> For the complete documentation index, see [llms.txt](https://docs.ibexa.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ibexa.ai/manual/organisation/built-in-mcp-servers/translation-tools-mcp-server.md). # Translation MCP Server The **Translation MCP Server** is a built-in server that provides deterministic, code-based validation for translation agents. It gives agents access to checks that cannot be safely left to an AI's own judgment - things like whether a language code is genuinely valid, whether placeholders and URLs survived translation intact, and whether the formatting structure of the translated text matches the original. The tools on this server are **pure validators**: they read only the text they are given, make no database calls, and produce no side effects. Every check runs in code against fixed standards (ISO registries, structural comparison), so results are objective and reproducible - not estimates. > **Designed for translation agents.** This server is not for end users to configure directly. It is attached to agents that perform translation work so they have access to reliable, rule-based quality gates before returning results. ## Connection Parameters | **Parameter** | **Value** | | ------------------ | ----------------------------------------------------- | | **Server address** | `internal://translation-tools` | | **Server type** | Internal (built-in, no external credentials required) | This is an internal server - it is provided by the platform and requires no API keys or external configuration. Attach it to a translation agent from the agent's settings page. ## Key Concepts ### Why Deterministic Validation? AI models are confident but not always correct when evaluating their own output. A model asked to judge whether sp is a valid language code for Spanish may accept it - it looks like a reasonable abbreviation - but sp is not a recognised BCP-47 tag; the correct code is es. A model asked to verify that all placeholders survived translation may miss one. These tools enforce the checks in code, against fixed registries, so the answer is always exact. ### Language Tags (BCP-47) The platform uses **BCP-47 language tags** - the international standard for identifying languages - rather than plain ISO 639-1 two-letter codes. BCP-47 supports regional and script variants that production translation workflows need: `pt-BR` (Portuguese - Brazil) vs `pt-PT` (Portuguese - Portugal), `zh-Hans` (Chinese Simplified) vs `zh-Hant` (Chinese Traditional), `sr-Latn` (Serbian in Latin script) vs `sr-Cyrl` (Serbian in Cyrillic). The supported format is `language[-Script][-REGION]`, for example: `pl`, `pt-BR`, `zh-Hans-CN`, `en`. ### Issue Codes When validation finds a problem, it returns a standardised **issue code** alongside the human-readable details. These codes give a consistent vocabulary for downstream processing: | **Code** | **Meaning** | | -------------------------- | ------------------------------------------------------------------------------------------------------------------ | | `INVALID_LANGUAGE_CODE` | A requested or returned language tag failed validation. | | `PLACEHOLDER_MISMATCH` | A placeholder token, variable, or email address was added or removed in translation. | | `FORMAT_MISMATCH` | HTML tags, Markdown structure, link targets, code blocks, or embedded structured content differ from the source. | | `OUTPUT_VALIDATION_FAILED` | The translated text is wildly shorter or longer than the source - likely empty, truncated, or repeated. | | `UNTRANSLATABLE_SEGMENT` | A segment of the source text cannot be translated (this code is assigned by the agent itself, not by these tools). | ## Available Tools | **Tool** | **Description** | | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `validate_language_codes` | Validate one or more BCP-47 language tags against the ISO 639 (language), ISO 15924 (script), and ISO 3166-1 (region) registries. Returns a result for each tag: whether it is valid, its **canonical form** (which must be used as the language identifier going forward, not the original tag as submitted), its human-readable display name, and a rejection reason if invalid. This tool must be called for every source and target language before translating - the agent must never judge a language code's validity itself. | | `validate_translation` | Run a full deterministic quality check on a completed batch of translations before returning the final answer. Checks every translation for: placeholder and variable consistency, bare URL preservation, HTML tag and attribute structure, Markdown structural element counts, Markdown link targets (display text may change; URLs must not), code block content (must be copied verbatim), embedded JSON/YAML/XML shape, and a length sanity check. Also checks that every requested language was translated and no extra languages were added. If any issues are found, the agent must fix them and call this tool again - it must not return an answer this tool has not confirmed clean. |