use-ai-i18n-mcp

Use ai-i18n MCP

Use the locate → scan when needed → list → update → verify workflow. Do not scan for i18n directories or edit generated files manually while the MCP tools are available.

Read the right source

For product behavior, generated-file guidance, or integration troubleshooting, read https://bosens-china.github.io/ai-i18n/llms.txt and then the one relevant page. Do not load llms-full.txt by default or duplicate that guidance in this Skill.

For Agent registration, MCP setup, Codex-only plugin installation, and prompt templates, read registration.

For MCP calls, read Tool contracts before the first call. It is the Agent-only authority for message identity, inputs, pagination, batch behavior, write boundaries, and authorization. Read Error recovery only after a returned next_action is insufficient, when a tool or protocol file is unavailable, or when DUPLICATE_JSON_KEY requires an approved protocol-file repair.

Locate the target app

1. Identify the Vite app the user wants to change. In a monorepo, do not treat the repository root or a similarly named i18n/ directory as the target.
2. Read the app's package.json, package scripts, and vite.config.* as text. Do not execute the Vite config merely to locate the app; the explicit scan step below loads it.
3. Resolve Vite root from the command's working directory. Resolve a relative aiI18n({ directory }) against that root; use an absolute directory unchanged. The default directory is i18n.
4. Pass the resulting absolute path as i18n_directory.

If more than one Vite app is plausible, ask the user which app to use before calling MCP. The app's framework mode and autoImport setting affect source integration but do not change the MCP directory contract. Do not add or remove Runtime imports as part of a translation-only MCP task. Dev may inline ordinary static named Runtime imports, while Build keeps its static registration modules; neither behavior makes browser-driven Dev extraction cover unvisited pages. When package installation, Vite configuration, or Runtime source integration is incomplete or requested, use the integrate-ai-i18n Skill before starting this translation workflow.

The selected app's extracted set includes every reachable local workspace source processed by that Vite build. Treat source-only packages as source_files within the consuming app, not as separate MCP targets. Never point two Vite builds at one i18n directory; call the tools once per selected app. Use tool-returned source_file values; never decode or guess a source path from a physical filename.

For first use, a complete translation audit, or stale extraction after source, branch, or configuration changes, follow Entry scan and Skill-only translation. Prefer the Skill scan over a full Build. Repeat the helper after source edits and before final verification; it decides whether extraction can be reused. Never edit Translation Memory storage directly. If Host MCP is unavailable, the same reference provides the Skill-only list/set path without registering a server. If the target app enables failOnMissingTranslations, a Build with remaining missing target-locale values fails after Provider work. Keep that gate enabled; scan and list missing entries here, fill them through the normal authorized workflow, then rerun the Build. A failed gated Build does not prove its application bundle was emitted.

When that app's Vite Dev Server is running, successful MCP Translation Memory or override writes are observed and applied to its in-memory Runtime through HMR, including occurrence-scoped override edits and deletions. This convenience does not make the Dev catalog a complete source set: ordinary full translation needs the entry scan above; destructive orphan decisions still require a full Build. Do not restart Dev or edit generated locale files merely to expose an MCP write.

When the target explicitly registers aiI18nReview(), its Vite Dev console is the preferred interface for a person interactively choosing a small number of review values. Use the in-page launcher when page context or element picking matters; use the printed /__ai-i18n/ URL for all-page review. The URL remains available when printUrl: false, and the launcher may be absent when launcher: false. Its in-page picker may resolve a static HTML element directly to one occurrence; when runtime-rendered copy has multiple candidates, the person must choose the exact file, line, and column rather than accepting an inferred first match. This Skill remains the authority when an Agent performs batch work, automates writes, audits the complete extracted set, or acts on explicit user-approved wording. The embedded workbench's default current-page scope uses Dev results; switching to all copy ensures an entry-reachable catalog without Build; the standalone workbench starts with the same complete entry scan and has no page picker. Multiple picker matches enter a file and occurrence locate hierarchy instead of selecting the first result. Both paths write the same project overrides/ shards; do not run MCP review writes concurrently with an open review-console save operation.

Performance diagnosis and plugin on/off comparisons belong to integrate-ai-i18n. Startup/transform reports omit individual write stages and do not prove persistence completion. Reports are diagnostic artifacts outside the i18n protocol directory; they are not MCP inputs or evidence that a full extracted catalog exists. Do not change translations to address a timing anomaly.

When invoked by a plugin end check, follow Plugin end checks.

Execute the workflow

1. List missing translations with only the resolved i18n_directory on the first call.
2. Follow every page unless the user requested a sample or narrower scope.
3. Write ordinary translations without overwriting existing non-null values.
4. Clear automatic translations or change human review values only when the user explicitly requests or approves that action.
5. Repeat the matching list operation to verify the result.

Do not list or delete orphan messages during ordinary translation, review, or verification work. Enter the orphan workflow only when the user explicitly requests an orphan audit or cleanup. Run one full Build first, list every requested orphan, report the retained translations, and obtain explicit user approval before deleting the listed IDs. Do not treat an earlier general cleanup request as approval after the list changes or a selected message becomes active again.

Preserve product names, intentional whitespace, and every template token. Do not guess between conflicting non-empty values.

List items omit source_files by default. Keep that compact response for translation work; request include_source_files: true only when the user needs per-file impact or when an exact file filter must be prepared. When message.comment and project terminology do not disambiguate short copy, request include_occurrences: true, then read the nearby source lines for the returned files from the target workspace. Do not request occurrences for every batch by default or treat paths and locations as write identity for Translation Memory. For a user-approved file-scoped human review, copy exact returned source_file values into the override update's files. For an occurrence-scoped review, copy the exact source_file, 1-based line, and 0-based column into occurrences; this is the only scope that distinguishes repeated calls on one line. Never derive, shorten, or guess these values. When a tool fails, follow its returned next_action before consulting the recovery reference.

Report

Report the selected app and absolute i18n directory, added, overwritten, cleared or deleted, unchanged, remaining, and failed counts. Explain unresolved errors in the user's language without exposing internal message IDs.