Skip to main content
Glama
fabkho

the-i18n-mcp

by fabkho
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Search Translations

search_translations
Read-only

Find existing translation keys and values across layers and locales before adding duplicates. Match by substring or exact wording and get one compact row per matching key.

Instructions

Search translation files by key path or value, one compact row per matching key rather than one per key and locale. Useful for finding an existing translation before adding a duplicate of it. A key that seven layers and thirty locales define comes back as a single row: layers names every layer that defines it, which is what tells reuse from duplication, and value is the one the reference locale holds. Pass includeLocales for the detail rows — one per key and locale — when what each locale holds is the question. Matching is a case-insensitive substring unless matchMode says otherwise.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
layerNoLayer name to search in (e.g., "root", "app-admin"), or "*" for all layers. If omitted, searches every layer.
limitNoMaximum number of matching rows 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.
queryYesText to search for, matched against keys and/or values. Compared as a case-insensitive substring unless matchMode says otherwise. Example: "save" matches the key "common.actions.save" and the value "Save changes".
localeNoLocale code to search in (e.g., "en", "de"). If omitted, searches every locale.
offsetNoNumber of matching rows to skip before returning any. Default: 0. Pass the nextOffset of a truncated result to continue where it stopped.
searchInNoWhether to search translation keys, values, or both. Default: "both".
matchModeNoHow query is compared. "contains" is a case-insensitive substring, over every locale searched. "exact" is the whole string, and "fuzzy" also accepts near-misses in wording, both ignoring case, accents, punctuation and whitespace and both comparing against one locale only — locale when given, otherwise the project default. Default: "contains".
outputFileNoAbsolute 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/search-results.json"
projectDirNoAbsolute path to the project root. Defaults to I18N_PROJECT_DIR, then server cwd. Example: "/home/user/my-app".
includeLocalesNoReturn one row per key and locale — layer, locale, key, value — instead of one row per key. Several times the output for the same findings, so ask for it when the per-locale values are what you are after. Default: false.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed11 schema fields changedv1.0.6
    • addedInput schema / properties / includeLocales
      Added value: +{
+  "description": "Return one row per key and locale — layer, locale, key, value — instead of one row per key. Several times the output for the same findings, so ask for it when the per-locale values are what you are after. Default: false.",
+  "type": "boolean"
+}
    • changedInput schema / properties / layer / description
      Previous value: -"Layer name to search in (e.g., \"root\", \"app-admin\"), or \"*\" for all layers. If omitted, searches all layers. Call discover to discover available layers."New value: +"Layer name to search in (e.g., \"root\", \"app-admin\"), or \"*\" for all layers. If omitted, searches every layer."
    • addedInput schema / properties / limit
      Added value: +{
+  "description": "Maximum number of matching rows 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 code to search in (e.g., \"en\", \"de\"). If omitted, searches all locales."New value: +"Locale code to search in (e.g., \"en\", \"de\"). If omitted, searches every locale."
    • addedInput schema / properties / matchMode
      Added value: +{
+  "description": "How query is compared. \"contains\" is a case-insensitive substring, over every locale searched. \"exact\" is the whole string, and \"fuzzy\" also accepts near-misses in wording, both ignoring case, accents, punctuation and whitespace and both comparing against one locale only — locale when given, otherwise the project default. Default: \"contains\".",
+  "enum": [
+    "contains",
+    "exact",
+    "fuzzy"
+  ],
+  "type": "string"
+}
    • addedInput schema / properties / offset
      Added value: +{
+  "description": "Number of matching rows 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"
+}
    • changedInput schema / properties / outputFile / description
      Previous value: -"Absolute path to write full JSON output. Returns only a compact summary to the caller — use this for large outputs to avoid flooding the conversation context. Example: \"/tmp/search-results.json\""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/search-results.json\""
    • changedInput schema / properties / projectDir / description
      Previous value: -"Absolute path to the Nuxt project root. Defaults to I18N_PROJECT_DIR, then 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\"."
    • changedInput schema / properties / query / description
      Previous value: -"Substring to search for. Matched against translation keys and/or string values. Case-insensitive. Example: \"save\" matches key \"common.actions.save\" or value \"Save changes\"."New value: +"Text to search for, matched against keys and/or values. Compared as a case-insensitive substring unless matchMode says otherwise. Example: \"save\" matches the key \"common.actions.save\" and the value \"Save changes\"."
    • changedInput schema / properties / searchIn / description
      Previous value: -"Whether to search in translation keys, values, or both. Default: \"both\"."New value: +"Whether to search translation keys, values, or both. Default: \"both\"."
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "anyOf": [
+    {
+      "additionalProperties": false,
+      "properties": {
+        "matches": {
+          "anyOf": [
+            {
+              "items": {
+                "additionalProperties": false,
+                "properties": {
+                  "key": {
+                    "description": "The matching dot-path key.",
+                    "type": "string"
+                  },
+                  "layers": {
+                    "description": "Every searched layer that defines it. More than one means the key is duplicated across layers.",
+                    "items": {
+                      "type": "string"
+                    },
+                    "type": "array"
+                  },
+                  "locale": {
+                    "description": "Which locale value was read from: the reference locale where it defines the key, otherwise the first searched locale that does.",
+                    "type": "string"
+                  },
+                  "localeCount": {
+                    "description": "How many of the searched locales define the key.",
+                    "maximum": 9007199254740991,
+                    "minimum": -9007199254740991,
+                    "type": "integer"
+                  },
+                  "value": {
+                    "description": "What the locale named below holds for the key."
+                  }
+                },
+                "required": [
+                  "key",
+                  "layers",
+                  "value",
+                  "locale",
+                  "localeCount"
+                ],
+                "type": "object"
+              },
+              "type": "array"
+            },
+            {
+              "items": {
+                "additionalProperties": false,
+                "properties": {
+                  "key": {
+                    "description": "The matching dot-path key.",
+                    "type": "string"
+                  },
+                  "layer": {
+                    "description": "Layer the match was found in.",
+                    "type": "string"
+                  },
+                  "locale": {
+                    "description": "Locale the match was found in.",
+                    "type": "string"
+                  },
+                  "value": {
+                    "description": "What that locale holds for the key."
+                  }
+                },
+                "required": [
+                  "layer",
+                  "locale",
+                  "key",
+                  "value"
+                ],
+                "type": "object"
+              },
+              "type": "array"
+            }
+          ],
+          "description": "One row per key by default; one row per key and locale when includeLocales was passed."
+        },
+        "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"
+        },
+        "totalMatches": {
+          "description": "Number of rows the search found, whichever shape they are in — before limit, so it exceeds the rows in matches when truncated.",
+          "maximum": 9007199254740991,
+          "minimum": -9007199254740991,
+          "type": "integer"
+        },
+        "truncated": {
+          "description": "True when limit cut the result short. The totals still count everything.",
+          "type": "boolean"
+        }
+      },
+      "required": [
+        "matches",
+        "totalMatches",
+        "truncated"
+      ],
+      "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": {
+            "nextOffset": {
+              "description": "The offset to pass to continue where this result stopped. Present only when truncated.",
+              "maximum": 9007199254740991,
+              "minimum": -9007199254740991,
+              "type": "integer"
+            },
+            "totalMatches": {
+              "description": "Number of rows the search found, whichever shape they are in — before limit, so it exceeds the rows in matches when truncated.",
+              "maximum": 9007199254740991,
+              "minimum": -9007199254740991,
+              "type": "integer"
+            },
+            "truncated": {
+              "const": true,
+              "description": "Present when the diverted search was cut by limit.",
+              "type": "boolean"
+            }
+          },
+          "required": [
+            "totalMatches"
+          ],
+          "type": "object"
+        }
+      },
+      "required": [
+        "reportFile",
+        "summary"
+      ],
+      "type": "object"
+    }
+  ],
+  "type": "object"
+}
  2. Changed2 schema fields changedv1.0.3
    • 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 Nuxt project root. Defaults to server cwd. Example: \"/home/user/my-app\"."New value: +"Absolute path to the Nuxt project root. Defaults to I18N_PROJECT_DIR, then server cwd. Example: \"/home/user/my-app\"."
  3. First observedv1.0.0

