formhaus-mcp

Translation template

translation_template

Read-only

Generate a per-language translation overlay for a Formhaus form definition, translate only its values, and pass it to simulation to verify the result.

Instructions

Call this when the form needs another language, once per language: it returns the overlay to translate, which simulate_path accepts as overlay to check the result. Returns the translation skeleton of a definition for one language: overlay is nested JSON with the source texts as values and a locale key, which the app passes as the locale prop, file is the suggested name (signup.ru.json), slots lists every text with its address, translation key, {placeholders} and a source hash. Translate only the values, keep nesting, identifiers and {placeholders}, then save the overlay next to the definition. Store revision and review state separately; the template never marks anything as translated. When the app has its own keys, such as Lokalise keys, put them in "i18n" objects of the definition exactly as given instead. When the definition has errors, returns ok: false and the validation issues.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "definition": "<definition>",
      "lang": "<lang>"
    },
    "name": "translation_template"
  }
}

Input Schema

Name	Required	Description
`lang`	Yes	Target language code, such as "ru" or "pt-BR". It names the suggested file, such as signup.ru.json.
`prefix`	No	Prefix of derived translation keys, such as "signup" for keys like signup.title. Defaults to the form id. Pass false to list only the explicit keys from i18n objects.
`catalog`	No	Locale catalog the app passes as locale, such as the contents of @formhaus/core/locales/ru.json. Its messages and labels are left out of the overlay; catalog in the result lists its missing and unknown keys.
`definition`	Yes	Formhaus form definition as a JSON object or a JSON string. JSON Schema: https://formhaus.dev/schema/form-definition.json. Top level: id, title, submit { label }, and fields (one step) or steps [{ id, title, fields }]. Field: { key, type, label, validation?, options?, show?, showAny? }. Rules go inside "validation": { required, minLength, maxLength, min, max, pattern, matchField }. Condition: { field, eq \| neq \| in \| notIn \| contains \| notContains \| notEmpty \| gt \| gte \| lt \| lte } with exactly one operator, on a field of the same or an earlier step. Optional: lang, messages and labels catalogs, and i18n objects that map texts to translation keys.

Output Schema

Name	Required	Description
`ok`	Yes
`file`	No	Suggested file name, such as signup.ru.json.
`lang`	No
`slots`	No
`catalog`	No	Keys the given catalog lacks or does not know. Messages and labels it covers are left out of overlay and slots.
`overlay`	No	Translation skeleton with the source texts as values. Replace the values, keep the nesting.
`validation`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv0.13.5Oct 24, 2026

addedInput schema / properties / catalog

Added value: +{
+  "additionalProperties": {},
+  "description": "Locale catalog the app passes as locale, such as the contents of @formhaus/core/locales/ru.json. Its messages and labels are left out of the overlay; catalog in the result lists its missing and unknown keys.",
+  "propertyNames": {
+    "type": "string"
+  },
+  "type": "object"
+}

addedOutput schema / properties / catalog

Added value: +{
+  "additionalProperties": false,
+  "description": "Keys the given catalog lacks or does not know. Messages and labels it covers are left out of overlay and slots.",
+  "properties": {
+    "missing": {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "unknown": {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "missing",
+    "unknown"
+  ],
+  "type": "object"
+}

Changed1 schema field changedv0.13.4Oct 22, 2026

changedInput schema / properties / definition / description

Previous value: -"Formhaus form definition as a JSON object or a JSON string. JSON Schema: https://formhaus.dev/schema/form-definition.json. Top level: id, title, submit { label }, and fields (one step) or steps [{ id, title, fields }]. Field: { key, type, label, validation?, options?, show?, showAny? }. Rules go inside \"validation\": { required, minLength, maxLength, min, max, pattern, matchField }. Condition: { field, eq | neq | in | notIn | notEmpty | gt | gte | lt | lte } with exactly one operator, on a field of the same or an earlier step. Optional: lang, messages and labels catalogs, and i18n objects that map texts to translation keys."New value: +"Formhaus form definition as a JSON object or a JSON string. JSON Schema: https://formhaus.dev/schema/form-definition.json. Top level: id, title, submit { label }, and fields (one step) or steps [{ id, title, fields }]. Field: { key, type, label, validation?, options?, show?, showAny? }. Rules go inside \"validation\": { required, minLength, maxLength, min, max, pattern, matchField }. Condition: { field, eq | neq | in | notIn | contains | notContains | notEmpty | gt | gte | lt | lte } with exactly one operator, on a field of the same or an earlier step. Optional: lang, messages and labels catalogs, and i18n objects that map texts to translation keys."

Changed3 schema fields changedv0.13.3Oct 15, 2026

changedInput schema / properties / lang / description

Previous value: -"Target language, such as \"ru\" or \"pt-BR\"."New value: +"Target language code, such as \"ru\" or \"pt-BR\". It names the suggested file, such as signup.ru.json."

changedInput schema / properties / prefix / description

Previous value: -"Prefix of derived translation keys. Defaults to the form id; false lists explicit keys only."New value: +"Prefix of derived translation keys, such as \"signup\" for keys like signup.title. Defaults to the form id. Pass false to list only the explicit keys from i18n objects."

addedOutput schema / properties / validation / properties / issues / items / properties / fixes

Added value: +{
+  "description": "Ready repairs for this issue. Apply one patch to the definition, then validate again.",
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "patch": {
+        "description": "RFC 6902 JSON Patch operations (add, replace, remove, move) with JSON pointer paths.",
+        "items": {
+          "additionalProperties": {},
+          "propertyNames": {
+            "type": "string"
+          },
+          "type": "object"
+        },
+        "type": "array"
+      },
+      "safe": {
+        "description": "true when applying the patch only repairs the issue and changes nothing else. fix_definition applies these.",
+        "type": "boolean"
+      },
+      "title": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "title",
+      "safe",
+      "patch"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

First observedv0.13.1Oct 15, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Goes well beyond readOnlyHint: it says the template never marks anything as translated, that revision/review state must be stored separately, and that on invalid definitions it returns ok: false with validation issues. That is exactly the extra context annotations don't carry.

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 trigger, the return shape and the translate-then-save workflow are front-loaded and every sentence adds information. It is a dense single block, though, and could be split for easier scanning.

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 tool with nested JSON output, an existing output schema, and 100% parameter coverage, this description covers the workflow, the edit rules (translate values only, keep nesting and placeholders), and the error case. Nothing an agent needs to call 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 coverage is 100%, so lang/prefix/catalog/definition are already documented. The description clarifies how results are consumed (overlay as locale prop, file naming) but adds little parameter-level meaning beyond the schema baseline.

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 action and resource: it returns the translation skeleton/overlay of a definition for one language. It also names the downstream consumer (simulate_path accepts the overlay), which separates it cleanly from validate_definition and fix_definition.

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?

Explicit trigger ('when the form needs another language, once per language'), explicit follow-up step (pass overlay to simulate_path), and an explicit when-not with alternative ('when the app has its own keys, such as Lokalise keys, put them in i18n objects ... instead').

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

Deploy Server