Translate Craft
Translation that reads as if originally written in the target language. Based on ATA standards, Mozilla l10n best practices, Airbnb style guide, and Microsoft Language Portal.
Core Principle
Translate meaning, not words. If the reader can tell it's a translation, it failed.
Sub-Commands
| Command | Description |
|---|
translate | Translate text with tone, formality, and cultural adaptation |
localize | Localize dates, currencies, units, addresses per locale |
i18n | Set up i18n framework (react-intl / i18next / ICU) |
rtl | Implement RTL layout with CSS logical properties |
audit | Review existing translation for quality issues |
teach | Create a localization guide for a language pair |
Language-Specific Rules (8 languages)
EN → ES (Spanish)
- Formality:
tú (internal), usted (client/external)
- Gender: inclusive language. "El usuario" → "La persona usuaria"
- Length: ~25% longer. Account for UI expansion.
- Passive: Active preferred. "Se decidió" not "Fue decidido"
EN → JA (Japanese)
- Politeness: 3 levels: casual (だ), polite (です), honorific (敬語). Default: polite.
- Subject omission: Drop subjects when clear from context
- Pronouns: Minimize 私/あなた. Overuse sounds foreign.
EN → FR (French)
- Formality:
vous (professional), tu (casual)
- Gender: Everything has gender. Ensure agreement across sentences.
- Punctuation: Non-breaking space before
?, !, :, ;
EN → DE (German)
- Compound nouns: "cloud storage" → "Cloud-Speicher"
- Capitalization: All nouns capitalized
- Formality:
Sie (prof), du (casual)
EN → PT (Portuguese)
- Formality:
você (general), o senhor/a senhora (formal)
- Length: ~20-25% longer
EN → ZH (Mandarin)
- Measure words: 个, 张, 条, 块 — correct classifier per noun
- Tone: 您 (formal) vs 你 (casual)
- Shortened: ~15-20% shorter. More room in UI.
- Script: Simplified for CN. Traditional for TW/HK.
EN → KO (Korean)
- Honorifics: 합쇼체 (formal), 해요체 (polite casual), 해체 (casual). Default: 해요체
- SOV word order: Subject-Object-Verb, opposite of English
EN → AR (Arabic)
- RTL: Everything mirrors. Use CSS logical properties.
- Root system: Words derive from 3-letter roots
- Length: ~25% shorter. Text shrinks in UI.
Workflow
- Identify scope: source, target, audience, medium, tone tier
- Analyze source: flag idioms, cultural references, ambiguity
- Translate: first pass applying language-specific rules
- Adapt tone: adjust register per audience
- Localize: dates, times, currencies, units, phone, addresses
- Restructure: natural target-language word order
- Reverse review: read only target. If you can reconstruct source, too literal.
- UI verify: paste into layout. Check truncation, overflow, RTL, line breaks.
- Final pass: production checklist.
i18n Framework Patterns
ICU Message Syntax
{count, plural, one {# item} other {# items}}
{gender, select, male {He} female {She} other {They}}
RTL Layout (CSS logical properties)
.element {
margin-inline-start: 1rem; /* auto-flips LTR/RTL */
padding-inline: 1rem;
border-inline-end: 1px solid;
}
Locale Formatting Quick Reference
| Format | EN | DE | JA | AR |
|---|
| Date short | 05/12/2026 | 12.05.2026 | 2026/05/12 | 12/05/2026 |
| Time | 3:30 PM | 15:30 | 15:30 | 03:30 م |
| Currency | $1,234.56 | 1.234,56 € | ¥1,235 | ١٬٢٣٤٫٥٦ ر.س |
| Number | 1,234.56 | 1.234,56 | 1,234.56 | ١٬٢٣٤٫٥٦ |
Production Checklist
Error Handling
| Cause | Fix |
|---|
Placeholder syntax ({name}, %s, {{var}}) broken in translation | Preserve exact placeholder format. Verify each appears unchanged in output. Test with real data. |
| Text expansion breaking UI layout (German +25%, Spanish +25%) | Design containers with flex-grow. Test with longest translated string. Account for CJK shortening (-15-20%). |
| False friends between language pairs | Maintain language-pair-specific false friends list. ES: "embarazada" ≠ "embarrassed". FR: "actuellement" ≠ "actually". DE: "Gift" ≠ "gift". |
| Mixed formality in same document (tú/usted, Sie/du) | Pick one register at start. Scan entire document for consistency. Language-specific rules table has defaults. |
| Word-for-word translation producing unnatural phrasing | Restructure to target language word order. KO: SOV. JA: drop subjects. AR: root-based word derivation. |
| RTL layout breaks on dynamically injected content | Use CSS logical properties exclusively (margin-inline-start, padding-inline, border-inline-end). Never left/right. |
| Back-translation reveals meaning drift | If reconstructed source differs from original, the translation is too literal or too loose. Adjust: preserve meaning, not word order. |
| Cultural reference doesn't exist in target market | Adapt or explain. Replace region-specific idioms with natural equivalent. Add brief context for untranslatable concepts. |
Anti-Patterns
| Anti-pattern | Correct |
|---|
| Literal idiom translation | Find equivalent idiom or drop |
| False friends (embarrassed ≠ embarazada) | Maintain false friends list per language pair |
| Mixed formality (tú/usted in same paragraph) | Pick one register. Enforce throughout. |
| Word-for-word structure | Restructure to target language patterns |
| Ignoring expansion (German +25%) | Design flexible containers. Test with longest string. |
| RTL as afterthought | Use CSS logical properties from day 1 |
ICU MessageFormat Advanced Patterns
Plurals (per-language rules)
// EN: 1 item, 2 items
{count, plural, one {# item} other {# items}}
// AR: 0 عناصر, 1 عنصر, 2 عنصران, 3-10 عناصر, 11+ عنصر
{count, plural, zero {# عناصر} one {# عنصر} two {# عنصران} few {# عناصر} many {# عنصر}}
// JA: 日本語は複数形がない（単純）
{count}個
Gender
// ES
{gender, select, male {Estimado} female {Estimada} other {Estimado/a}}
// FR
{gender, select, male {Cher} female {Chère} other {Cher/Chère}}
Select with nested plural
{gender, select,
male {{count, plural, one {Il a # livre} other {Il a # livres}}}
female {{count, plural, one {Elle a # livre} other {Elle a # livres}}}
}
Date/Number Locale Formatting
# Python babel
from babel.dates import format_date, format_datetime
format_date(date, locale='de_DE') # 18.05.2026
format_date(date, locale='en_US') # May 18, 2026
format_date(date, locale='ja_JP') # 2026/05/18
from babel.numbers import format_number, format_currency
format_number(1234567, locale='en_US') # 1,234,567
format_number(1234567, locale='de_DE') # 1.234.567
format_currency(49.99, 'EUR', locale='de_DE') # 49,99 €
// JavaScript Intl
new Intl.DateTimeFormat('ja-JP').format(new Date()) // 2026/5/18
new Intl.DateTimeFormat('ar-SA', { dateStyle: 'full' }).format(new Date())
new Intl.NumberFormat('es-ES', { style: 'currency', currency: 'EUR' }).format(49.99) // 49,99 €
RTL CSS Patterns
/* Logical properties (direction-aware) */
.element {
margin-inline-start: 16px; /* margin-left in LTR, margin-right in RTL */
padding-inline-end: 8px;
border-inline-start: 2px solid;
text-align: start;
}
/* Avoid: margin-left, padding-right, text-align: left */
Sources
- ATA (American Translators Association)
- Mozilla l10n best practices
- Airbnb translation style guide
- Microsoft Language Portal
- UN Translation guidelines
- W3C Internationalization articles
- FormatJS / ICU Message Syntax
- Google Material Design — RTL guidelines
Checklist