the-i18n-mcp

Overview Schema Source Related Servers Discussions Admin

List Namespaces

list_namespaces

Read-only

Lists translation keys grouped by namespace prefix with counts per node. Use it to explore available keys, filter by layer or locale, and page large results without guessing path prefixes.

Instructions

List the translation key tree grouped by namespace prefix, with a count per namespace node. Use this to explore the available keys without guessing path prefixes. limit counts top-level namespace nodes across the scanned layers, each of which brings its whole subtree; totalNamespaces counts them all, whatever the limit let through.

Input Schema

TableJSON Schema

Name	Required	Description
`layer`	No	Layer name to filter by (e.g., "root", "app-admin"). If omitted or "*", scans all layers. Call discover to list the layers.
`limit`	No	Maximum number of top-level namespaces to return. Default: 100 for a tool call, unlimited at a terminal. When the cap applies the result carries truncated: true and nextOffset — call again with offset set to that value for the next page, or narrow the request instead.
`locale`	No	Locale code to read from (e.g., "en", "en-US"). Defaults to the project default locale. Keys are the same across locales, so one is enough.
`offset`	No	Number of top-level namespaces to skip before returning any. Default: 0. Pass the nextOffset of a truncated result to continue where it stopped.
`projectDir`	No	Absolute path to the project root. Defaults to I18N_PROJECT_DIR, then server cwd. Example: "/home/user/my-app".

Output Schema

TableJSON Schema

Name	Required	Description
`layers`	Yes	One entry per scanned layer. Alias layers are skipped.
`message`	No	The step to take next — how to continue a capped read. Present when there is one.
`truncated`	Yes	True when limit cut the result short. The totals still count everything.
`nextOffset`	No	The offset to pass to continue where this result stopped. Present only when truncated.
`totalNamespaces`	Yes	Top-level namespaces across every scanned layer, before limit. A namespace brings its whole subtree, so this is what limit counts.

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 filter by (e.g., \"root\", \"app-admin\"). If omitted or \"*\", scans all layers. Call discover to discover available layers."New value: +"Layer name to filter by (e.g., \"root\", \"app-admin\"). If omitted or \"*\", scans all layers. Call discover to list the layers."

addedInput schema / properties / limit

Added value: +{
+  "description": "Maximum number of top-level namespaces to return. Default: 100 for a tool call, unlimited at a terminal. When the cap applies the result carries truncated: true and nextOffset — call again with offset set to that value for the next page, or narrow the request instead.",
+  "maximum": 9007199254740991,
+  "minimum": 1,
+  "type": "integer"
+}

changedInput schema / properties / locale / description

Previous value: -"Locale to read keys from (e.g., \"en\"). Defaults to the project default locale. Keys are the same across locales — only one is needed."New value: +"Locale code to read from (e.g., \"en\", \"en-US\"). Defaults to the project default locale. Keys are the same across locales, so one is enough."

addedInput schema / properties / offset

Added value: +{
+  "description": "Number of top-level namespaces to skip before returning any. Default: 0. Pass the nextOffset of a truncated result to continue where it stopped.",
+  "maximum": 9007199254740991,
+  "minimum": 0,
+  "type": "integer"
+}

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$defs": {
+    "__schema0": {
+      "additionalProperties": false,
+      "properties": {
+        "children": {
+          "additionalProperties": {
+            "$ref": "#/$defs/__schema0"
+          },
+          "description": "Nested namespaces. Absent at a leaf, where the segment holds keys and no further nesting.",
+          "propertyNames": {
+            "description": "Next path segment.",
+            "type": "string"
+          },
+          "type": "object"
+        },
+        "keyCount": {
+          "description": "Translation keys under this namespace, including every nested one.",
+          "maximum": 9007199254740991,
+          "minimum": -9007199254740991,
+          "type": "integer"
+        }
+      },
+      "required": [
+        "keyCount"
+      ],
+      "type": "object"
+    }
+  },
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "additionalProperties": false,
+  "properties": {
+    "layers": {
+      "additionalProperties": {
+        "additionalProperties": false,
+        "properties": {
+          "namespaces": {
+            "additionalProperties": {
+              "$ref": "#/$defs/__schema0"
+            },
+            "description": "The key tree of that layer, one entry per top-level segment.",
+            "propertyNames": {
+              "description": "Top-level key segment, e.g. \"auth\".",
+              "type": "string"
+            },
+            "type": "object"
+          }
+        },
+        "required": [
+          "namespaces"
+        ],
+        "type": "object"
+      },
+      "description": "One entry per scanned layer. Alias layers are skipped.",
+      "propertyNames": {
+        "description": "Layer name.",
+        "type": "string"
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "The step to take next — how to continue a capped read. Present when there is one.",
+      "type": "string"
+    },
+    "nextOffset": {
+      "description": "The offset to pass to continue where this result stopped. Present only when truncated.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "totalNamespaces": {
+      "description": "Top-level namespaces across every scanned layer, before limit. A namespace brings its whole subtree, so this is what limit counts.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "truncated": {
+      "description": "True when limit cut the result short. The totals still count everything.",
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "layers",
+    "totalNamespaces",
+    "truncated"
+  ],
+  "type": "object"
+}

Changed2 schema fields changedv1.0.3Aug 19, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

changedInput schema / properties / projectDir / description

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

First observedv1.0.0Jun 15, 2026

TDQS

A4.1/5.0

Behavior4/5

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds real behavioral context the annotations don't: the limit/totalNamespaces relationship and that each top-level node drags in its entire subtree. It does not mention authentication or performance on large trees, but the added pagination semantics are substantive.

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?

Three sentences, front-loaded with purpose before the usage hint and the limit semantics. The final clause ('whatever the limit let through') is slightly convoluted, but overall there is little 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?

With an output schema present, return-value explanation is unnecessary, and the description still covers purpose, exploration use case, and pagination semantics. For a five-parameter, zero-required, read-only listing tool, an agent has everything it needs to call it correctly.

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 description coverage is 100%, so the baseline is 3, but the description goes beyond the schema by disambiguating what 'limit' actually counts — top-level namespace nodes, each carrying its whole subtree — versus totalNamespaces. That is genuine added meaning for the parameter an agent is most likely to misread.

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

Purpose4/5

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

States a specific verb and resource ('List the translation key tree grouped by namespace prefix, with a count per namespace node'), which is far more precise than the bare title 'List Namespaces'. It is clearly distinguishable from read-oriented siblings like get_translations or search_translations, though no sibling is named explicitly.

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

Usage Guidelines4/5

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

'Use this to explore the available keys without guessing path prefixes' gives a concrete selection context. It stops short of naming alternatives (e.g., discover for layers, search_translations for lookups) or stating when this tool should not be used, so it falls just short of a 5.

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

Deploy Server