the-i18n-mcp

Overview Schema Source Related Servers Discussions Admin

Get Translation Status

get_translation_status

Read-only

Check translation status across locales and layers: get counts of total, translated, missing, and empty keys plus overall completion percentage. Avoid manual counting.

Instructions

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.

Input Schema

TableJSON Schema

Name	Required	Description
`layer`	No	Layer name to scope this to (e.g., "root", "app-admin"). If omitted, every layer is included. Call discover to list the layers.
`listEmpty`	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`	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`	No	Absolute path to the project root. Defaults to I18N_PROJECT_DIR, then server cwd. Example: "/home/user/my-app".
`referenceLocale`	No	Locale code used as the source of truth (e.g., "en", "en-US"). Defaults to the project default locale.

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedv1.0.6Sep 12, 2026

changedInput schema / properties / layer / description

Previous value: -"Layer name to scan (e.g., \"root\", \"app-admin\"). If omitted, scans all layers."New value: +"Layer name to scope this to (e.g., \"root\", \"app-admin\"). If omitted, every layer is included. Call discover to list the layers."

addedInput schema / properties / listEmpty

Added value: +{
+  "description": "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.",
+  "type": "boolean"
+}

changedInput schema / properties / outputFile / description

Previous value: -"Absolute path to write the full per-locale and per-layer breakdown. Returns only the summary to the caller."New value: +"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\""

changedInput schema / properties / projectDir / description

