How Language Localization Works with the `--language` Flag in Egonex-AI Understand Anything

The --language flag controls the output language for all textual artifacts by normalizing input to ISO-639-1 codes, persisting the choice in config.json, and injecting a language directive into the LLM prompt that generates localized node descriptions, UI labels, and guided tours.

The Egonex-AI/Understand-Anything repository provides a comprehensive localization system that adapts knowledge graphs, dashboards, and documentation to different languages through a single command-line flag. Understanding how the --language flag processes user preferences, resolves precedence rules, and influences the LLM pipeline ensures you can generate consistent multilingual output across your projects.

Argument Parsing and Code-Friendly Normalization

The localization logic begins in understand-anything-plugin/skills/understand/SKILL.md, where the skill prompt extracts --language <lang> from the $ARGUMENTS environment variable (lines 42-44).

Friendly name mapping occurs immediately after extraction (lines 44-45). The system converts human-readable language names—such as "chinese", "japanese", or "portuguese"—into standardized ISO-639-1 codes (zh, ja, pt). It also handles locale variants including zh-TW for Traditional Chinese and pt-BR for Brazilian Portuguese, ensuring the LLM receives machine-readable language identifiers regardless of how the user expresses their preference.

Language Resolution Precedence

The system resolves the final output language through a strict three-tier hierarchy defined in the skill prompt:

1. Flag takes precedence – When --language is explicitly provided, the value is immediately stored as outputLanguage in $PROJECT_ROOT/.understand-anything/config.json, merging with any existing configuration settings (lines 51-53).

2. Stored configuration – If no flag is present, the engine checks the config file first. If outputLanguage exists from a previous run, that value is used automatically (lines 46-47).

3. First-run detection – When neither flag nor config exists, the system attempts to infer the user's language from $DETECTED_LANG. If detection yields English (en) or fails entirely, it defaults to en silently. For non-English detections, the user receives a one-time prompt to confirm or override the detected language before proceeding (lines 48-50).

Persistence and Configuration Storage

Once resolved, the language preference is always persisted to ensure subsequent runs remain consistent. The skill prompt writes the final outputLanguage value back to .understand-anything/config.json (lines 50-52), creating a permanent project setting that eliminates the need for repeated flag usage. This persistence mechanism means that after your first explicit setting or successful auto-detection, the system remembers your preference indefinitely.

LLM Prompt Integration and Locale Guidance

The resolved language influences the LLM through two distinct injection points:

Language directive template – A Markdown snippet stored in $LANGUAGE_DIRECTIVE is populated with the final ISO code and injected into the analysis prompt (lines 54-57). This directive instructs the underlying model to generate all summaries, descriptions, and explanations in the specified language.

Locale-specific guidance – For non-English outputs, the system appends additional style instructions from ./locales/<code>.md files under a ## Output Language Guidelines header (lines 430-437). These files provide concrete linguistic hints—such as formality levels, technical terminology preferences, and grammatical structures—ensuring the output matches cultural expectations for the target locale.

Impact on Generated Artifacts

The --language flag affects every textual component produced by the pipeline:

• Knowledge graph nodes – Node titles and descriptions are generated in the target language
• Dashboard UI – All labels, tooltips, buttons, and navigation elements in understand-anything-plugin/packages/dashboard/src/locales/*.ts are rendered according to the resolved locale
• Guided tours – Onboarding materials and interactive explanations match the selected language

Practical Usage Examples

Use these patterns to control localization in your workflows:

# Generate all output in Simplified Chinese (zh)

/understand --language zh

# Use Traditional Chinese (zh-TW) for dashboard UI and node text

/understand --language zh-TW

# Switch to Japanese for a new project (updates config.json)

/understand --language ja

# Subsequent runs can omit the flag after initial configuration

/understand

On first run without a flag, the system detects your conversation language and prompts for confirmation:

/understand

# → "Detected language: 中文 (zh). Generate all output in zh? (yes/override)"

Summary

• The --language flag is processed in SKILL.md by extracting $ARGUMENTS and normalizing friendly names to ISO-639-1 codes
• Resolution follows strict precedence: flag > stored config > auto-detection > English default
• Preferences persist in .understand-anything/config.json under the outputLanguage key
• The system injects a $LANGUAGE_DIRECTIVE into LLM prompts and appends locale-specific guidance from ./locales/<code>.md files
• All output artifacts—including knowledge graphs, dashboard UI, and guided tours—respect the resolved language setting

Frequently Asked Questions

What happens if I run /understand without the --language flag?

If you omit the flag, the system first checks .understand-anything/config.json for an existing outputLanguage value. If found, it uses that stored preference. If this is your first run and no config exists, it attempts to detect your conversation language from $DETECTED_LANG. Detection failures or English conversations default to en silently, while non-English detections trigger a one-time confirmation prompt before persisting the choice.

How does the system handle locale variants like Traditional Chinese versus Simplified Chinese?

The normalization logic in SKILL.md (lines 44-45) maps friendly names to both base ISO-639-1 codes and specific locale variants. You can pass zh-TW for Traditional Chinese or pt-BR for Brazilian Portuguese, and the system preserves these exact codes in the configuration and LLM directives, ensuring locale-specific terminology and conventions are respected throughout the output.

Where is my language preference stored, and can I manually edit it?

The preference is stored as outputLanguage in $PROJECT_ROOT/.understand-anything/config.json. You can manually edit this JSON file to change languages without using the CLI flag, or delete the entry to trigger the first-run detection behavior again on the next execution.

Can I switch languages for an existing project without losing previous work?

Yes. Running /understand --language <new-code> updates the config.json file immediately and applies the new language to all subsequent generated content. Previous knowledge graph structures remain intact, though node descriptions and UI labels will regenerate in the new language during the next analysis cycle.

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