AI Localization Agent

Translate an i18n source file to one or more target languages using l10n.dev AI. Supports JSON, JSONC, Flutter ARB, YAML, PO (gettext), XLIFF, MD, and all other text-based localization formats. Format is auto-detected from the file extension. If sourceFile is omitted, scan the project for i18n source files. Common patterns to look for: - `locales/en.json`, `locales/en-US.json` (flat file-based) - `locales/en/common.json`, `locales/en/messages.json` (folder-based) - `locales/common.en.json`, `locales/en-US.common.json` (language code inside the file name) - `app_en.arb` (Flutter ARB) - `*.po`, `*.xliff`, `*.yaml` files with language-code naming - `ai-l10n.config.json` if it already exists (read it to find the declared source files) For each candidate source file found, call `l10n_detect_project_structure` and collect: - Structure type, source language code, and detected target languages - Which target files already exist on disk If no source files can be found, ask me which file to use before continuing. If targetLanguages is omitted, and if target languages are not detected, ask me for them. Show a brief summary of what was found before continuing. PRE-TRANSLATION CHECKS — perform all of these BEFORE calling translate: 1. LINGUISTIC INSTRUCTIONS: If the user has not mentioned tone, style, or brand voice in this conversation, call l10n_list_instructions first. Check whether a saved instruction exists for each requested target language pair (source → target). If instructions exist for OTHER language pairs but NOT the requested targets, mention this gap explicitly. Ask the user in one sentence: "No instruction found for [language(s)] — would you like to set a tone/style rule before translating? (e.g. formal, casual, keep brand terms untranslated)" If yes, call l10n_create_instruction and pass the instruction text back via the 'instruction' parameter. If no or they want to skip, proceed without it. 2. GLOSSARY: If generateGlossary was not explicitly set by the user, call l10n_list_glossaries and check whether an active glossary exists for the requested target language pairs. If glossaries exist for OTHER language pairs but NOT the requested targets, mention this gap. Then ask the user: "No glossary found for [language(s)] — enabling glossary generation saves key terms for consistent future translations (costs extra characters). Enable it for this run?" If yes, set generateGlossary: true. If no, proceed without it. Do this check BEFORE translating — do not suggest a rerun after the fact. 3. INCREMENTAL UPDATE: For JSON-based formats (.json, .jsonc, .arb) only: if the target language files already exist on disk and translateOnlyNewStrings was not explicitly set by the user, suggest enabling it: "Target files already exist — enable incremental mode to skip unchanged strings and save quota?" If yes, set translateOnlyNewStrings: true. 4. BALANCE: If the translation fails with paymentRequired (HTTP 402 / Insufficient balance), analyze the error message (it contains current balance and required balance). Suggest purchasing more characters at https://l10n.dev/#pricing 5. API KEY: If the error indicates unauthorized access or no API key, suggest creating a free account and API key at https://l10n.dev/ws/keys. Offer to store the key using the l10n_set_api_key tool. POST-TRANSLATION CHECKS — perform all of these AFTER calling translate: 1. USAGE DETAILS: Always present a character usage breakdown to the user. For each entry in results[], report the output file path (outputPath) and a cost breakdown from usageDetails — omit zero values and use these descriptive labels: - sourceStringsCharCount → "content" - glossaryCharCount → "glossary applied" - instructionCharCount → "linguistic instruction" - terminologyCharCount → "terminology" Then report total characters used and remaining balance. 2. FILTERED STRINGS: If filteredStringsP…

List all saved linguistic instructions for this l10n.dev account. Linguistic instructions guide AI translation style, tone, and brand voice (e.g. "Use formal tone", "Never translate the word Dashboard"). Call this before translating if the user hasn't specified tone preferences, to check whether instructions are already configured.

Create and save a new linguistic instruction for a source→target language pair. The instruction is stored in l10n.dev and applied automatically to future translations for that language pair (unless overridden per-request). Use this when the user wants to set a tone, style, or brand rule — for example after they answer the suggestion made during translation. Examples: - "Use formal tone (Sie, not du)" - "Keep product names Dashboard, Workspace, and Settings untranslated" - "Use simple, friendly language suitable for children"

Update the text, name, or active status of an existing linguistic instruction. Use to edit a previously saved instruction without deleting and recreating it. Setting isActive to true deactivates all other instructions for the same language pair.

Permanently delete a linguistic instruction. This cannot be undone. If the deleted instruction was active, no other instruction is automatically activated.

List all saved glossaries for this l10n.dev account. Each glossary maps source terms to preferred translations for a language pair. Active glossaries are applied automatically during translation. Call this when the user asks about their glossaries, or to check whether a glossary exists for a language pair before suggesting generateGlossary.

Get the full details and all term entries of a specific glossary by ID. Use when the user wants to review or audit the terms in a glossary.

Create a new empty glossary for a source→target language pair. After creating, use l10n_add_glossary_entry to add term mappings. Note: to auto-generate a glossary from a translation, use generateGlossary: true in l10n_translate_file instead.

Update the name or active status of an existing glossary. Setting isActive to true deactivates all other glossaries for the same language pair.

Permanently delete a glossary and all its term entries. This cannot be undone.

Add a term mapping to an existing glossary. Maps a source term to a preferred translation, with an optional context note for disambiguating polysemous terms (e.g. 'bank' = financial institution vs. river bank).

Remove a single term mapping from a glossary.

Check the remaining character balance for this l10n.dev account. Each translation consumes characters from the balance. Use this when the user asks how many characters they have left, or proactively if a translation result shows a low remaining balance. If balance is insufficient, suggest purchasing more characters at https://l10n.dev/#pricing

Store an l10n.dev API key locally in the user's home directory (~/.ai-l10n/config.json). Once stored, the key is used automatically by all l10n tools without needing to set L10N_API_KEY. Get a free API key at https://l10n.dev/ws/keys Use this when: - The user provides an API key and wants to save it - A translation fails with an authorization error and the user wants to persist their key Note: if L10N_API_KEY environment variable is set in the MCP config, that takes precedence over the stored key and this tool is not needed.

Check whether an l10n.dev API key is configured (via environment variable or stored config). Use this to diagnose authorization errors or to confirm the key is set up correctly.

Scan an i18n source file to understand the project's localization structure. Returns: structure type (folder-based, file-based or unknown), source language code, all detected target languages, and the resolved target file path for each language (showing whether files already exist). Structure types: - folder-based: a language-code directory per language (locales/en/common.json) - file-based: the language code is in the file name, either as the whole name (locales/en.json) or next to other parts (app_en.arb, locales/common.en.json, locales/en-US.common.json, locales/messages_en_US.properties). In the latter case the detected naming pattern is reported as well. Use this before translating or setting up automation to understand what source files and target languages are in place. Call with the path to the source language file (e.g. locales/en.json, app_en.arb, locales/en/common.json). If the structure comes back as unknown even though localization files exist, pass languageCodeRegex to describe the naming pattern.