How to Add Support for New Languages in OpenDeepWiki Translation Service

You can add support for new languages in OpenDeepWiki by appending ISO-639-1 codes to the WIKI_LANGUAGES environment variable or WikiGeneratorOptions.Languages configuration, which the TranslationWorker automatically detects to generate translation tasks for existing repository branches.

OpenDeepWiki is an open-source multilingual wiki generator that leverages AI translation models to create localized documentation from repository source code. Adding support for new languages requires minimal configuration changes to extend the language list, as the translation pipeline automatically handles task creation, deduplication, and processing for any supported language code you specify.

Understanding the Language Configuration Architecture

WikiGeneratorOptions and the Default Language List

The language configuration resides in WikiGeneratorOptions, located at src/OpenDeepWiki/Services/Wiki/WikiGeneratorOptions.cs. This class maintains a comma-separated string of language codes that defines which translations the system generates.

public string? Languages { get; set; } = "en,zh,ja,ko";   // src/OpenDeepWiki/Services/Wiki/WikiGeneratorOptions.cs

The default configuration targets English (en), Chinese (zh), Japanese (ja), and Korean (ko). The GetTranslationLanguages method processes this string to filter out the primary language and return the target translation codes:

return Languages
    .Split(',', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries)
    .Select(l => l.ToLowerInvariant())
    .Where(l => !string.Equals(l, primaryLanguage, StringComparison.OrdinalIgnoreCase))
    .Distinct()
    .ToList();                                   // src/OpenDeepWiki/Services/Wiki/WikiGeneratorOptions.cs (lines 160-172)

Configuration Sources and Priority

OpenDeepWiki reads language settings from multiple sources with the following precedence, as implemented in src/OpenDeepWiki/Program.cs:

1. Environment Variable: WIKI_LANGUAGES overrides all other settings
2. Configuration Section: WikiGenerator:Languages in appsettings.json
3. Default Value: The hardcoded fallback in WikiGeneratorOptions

The binding logic in Program.cs (lines 57-63) demonstrates this priority:

builder.Services.AddOptions<WikiGeneratorOptions>()
    .Bind(builder.Configuration.GetSection(WikiGeneratorOptions.SectionName))
    .PostConfigure(options =>
    {
        var languages = builder.Configuration["WIKI_LANGUAGES"];
        if (!string.IsNullOrWhiteSpace(languages))
        {
            options.Languages = languages;    // src/OpenDeepWiki/Program.cs (lines 57-63)
        }
    });

Step-by-Step Guide to Adding New Languages

Step 1: Update the Language Configuration

To add support for a new language, append its ISO-639-1 code to the comma-separated list. For example, to add French (fr) and German (de), update your environment variable:

# .env file or docker-compose.yml

WIKI_LANGUAGES=en,zh,ja,ko,fr,de

Alternatively, modify appsettings.json:

{
  "WikiGenerator": {
    "Languages": "en,zh,ja,ko,fr,de"
  }
}

Step 2: Restart the Service

The WikiGeneratorOptions are bound at application startup in Program.cs. You must restart the OpenDeepWiki service for the new language list to take effect. If running in Docker:

docker-compose restart opendeepwiki

Step 3: Verify Translation Model Support

Ensure your configured translation model supports the new language codes. The translation endpoint and model are specified in WikiGeneratorOptions:

• TranslationModel: The AI model identifier (falls back to ContentModel if not set)
• TranslationEndpoint: The API endpoint for translation services

If your model requires language-specific prompt templates, add them under the prompts/ directory (e.g., translate_fr.txt for French-specific instructions).

How the Translation Pipeline Processes New Languages

The TranslationWorker Polling Mechanism

The TranslationWorker (implemented in src/OpenDeepWiki/Services/Translation/TranslationWorker.cs) executes every 30 seconds to scan for completed repository branches. When it detects a branch with a primary language, it calls GetTranslationLanguages to determine which target languages need translation tasks.

Automatic Task Creation and Deduplication

For each target language not yet present in the branch, the worker creates a TranslationTask entity:

var translationLanguages = wikiOptions.GetTranslationLanguages(branchLanguage.LanguageCode);
...
var task = new TranslationTask { /* … */ };
context.TranslationTasks.Add(task);              // src/OpenDeepWiki/Services/Translation/TranslationWorker.cs (lines 126-134, 184-195)

The system automatically handles deduplication. If a task already exists (pending, processing, or failed), the worker either reuses the existing task or resets it according to its current status, preventing duplicate translation work.

Advanced: Manual Task Creation and Customization

Creating Translation Tasks Programmatically

For on-demand translations, inject ITranslationService and call CreateTaskAsync:

// Inject ITranslationService (e.g. in a controller)
public async Task<ActionResult> TranslateBranch(string repoId, string branchId, string sourceLang, string targetLang)
{
    var task = await _translationService.CreateTaskAsync(
        repositoryId: repoId,
        repositoryBranchId: branchId,
        sourceBranchLanguageId: sourceLang,
        targetLanguageCode: targetLang);

    if (task == null)
    {
        return BadRequest("Task already exists or target language already present.");
    }

    return Ok(task);
}

This approach bypasses the automatic polling interval and immediately queues a translation for the specified language pair.

Adding Language-Specific Prompt Templates

If your translation model requires customized instructions for specific languages (e.g., formal vs. informal tone, technical terminology guidelines), create prompt template files in the prompts/ directory:

• translate_fr.txt for French-specific translation instructions
• translate_de.txt for German-specific guidelines

The WikiGenerator loads these templates based on the target language code when executing TranslateWikiAsync in src/OpenDeepWiki/Services/Wiki/WikiGenerator.cs.

Summary

• Configuration-driven: Add new languages by updating the comma-separated WIKI_LANGUAGES environment variable or WikiGeneratorOptions.Languages setting—no code changes required.
• Automatic pipeline: The TranslationWorker automatically detects new languages in the configuration and creates translation tasks for all existing repository branches.
• Deduplication built-in: The system prevents duplicate tasks by checking existing task statuses before creating new ones.
• Extensible: Use ITranslationService.CreateTaskAsync for manual translations and custom prompt templates for language-specific translation guidelines.

Frequently Asked Questions

What language codes does OpenDeepWiki support?

OpenDeepWiki accepts any ISO-639-1 two-letter language code (e.g., fr, de, es) or other identifiers supported by your configured translation model. The system validates codes by splitting the comma-separated Languages string in WikiGeneratorOptions, but delegates actual translation capability to the underlying AI model configured in TranslationModel or ContentModel.

Do I need to modify the source code to add a new language?

No. Adding support for new languages in OpenDeepWiki requires only configuration changes. Append the new language code to the WIKI_LANGUAGES environment variable or update the WikiGenerator:Languages setting in appsettings.json. The TranslationWorker and WikiGenerator automatically incorporate the new language without requiring code modifications or redeployment beyond a service restart.

How long does it take for translations to appear after adding a language?

Translations begin processing immediately after the service restarts and the TranslationWorker completes its next polling cycle (every 30 seconds). For each existing completed branch, the worker creates a TranslationTask for the new language. Processing time depends on the size of the repository, the AI model's response time, and queue depth, but tasks appear in the database immediately upon creation.

Can I use a different translation model for specific languages?

Yes, though this requires code customization. By default, all translations use the model specified in WikiGeneratorOptions.TranslationModel (falling back to ContentModel). To implement language-specific models, you would modify the WikiGenerator.TranslateWikiAsync method in src/OpenDeepWiki/Services/Wiki/WikiGenerator.cs to select a model based on the targetLanguageCode parameter, or extend ITranslationService to support model routing logic.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}