the-i18n-mcp

Overview Schema Source Related Servers Discussions Admin

Scaffold Locale

scaffold_locale

Idempotent

Create empty locale files for new languages by copying your default locale's key structure with blank values, in JSON or PHP format — for adding untranslated locales.

Instructions

Create empty locale files for new languages, copying the key structure of the default locale with every value set to an empty string. Supports both JSON (Nuxt) and PHP (Laravel) formats. Does NOT modify the framework configuration — add the locale there first, then call this.

Input Schema

TableJSON Schema

Name	Required	Description
`layer`	No	Layer to scaffold in (e.g., "root", "app-admin"). If omitted, scaffolds across every layer.
`dryRun`	No	Report the files that would be created without writing them. Default: false.
`locales`	No	Locale codes to scaffold empty files for (e.g., ["sv", "ja", "pt-BR"]). If omitted, auto-detects the locales the config declares but has no files for.
`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
`dryRun`	Yes	True when nothing was written because a preview was asked for.
`created`	Yes	Files that were created, or would be under dryRun.
`skipped`	Yes	Files that already existed and were left alone.

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedv1.0.6Sep 12, 2026

changedInput schema / properties / dryRun / description

Previous value: -"When true, returns what files would be created without writing them. Default: false."New value: +"Report the files that would be created without writing them. Default: false."

changedInput schema / properties / layer / description

Previous value: -"Scope scaffolding to a single layer (e.g., \"root\", \"app-admin\"). If omitted, scaffolds across all layers. Call discover to discover available layers."New value: +"Layer to scaffold in (e.g., \"root\", \"app-admin\"). If omitted, scaffolds across every layer."

changedInput schema / properties / locales / description

Previous value: -"Locale codes to scaffold empty files for (e.g., [\"sv\", \"ja\", \"pt-BR\"]). If omitted, auto-detects locales defined in config that are missing locale files."New value: +"Locale codes to scaffold empty files for (e.g., [\"sv\", \"ja\", \"pt-BR\"]). If omitted, auto-detects the locales the config declares but has no files for."

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "additionalProperties": false,
+  "properties": {
+    "created": {
+      "description": "Files that were created, or would be under dryRun.",
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "file": {
+            "description": "Absolute path of the locale file.",
+            "type": "string"
+          },
+          "keys": {
+            "description": "Keys copied from the default locale, all with an empty-string value.",
+            "maximum": 9007199254740991,
+            "minimum": -9007199254740991,
+            "type": "integer"
+          },
+          "layer": {
+            "description": "Layer the file belongs to.",
+            "type": "string"
+          },
+          "locale": {
+            "description": "Locale code the file is for.",
+            "type": "string"
+          },
+          "namespace": {
+            "description": "Namespace this file holds, for a namespaced layout such as Laravel. Absent for a flat layout.",
+            "type": "string"
+          }
+        },
+        "required": [
+          "locale",
+          "layer",
+          "file",
+          "keys"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "dryRun": {
+      "description": "True when nothing was written because a preview was asked for.",
+      "type": "boolean"
+    },
+    "skipped": {
+      "description": "Files that already existed and were left alone.",
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "file": {
+            "description": "Absolute path of the locale file.",
+            "type": "string"
+          },
+          "keys": {
+            "description": "Keys copied from the default locale, all with an empty-string value.",
+            "maximum": 9007199254740991,
+            "minimum": -9007199254740991,
+            "type": "integer"
+          },
+          "layer": {
+            "description": "Layer the file belongs to.",
+            "type": "string"
+          },
+          "locale": {
+            "description": "Locale code the file is for.",
+            "type": "string"
+          },
+          "namespace": {
+            "description": "Namespace this file holds, for a namespaced layout such as Laravel. Absent for a flat layout.",
+            "type": "string"
+          }
+        },
+        "required": [
+          "locale",
+          "layer",
+          "file",
+          "keys"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "created",
+    "skipped",
+    "dryRun"
+  ],
+  "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.3/5.0

Behavior4/5

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

Annotations already declare non-read-only, idempotent, non-destructive behavior; the description adds meaningful detail beyond them — files are created with empty-string values, key structure mirrors the default locale, and config is deliberately left untouched. It doesn't say what happens if a locale file already exists, which is the one residual gap given idempotentHint=true.

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

Conciseness5/5

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

Three sentences, front-loaded with the action and the format scope, followed by the critical exclusion. Every clause carries information an agent needs; nothing is restated from the title or schema.

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 annotations covering safety and idempotency and an output schema handling return values, the description supplies the remaining essentials: what is created, in which formats, with what content, and the config prerequisite. Nothing needed to invoke it correctly is missing.

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

Parameters3/5

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

Schema description coverage is 100%, so all four parameters (layer, dryRun, locales, projectDir) are already fully documented in the schema, including defaults and fallbacks. The description adds no syntax or format detail beyond that, so the baseline 3 applies.

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+resource ("Create empty locale files") and immediately scopes it: copies the default locale's key structure with empty values, supports JSON and PHP formats. It also draws an explicit boundary ("Does NOT modify the framework configuration"), which no sibling tool claims, so an agent can distinguish it from write_translations or translate_missing.

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?

Gives a clear ordering prerequisite — add the locale to the framework config first, then call this — which is exactly the context needed before invocation. It doesn't name or contrast against any sibling tool, so it falls short of the 5 benchmark for explicit alternatives.

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

Deploy Server