Translate JSON dictionaries and MDX content files between locales with structural integrity, SEO/GEO-aware keyword adaptation, and native-quality output. Use when translating UI strings, blog posts, service pages, or any locale-specific content.
Translate web content between locales. Every translation must read like it
was originally written in the target language while preserving exact file
structure.
Value types (string stays string, array stays array)
Translate:
All string leaf values that contain human-readable text
Do NOT translate:
Keys (ever)
URLs in values (e.g., "href": "/audit", "href": "https://...")
Brand names (define in project context or terminology glossary)
Statistical values that appear as strings (e.g., "value": "44%")
If the source has interpolation variables ({{variable}} or {variable}),
preserve them exactly in the translated string. Do not translate variable names.
python .claude/scripts/dictionary-diff.py --source en --target de --dir dictionaries
2. MDX content translation
Frontmatter rules
MDX files use YAML frontmatter. Fields fall into two categories:
Translate these text fields:
Field
Notes
title
Optimize for target-language search intent (see section 3)
description
Optimize for target-language search intent
summary
Natural adaptation, not word-for-word
tagline
Short, punchy — adapt to target language rhythm
Do NOT translate metadata fields (copy byte-identical):
Date fields, author, image paths, tags, status, technical metadata,
ordering fields, category slugs, URLs, and any field whose value is
a machine-readable identifier rather than human-readable text.
Body rules
Translate:
All prose paragraphs
Heading text (preserve heading level: ## stays ##)
Table cell content (preserve table structure)
List item text
Image alt text if present
Link text (the visible part in [text](url))
Do NOT translate:
URLs in links: [translated text](original-url-unchanged)
Preserve list structures (enumerated/bulleted content is cited more often)
Preserve table structure and column alignment
Preserve the overall content architecture (section count, section ordering)
Internal linking:
Link URLs stay unchanged (routing handles locale prefixing automatically)
Link text translates naturally
4. Quality standard
The bar
A native speaker of the target language should read the content and not
suspect it was translated. No translationese. No awkward calques.
No word-for-word mirroring of source language sentence structure.
What good translation looks like
Restructure sentences for natural target-language flow. Different
languages have different word order conventions — respect them.
Adapt idioms and examples. Find the equivalent expression or
rewrite the thought.
Match register. If the source is casual and direct, the translation
should feel casual and direct in the target language.
Preserve tone. The translation must carry the same personality as
the source.
Anti-fabrication rules
Never invent content not present in the source. If the source says
three benefits, the translation has three benefits. Not four.
Never omit content present in the source. Every paragraph, heading,
list item, and table row must appear in the translation.
Never change factual claims. Statistics, pricing, dates, company names,
product names, technical specifications — these transfer exactly.
Never alter URLs. Not even "fixing" a URL that looks wrong.
Terminology consistency
Use consistent terminology across all files for the same locale. Do not
translate a term one way in one section and another way elsewhere.
If the project has a terminology glossary (references/terminology-glossary.md),
follow it. If not, document terminology decisions in the translation report.
5. Language-specific rules
Each locale can have its own reference file at references/i18n-{code}.md
containing register, grammar rules, terminology table, and brand names.
Before translating, check for references/i18n-{locale}.md for the
target locale. If no file exists, create one and document all decisions.
When creating a new locale reference, determine:
Register (formal/informal) based on context
Which technical terms the target industry keeps in the source language
Script or directionality requirements (RTL for Arabic, etc.)
Cultural adaptations (date formats, number separators, etc.)
6. Workflow
Read the source file(s).
Determine content type (JSON or MDX) and apply the corresponding rules.
Translate following quality standards and anti-fabrication rules.
Write output to the matching path in the target locale directory.
Validate structure using the appropriate validation script.
If validation fails, fix the issues and re-run until PASS.
Report what was translated, any terminology decisions made, and any
content that needs native speaker review.