get_translation_status
Translation coverage in one call: per-locale and per-layer counts of total, translated, missing and empty keys, plus an overall completion percentage. Use this instead of calling get_missing_translations per layer and counting keys yourself. Empty-string values count as untranslated; set listEmpty to get the keys behind that count — they exist in the locale file, so they are never reported as missing, and they render as nothing in the UI. Locales listed in protectedLocales are reported but excluded from the overall figure, since they are maintained by hand. Where a translation memory lockfile exists, each locale and layer also carries stale — keys whose target was written from source text that has changed since — and the summary carries staleCount; translate with overwriteStale refreshes them.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
layer | string | no | Layer name to scope this to (e.g., "root", "app-admin"). If omitted, every layer is included. Call discover to list the layers. |
referenceLocale | string | no | Locale code used as the source of truth (e.g., "en", "en-US"). Defaults to the project default locale. |
listEmpty | boolean | no | Also list the keys behind summary.emptyKeys under "empty" (locale → layer → keys), and keys that are empty in the reference locale itself under "emptyInReference" — useful after a scaffold or an interrupted translation run. Default: false, which returns counts only. |
outputFile | string | no | Absolute path to write the full JSON output to. Only a compact summary is returned to the caller, which is what you want for a result too large to read in one piece. Example: ".i18n-reports/translation-status.json" |
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 |
|---|---|---|
locales | object[] | Coverage per locale, protected locales included and marked. |
layers | object[] | Coverage per layer, summed over the locales checked. |
empty | Record<string, Record<string, string[]>> | Locale → layer → the keys behind summary.emptyKeys. Present only when the caller asked for them. |
emptyInReference | Record<string, string[]> | Layer → keys whose value is empty in the reference locale itself, so there is nothing to translate from. Present only alongside empty, and only when there are any. |
summary | object | Project-wide coverage in one object. This is what comes back when the full result is diverted to a file. |
reportFile | string | Absolute path the full JSON result was written to. Read the file for the findings; the summary below is all that came back. |
Behavior Hints
A host reads these to decide whether a call needs your confirmation first.
| Hint | Value |
|---|---|
readOnlyHint | true |
openWorldHint | false |
Paired CLI Command
The same operation runs from a terminal as the-i18n-cli status, whose page documents its flags.