eliasoulkadi/shokunin/translate-craft

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

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

1. Identify scope: source, target, audience, medium, tone tier
2. Analyze source: flag idioms, cultural references, ambiguity
3. Translate: first pass applying language-specific rules
4. Adapt tone: adjust register per audience
5. Localize: dates, times, currencies, units, phone, addresses
6. Restructure: natural target-language word order
7. Reverse review: read only target. If you can reconstruct source, too literal.
8. UI verify: paste into layout. Check truncation, overflow, RTL, line breaks.
9. 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

Production Checklist

• [ ] Placeholders preserved ({name}, %s, {{var}})
• [ ] Date/time/currency/units converted per locale
• [ ] Cultural references adapted or explained
• [ ] Idioms replaced with natural equivalent
• [ ] Formality consistent across entire document
• [ ] Gender agreement checked
• [ ] UTF-8 encoding verified
• [ ] UI: expansion/shrinkage accounted for
• [ ] RTL: layout mirrored, numbers left-to-right
• [ ] Read-aloud test passed
• [ ] Back-translation sample checked for meaning drift

Error Handling

Anti-Patterns

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

• [ ] Skill loads without errors in the AI agent
• [ ] YAML frontmatter is valid (description, compatibility, audience)
• [ ] Workflow section provides clear step-by-step instructions
• [ ] Error handling section covers common failure modes
• [ ] All referenced files (references/, scripts/, assets/) exist
• [ ] Skill triggers correctly for intended use cases
• [ ] No broken links or missing resources