TDQS

A4.4/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 beyond that: how a key defined across many layers and locales collapses into a single row, what the layers field signals about reuse versus duplication, and that value reflects the reference locale. It does not discuss cost, rate limits, or permission requirements.

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?

The description is front-loaded — purpose and the compact-row contract come first, the includeLocales escape hatch and matching default follow. Sentences are long and clause-heavy, but each carries information; nothing is pure filler. Slightly dense for the number of points being made.

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?

For a 10-parameter read tool with full schema coverage and an output schema, the description covers everything an agent needs: what it returns, the deduplication semantics, when to expand to per-locale rows, and the default matching mode. Return-values detail is unnecessary given the output schema, and nothing material is missing.

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 genuinely adds meaning the schema does not: it explains the output-size tradeoff of includeLocales ("Several times the output for the same findings" — actually stated in schema too) and clarifies matching semantics (case-insensitive substring unless matchMode says otherwise) at the call level. The includeLocales guidance about when the per-locale detail is worth the extra rows is the strongest added value.

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?

The description names a specific verb (search) and resource (translation files by key path or value) and immediately states the distinctive output shape: one compact row per matching key rather than one per key and locale. That row-shape framing is exactly what separates it from get_translations and find_duplicate_keys in the sibling list, so an agent can route correctly without opening any schema.

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?

It gives a concrete use case ("finding an existing translation before adding a duplicate of it") and an explicit condition for the alternate mode ("Pass includeLocales ... when what each locale holds is the question"), which is clear when-to-use guidance. It stops short of naming sibling tools such as get_translations or find_duplicate_keys as the alternative, so the routing is implied rather than explicit.

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

Deploy Server

Other Tools