How the Egonex-AI Localization System Works: A Complete Guide to the --language Flag

The --language flag controls the output language for all textual artifacts by updating the outputLanguage setting in .understand-anything/config.json and injecting a language directive into the LLM prompt pipeline.

The Egonex-AI/Understand-Anything repository provides a sophisticated localization system that adapts knowledge-graph outputs, dashboard UIs, and guided tours to the user's preferred language. At the heart of this system lies the --language flag, which orchestrates a multi-step precedence chain to determine how text is generated and persisted across sessions.

Understanding the --language Processing Pipeline

The flag’s behavior is defined in the skill prompt for the /understand command within understand-anything-plugin/skills/understand/SKILL.md. The processing follows a strict execution order from argument parsing to locale-specific guidance injection.

Argument Parsing and Code-Friendly Normalization

When you invoke the /understand command, the skill prompt extracts --language <lang> from the $ARGUMENTS variable [lines 42-44]. Friendly language names like "chinese" or "japanese" are automatically normalized to ISO-639-1 codes (zh, ja) and locale variants such as zh-TW or pt-BR [lines 44-45].

Precedence Resolution Logic

The system resolves the final output language through a strict three-tier precedence chain:

1. Flag wins – If the --language flag is present, the requested language immediately becomes the active setting and is stored as outputLanguage in $PROJECT_ROOT/.understand-anything/config.json [lines 51-53].
2. Stored preference – If no flag is provided, the engine first checks the config file for an existing outputLanguage value [lines 46-47].
3. First-run detection – When neither flag nor config exists, the system attempts to infer the language from $DETECTED_LANG. If the detection yields English (en) or fails, it defaults silently to en. Otherwise, it prompts the user once to confirm or override the detected language [lines 48-50].

Configuration Persistence

Once resolved, the system always writes the final language code back to .understand-anything/config.json under the outputLanguage key [lines 50-52]. This persistence ensures subsequent invocations reuse the stored preference without requiring the flag again.

Language Directive Injection

The pipeline populates a $LANGUAGE_DIRECTIVE Markdown template with the resolved language code and injects it into the LLM analysis prompt [lines 54-57]. This directive instructs the model to generate all textual output—including knowledge-graph node titles, descriptions, and dashboard labels—in the specified language.

Locale-Specific Style Guidelines

For non-English outputs, the system appends additional context from ./locales/<code>.md files under a ## Output Language Guidelines header [lines 430-437]. These files provide concrete style hints and cultural conventions that improve translation quality for knowledge-graph nodes and UI elements.

Practical Usage Examples

The following commands demonstrate how to leverage the flag across different scenarios:

# Generate all output in Simplified Chinese (zh)

/understand --language zh

# Use Traditional Chinese (zh‑TW) – dashboard UI and node text will be in zh-TW

/understand --language zh-TW

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

# Subsequent runs can omit the flag

/understand --language ja

# No flag: first run detects conversation language, asks once, then stores it

/understand

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

Key Implementation Files

The localization logic spans several critical files in the repository:

• understand-anything-plugin/skills/understand/SKILL.md – Defines argument parsing, precedence rules, persistence logic, and the injection of locale files [lines 42-57, 430-437].
• .understand-anything/config.json – Stores the persistent outputLanguage value at the project root, merged with existing settings [lines 50-53].
• understand-anything-plugin/packages/dashboard/src/locales/*.ts – TypeScript locale modules (e.g., zh.ts, ja.ts) consulted when the output language is not English.
• ./locales/<code>.md – Markdown guidance files appended to prompts for locale-specific styling [lines 430-437].
• README.md – User-facing documentation summarizing the flag behavior and first-run detection [lines 28-35].

Summary

• The Egonex-AI localization system uses a precedence chain (flag → config → detection) to determine output language.
• The --language flag normalizes friendly names to ISO codes and updates .understand-anything/config.json immediately [lines 42-53].
• Language directives are injected into LLM prompts via $LANGUAGE_DIRECTIVE to control generation [lines 54-57].
• Non-English outputs incorporate style guidelines from ./locales/<code>.md to ensure quality translations [lines 430-437].
• All settings persist automatically, making subsequent runs flag-optional once configured.

Frequently Asked Questions

What happens if I don't use the --language flag on my first run?

If you omit the flag and no outputLanguage exists in config.json, the system attempts to detect your conversation language from $DETECTED_LANG. It defaults silently to English (en) if detection fails or returns English; otherwise, it prompts you once to confirm the detected language before storing it permanently in the configuration file [lines 48-50].

Can I use friendly language names like "chinese" instead of ISO codes?

Yes. The skill prompt automatically normalizes friendly names to ISO-639-1 codes (e.g., "chinese" → zh, "japanese" → ja) and handles locale variants like zh-TW or pt-BR transparently during the argument processing phase [lines 44-45].

Where is my language preference stored?

The resolved language is written to $PROJECT_ROOT/.understand-anything/config.json under the outputLanguage key. The system merges this value with existing settings, ensuring your preference persists across sessions and projects [lines 50-52].

How does the system handle translation quality for non-English outputs?

When the output language is not English, the pipeline reads a locale-specific Markdown file from ./locales/<code>.md and appends it to the prompt under a ## Output Language Guidelines header. This provides the LLM with concrete stylistic and cultural guidance specific to that language, improving the quality of generated summaries and UI text [lines 430-437].

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