content-translate— agent skill

Overview

Translate and localize documents, code comments, UI strings, and structured content while preserving meaning, formatting, placeholders, and terminology. Use for anything from one string to a multi-file documentation set. For a native-fluency audit of the result, load the content-locale-humanize skill.

Mental model

A translation is a contract: same meaning and function, target-native form. Accuracy and completeness come first, then terminology, then fluency, style, and locale conventions; these are the MQM error dimensions reviewers will score. Professional practice (ISO 17100) separates translation from an independent revision. An LLM draft is machine output: it still needs that revision step (ISO 18587 post-editing), however fluent it reads.

Rules

Brief before translating

Ask when the locale variant, register, or domain is unknown and would change the output. Don't guess between es-ES and es-419.

Terminology

• Build or load a glossary before translating: source term → target term [domain, notes, rejected alternatives]. Reuse it in every section and extend it when new terms appear.
• UI labels in docs must match the shipped localized UI exactly. If the product isn't localized, keep the source label and add a translation only if the style guide asks for it.
• Verify uncertain terms against target-language vendor documentation and terminology portals, or an exact-phrase search on native sites. Keep established English loanwords where the target domain uses them ("commit," "pull request" in most developer registers).
• One source term, one target term per sense. If the source uses one word for two concepts, split it rather than forcing consistency.

Context and segmentation

• Give the model the brief, glossary, and enough surrounding document to resolve references. Current long-context models can hold a whole document; segment by output budget, not by an old context ceiling.
• Split only at structural boundaries: headings, functions, string groups, scenes. Never split inside code blocks, tables, frontmatter, lists with cross-references, or sentences.
• Pass the previous translated section as context instead of overlapping source text and deduplicating later.
• Track state per section (Section X/Y | heading | status). After assembly, read start to finish for tone drift, cross-references, anchors, and glossary use.

Format preservation

If unsure whether something is translatable, keep it and add [TN: ...].

Software strings

• Translate whole messages; never concatenate fragments, which breaks word order and agreement.
• Use ICU MessageFormat or the platform's plural API with CLDR plural categories (Arabic has six forms, Russian and Polish four, Japanese and Chinese one). Don't hand-code an English "s".
• Check gender, case, and article agreement around placeholders; ask for translator comments when a placeholder's content is unknown.
• Respect length limits. Labels under 10 characters can double or triple in European languages; text over 70 characters runs about 30% longer (W3C, citing IBM). Typical whole-text expansion: German +20–30%, Spanish and French +15–25%, Russian +15%; CJK usually runs shorter in characters. Flag truncation risks instead of abbreviating unclearly.
• RTL: isolate embedded LTR runs (<bdi>, dir="auto", or Unicode FSI/PDI), keep numbers and code readable, and let layout mirror.

Locale conventions

Follow Unicode CLDR data for the exact locale; this table covers the common traps.

Headings: English Title Case is an error in most target languages; use sentence case (German capitalizes nouns only). Converting Simplified to Traditional script is not localization for Taiwan or Hong Kong.

en-US: 1,000.50, 05/23/2026 (ISO 2026-05-23 when the source enforces it). Russian, Polish, Czech, Slovak: «…» or „…“ by country.

Domain adaptation

Gender-inclusive forms follow the client's style guide. Academies and several governments restrict typographic forms (asterisks, colons, the French point médian, the Italian schwa); the per-language locale skills carry the current norms. Without a guide, prefer neutral rewording or paired forms. Spanish: doublets ("todos y todas") or neutral rewording in formal text; the RAE rejects "todes", "tod@s", and "todxs", though some activist or youth audiences expect them.

Risk inventory

Ambiguity

Choose the reading the domain and context support and note it: [TN: ambiguous source; translated as "X" meaning Y]. Ask when the choice changes meaning materially.

Quality review

• Revise against the source, segment by segment: omissions, additions, numbers, negation, units, names, glossary terms. Reading only the target misses fluent errors.
• Run mechanical checks: placeholder and tag parity, numbers, URLs, glossary hits, length limits. For shipped content, log findings with MQM-style categories and severities.
• LLM self-review misses errors and favors its own output. For high-stakes content, review with a different model or a qualified human. Metrics (COMET, MetricX) and LLM judges (GEMBA-style) are screening tools, not sign-off; back-translation catches only gross drift.
• Fixing raw machine translation is full post-editing (ISO 18587:2017, under revision): human-translation quality, every check applies. Light post-editing (comprehensible, not publishable) only for internal gisting at the requester's word; state which level was delivered.
• Grade an existing translation analytically (ISO 5060:2024, MQM): tag each error by type (accuracy, fluency, terminology, style, locale convention, markup/placeholder) and severity (critical / major / minor); counts drive the verdict, not impression.

Report shapes

Adjustment delta note:

✏️ Adjustments (<what the user asked for>)

- <change category> — was: "<short snippet>" → now: "<short snippet>" — <reason>
- <change category> — applied throughout: <e.g. T-V form switched tú → usted>
- Preserved: <what was kept intact>

Translation notes (non-trivial choices only, one bullet each):

🗒 Translation notes (<source-lang> → <target-locale>)

- T-V form / Register: <choice> (reason)
- Untranslatable: <source term> rendered as <choice> — alternative: <other>
- Idiom: <source> → <target rendering> (literal would be misleading)
- Culture-bound: <reference> localized (purpose=marketing) / preserved+glossed (purpose=technical)
- Ambiguity flagged: <sentence> — read as <A> over <B> because <reason>
- Length: +/-X% vs source — <warn if a UI string may break layout>

Examples

Markdown, EN → es-ES (technical):

## Getting started
Install the package with npm:

npm install my-package

## Primeros pasos
Instala el paquete con npm:

npm install my-package

Heading in sentence case, code untouched, informal tú matching a developer audience in Spain.

Plural string, EN → ru. Wrong (concatenation, one form):

"Deleted " + count + " files"  →  "Удалено " + count + " файлов"

Right (ICU, CLDR categories):

{count, plural, one {Удалён # файл} few {Удалено # файла} many {Удалено # файлов} other {Удалено # файла}}

Checklist

• [ ] Locale tag, domain, audience, and register fixed before translating.
• [ ] Every source sentence present; nothing added, dropped, or softened.
• [ ] Glossary applied uniformly; UI labels match the shipped localized UI.
• [ ] Code, placeholders, tags, URLs, and frontmatter keys byte-identical; anchors updated.
• [ ] Plurals, agreement, and length limits handled for UI strings.
• [ ] Quotes, numbers, dates, spacing, and heading case follow the target locale.
• [ ] Revised against the source, ideally by a different model or a human for high-stakes text.
• [ ] Translator notes and unresolved ambiguities listed for the requester.

References

Reviewed 2026-10-12.

• ISO 17100 (translation services), ISO 18587 (post-editing; revision in progress), ISO 5060:2024 (evaluating translation output)
• MQM scoring models
• Unicode CLDR and MessageFormat 2.0 (stable since CLDR 47, 2025)
• W3C Internationalization: inline bidi markup and text size in translation
• OQLF: spacing around punctuation