translate_missing
Find the keys missing in the target locales and translate them. Without a translation backend nothing is written: the result carries per-locale fallback contexts to translate by hand instead. Two modes: in provider mode (the server env-configured with I18N_PROVIDER, I18N_MODEL and an API key) it calls the LLM provider directly and writes the results; in agent mode it returns those fallbackContexts — translate them inline and persist via write_translations. Check the discover output for the active mode. Uses the project config (glossary, translation prompt, locale notes, examples) where there is one. Translates all locales concurrently, so pass every target locale at once.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
layer | string | no | Layer to translate (e.g., "root", "app-admin"). Omit to translate every locale-backed layer in one call — the recommended default for layered projects, which returns a result per layer plus an aggregated summary. |
referenceLocale | string | no | Locale code used as the translation source (e.g., "en", "en-US"). Defaults to the project default locale. |
targetLocales | string[] | no | Locale codes to translate into (e.g., "de", "fr", "sv"). Defaults to all locales except the reference. |
keys | string[] | no | Dot-path keys to translate (e.g., "auth.login.title", "common.save"). If omitted, translates every missing key in the layer. |
batchSize | integer | no | Maximum number of keys per provider request. Default: 50. A lower value reduces per-batch risk and increases round trips. |
overwriteStale | boolean | no | Also re-translate keys whose target value was written from source text that has changed since. Needs the translation memory, which is on unless translationMemory is false in the project config — without it nothing is known to be stale and this changes nothing. Default: false, which reports those keys under "stale" and leaves their values alone. |
dryRun | boolean | no | Return which keys would be translated without calling the provider or writing files. Default: false. |
compact | boolean | no | Return a compact summary (totalTranslated, totalFailed, byLocale) instead of full per-locale results. Default: false. |
projectDir | string | no | Absolute path to the project root. Defaults to I18N_PROJECT_DIR, then server cwd. Example: "/home/user/my-app". |
Result
| Field | Type | Description |
|---|---|---|
results | Record<string, object> | Full per-locale results. Absent in compact mode, which returns summary.byLocale instead. |
fallbackContexts | Record<string, Record<string, unknown>> | Per-locale context to translate inline and persist with write_translations. Present only in agent mode. |
summary | object | What the run did across every locale of the layer. |
layers | Record<string, object> | One full result per locale-backed layer. |
Behavior Hints
A host reads these to decide whether a call needs your confirmation first.
| Hint | Value |
|---|---|
readOnlyHint | false |
destructiveHint | false |
idempotentHint | true |
openWorldHint | true |
Paired CLI Command
The same operation runs from a terminal as the-i18n-cli translate, whose page documents its flags.