Previous value: -"Absolute path to the project root. Defaults to I18N_PROJECT_DIR, then server cwd."New value: +"Absolute path to the project root. Defaults to I18N_PROJECT_DIR, then server cwd. Example: \"/home/user/my-app\"."

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "anyOf": [
+    {
+      "additionalProperties": false,
+      "properties": {
+        "empty": {
+          "additionalProperties": {
+            "additionalProperties": {
+              "description": "Dot-path keys of that layer.",
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            },
+            "propertyNames": {
+              "description": "Layer name.",
+              "type": "string"
+            },
+            "type": "object"
+          },
+          "description": "Locale → layer → the keys behind summary.emptyKeys. Present only when the caller asked for them.",
+          "propertyNames": {
+            "description": "Locale code.",
+            "type": "string"
+          },
+          "type": "object"
+        },
+        "emptyInReference": {
+          "additionalProperties": {
+            "description": "Dot-path keys of that layer.",
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          },
+          "description": "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.",
+          "propertyNames": {
+            "description": "Layer name.",
+            "type": "string"
+          },
+          "type": "object"
+        },
+        "layers": {
+          "description": "Coverage per layer, summed over the locales checked.",
+          "items": {
+            "additionalProperties": false,
+            "properties": {
+              "completion": {
+                "description": "translated ÷ total as a percentage, 0–100.",
+                "type": "number"
+              },
+              "consumedBy": {
+                "description": "Apps whose declared layers include this one. Empty means either no app information exists or nothing consumes the layer.",
+                "items": {
+                  "type": "string"
+                },
+                "type": "array"
+              },
+              "empty": {
+                "description": "Of those, the ones present with an empty-string value.",
+                "maximum": 9007199254740991,
+                "minimum": -9007199254740991,
+                "type": "integer"
+              },
+              "layer": {
+                "description": "Layer name.",
+                "type": "string"
+              },
+              "missing": {
+                "description": "Of those, the ones absent from the locale file.",
+                "maximum": 9007199254740991,
+                "minimum": -9007199254740991,
+                "type": "integer"
+              },
+              "stale": {
+                "description": "Keys of this layer, over the locales checked, whose value was written from source text that has changed since. Present only when a translation memory lockfile exists.",
+                "maximum": 9007199254740991,
+                "minimum": -9007199254740991,
+                "type": "integer"
+              },
+              "total": {
+                "description": "Keys the reference locale defines in this layer, times the locales checked.",
+                "maximum": 9007199254740991,
+                "minimum": -9007199254740991,
+                "type": "integer"
+              },
+              "translated": {
+                "description": "Of those, the ones holding a non-empty value.",
+                "maximum": 9007199254740991,
+                "minimum": -9007199254740991,
+                "type": "integer"
+              }
+            },
+            "required": [
+              "layer",
+              "total",
+              "translated",
+              "missing",
+              "empty",
+              "completion",
+              "consumedBy"
+            ],
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "locales": {
+          "description": "Coverage per locale, protected locales included and marked.",
+          "items": {
+            "additionalProperties": false,
+            "properties": {
+              "code": {
+                "description": "Canonical locale code, e.g. \"en-US\". This is the spelling to pass back to another call.",
+                "type": "string"
+              },
+              "completion": {
+                "description": "translated ÷ total as a percentage, 0–100.",
+                "type": "number"
+              },
+              "empty": {
+                "description": "Keys present with an empty-string value — scaffolded and never filled. They render as nothing, and are never reported as missing.",
+                "maximum": 9007199254740991,
+                "minimum": -9007199254740991,
+                "type": "integer"
+              },
+              "excludedFromOverall": {
+                "const": true,
+                "description": "Present when the locale is kept out of summary.completionPercent, which is what protection means for the overall figure.",
+                "type": "boolean"
+              },
+              "file": {
+                "description": "Locale file name, e.g. \"en-US.json\". Absent for directory-per-locale layouts such as Laravel.",
+                "type": "string"
+              },
+              "language": {
+                "description": "BCP-47 language tag, e.g. \"en-GB\". Absent when the framework config carries none.",
+                "type": "string"
+              },
+              "missing": {
+                "description": "Keys absent from this locale's files.",
+                "maximum": 9007199254740991,
+                "minimum": -9007199254740991,
+                "type": "integer"
+              },
+              "name": {
+                "description": "Human-readable language name, e.g. \"Deutsch\". Absent unless the framework config names one.",
+                "type": "string"
+              },
+              "protected": {
+                "const": true,
+                "description": "Present when the locale is listed in protectedLocales, so translation leaves it alone.",
+                "type": "boolean"
+              },
+              "stale": {
+                "description": "Keys whose value was written from source text that has changed since, per the translation memory. Present only when a lockfile exists; translate with overwriteStale refreshes them.",
+                "maximum": 9007199254740991,
+                "minimum": -9007199254740991,
+                "type": "integer"
+              },
+              "total": {
+                "description": "Keys the reference locale defines in the scanned layers.",
+                "maximum": 9007199254740991,
+                "minimum": -9007199254740991,
+                "type": "integer"
+              },
+              "translated": {
+                "description": "Keys this locale holds a non-empty value for.",
+                "maximum": 9007199254740991,
+                "minimum": -9007199254740991,
+                "type": "integer"
+              }
+            },
+            "required": [
+              "code",
+              "total",
+              "translated",
+              "missing",
+              "empty",
+              "completion"
+            ],
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "summary": {
+          "additionalProperties": false,
+          "description": "Project-wide coverage in one object. This is what comes back when the full result is diverted to a file.",
+          "properties": {
+            "completionPercent": {
+              "description": "Overall completion, 0–100, protected locales excluded. The counter the completion gate reads.",
+              "type": "number"
+            },
+            "emptyKeys": {
+              "description": "Of those, the ones present with an empty-string value.",
+              "maximum": 9007199254740991,
+              "minimum": -9007199254740991,
+              "type": "integer"
+            },
+            "layersScanned": {
+              "description": "Layer names the scan covered.",
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            },
+            "localesChecked": {
+              "description": "Number of locales measured, protected ones included.",
+              "maximum": 9007199254740991,
+              "minimum": -9007199254740991,
+              "type": "integer"
+            },
+            "missingKeys": {
+              "description": "Of those, the ones absent from their locale file.",
+              "maximum": 9007199254740991,
+              "minimum": -9007199254740991,
+              "type": "integer"
+            },
+            "protectedLocales": {
+              "description": "Canonical codes kept out of the overall figure because they are maintained by hand.",
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            },
+            "referenceLocale": {
+              "additionalProperties": false,
+              "description": "The locale coverage was measured against.",
+              "properties": {
+                "code": {
+                  "description": "Canonical locale code, e.g. \"en-US\". This is the spelling to pass back to another call.",
+                  "type": "string"
+                },
+                "file": {
+                  "description": "Locale file name, e.g. \"en-US.json\". Absent for directory-per-locale layouts such as Laravel.",
+                  "type": "string"
+                },
+                "language": {
+                  "description": "BCP-47 language tag, e.g. \"en-GB\". Absent when the framework config carries none.",
+                  "type": "string"
+                },
+                "name": {
+                  "description": "Human-readable language name, e.g. \"Deutsch\". Absent unless the framework config names one.",
+                  "type": "string"
+                }
+              },
+              "required": [
+                "code"
+              ],
+              "type": "object"
+            },
+            "staleCount": {
+              "description": "Of those, the ones written from source text that has changed since, per the translation memory. Present only when a lockfile exists.",
+              "maximum": 9007199254740991,
+              "minimum": -9007199254740991,
+              "type": "integer"
+            },
+            "totalKeys": {
+              "description": "Keys expected across every checked locale and layer.",
+              "maximum": 9007199254740991,
+              "minimum": -9007199254740991,
+              "type": "integer"
+            },
+            "translatedKeys": {
+              "description": "Of those, the ones holding a non-empty value.",
+              "maximum": 9007199254740991,
+              "minimum": -9007199254740991,
+              "type": "integer"
+            },
+            "unconsumedLayers": {
+              "description": "Scanned layers no app consumes — keys nothing can render. Empty unless the project declares more than one app.",
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            }
+          },
+          "required": [
+            "referenceLocale",
+            "layersScanned",
+            "unconsumedLayers",
+            "localesChecked",
+            "protectedLocales",
+            "totalKeys",
+            "translatedKeys",
+            "missingKeys",
+            "emptyKeys",
+            "completionPercent"
+          ],
+          "type": "object"
+        }
+      },
+      "required": [
+        "locales",
+        "layers",
+        "summary"
+      ],
+      "type": "object"
+    },
+    {
+      "additionalProperties": false,
+      "properties": {
+        "reportFile": {
+          "description": "Absolute path the full JSON result was written to. Read the file for the findings; the summary below is all that came back.",
+          "type": "string"
+        },
+        "summary": {
+          "additionalProperties": false,
+          "description": "The counts from the full result, so a caller can act on them without reading the file.",
+          "properties": {
+            "completionPercent": {
+              "description": "Overall completion, 0–100, protected locales excluded. The counter the completion gate reads.",
+              "type": "number"
+            },
+            "emptyKeys": {
+              "description": "Of those, the ones present with an empty-string value.",
+              "maximum": 9007199254740991,
+              "minimum": -9007199254740991,
+              "type": "integer"
+            },
+            "layersScanned": {
+              "description": "Layer names the scan covered.",
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            },
+            "localesChecked": {
+              "description": "Number of locales measured, protected ones included.",
+              "maximum": 9007199254740991,
+              "minimum": -9007199254740991,
+              "type": "integer"
+            },
+            "missingKeys": {
+              "description": "Of those, the ones absent from their locale file.",
+              "maximum": 9007199254740991,
+              "minimum": -9007199254740991,
+              "type": "integer"
+            },
+            "protectedLocales": {
+              "description": "Canonical codes kept out of the overall figure because they are maintained by hand.",
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            },
+            "referenceLocale": {
+              "additionalProperties": false,
+              "description": "The locale coverage was measured against.",
+              "properties": {
+                "code": {
+                  "description": "Canonical locale code, e.g. \"en-US\". This is the spelling to pass back to another call.",
+                  "type": "string"
+                },
+                "file": {
+                  "description": "Locale file name, e.g. \"en-US.json\". Absent for directory-per-locale layouts such as Laravel.",
+                  "type": "string"
+                },
+                "language": {
+                  "description": "BCP-47 language tag, e.g. \"en-GB\". Absent when the framework config carries none.",
+                  "type": "string"
+                },
+                "name": {
+                  "description": "Human-readable language name, e.g. \"Deutsch\". Absent unless the framework config names one.",
+                  "type": "string"
+                }
+              },
+              "required": [
+                "code"
+              ],
+              "type": "object"
+            },
+            "staleCount": {
+              "description": "Of those, the ones written from source text that has changed since, per the translation memory. Present only when a lockfile exists.",
+              "maximum": 9007199254740991,
+              "minimum": -9007199254740991,
+              "type": "integer"
+            },
+            "totalKeys": {
+              "description": "Keys expected across every checked locale and layer.",
+              "maximum": 9007199254740991,
+              "minimum": -9007199254740991,
+              "type": "integer"
+            },
+            "translatedKeys": {
+              "description": "Of those, the ones holding a non-empty value.",
+              "maximum": 9007199254740991,
+              "minimum": -9007199254740991,
+              "type": "integer"
+            },
+            "unconsumedLayers": {
+              "description": "Scanned layers no app consumes — keys nothing can render. Empty unless the project declares more than one app.",
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            }
+          },
+          "required": [
+            "referenceLocale",
+            "layersScanned",
+            "unconsumedLayers",
+            "localesChecked",
+            "protectedLocales",
+            "totalKeys",
+            "translatedKeys",
+            "missingKeys",
+            "emptyKeys",
+            "completionPercent"
+          ],
+          "type": "object"
+        }
+      },
+      "required": [
+        "reportFile",
+        "summary"
+      ],
+      "type": "object"
+    }
+  ],
+  "type": "object"
+}

Addedv1.0.3Aug 19, 2026

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only declare readOnlyHint/openWorldHint, so the description carries the real behavioral detail: empty-string values count as untranslated and never appear as missing, protectedLocales are reported but excluded from the overall figure, and stale keys plus staleCount behavior are disclosed. This is rich context beyond safety annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core outcome, then layers in edge cases in dense, purposeful sentences. It is long but nearly every clause adds decision-relevant information; minor density rather than waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need no explanation. The description covers the edge cases an agent must know (empty strings, protected locales, stale keys) and the routing to siblings, leaving nothing material unaddressed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% so the baseline is 3, but the description adds real meaning beyond the schema — it explains what listEmpty surfaces and when it is useful (after a scaffold or interrupted run) and clarifies the empty-vs-missing distinction that governs the counts.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: per-locale and per-layer counts of total/translated/missing/empty keys plus an overall completion percentage. It explicitly distinguishes itself from the sibling get_missing_translations by offering the aggregate in one call.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Names the alternative it replaces ('instead of calling get_missing_translations per layer and counting keys yourself') and routes the agent to the right follow-up ('translate with overwriteStale refreshes them'). Conditions for using listEmpty and outputFile are given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server