Localization

Deep localization workflow—locale strategy, string extraction, ICU and placeholders, formatting, RTL and layout, translation QA, and continuous delivery with feature flags. Use when shipping multiple languages or fixing i18n bugs at scale.

Localization (l10n) (Deep Workflow)

Localization is engineering + content + QA—not “send strings to translators.” Plan for concatenation, plural/gender, context, and layout early to avoid expensive rework.

When to Offer This Workflow

Trigger conditions:

• New markets/languages; translation backlog
• Broken plurals, overflow, RTL layout bugs
• Date/currency errors; sort order issues

Initial offer:

Use six stages: (1) strategy & scope, (2) extraction & keys, (3) ICU & placeholders, (4) formatting & locale data, (5) layout & RTL, (6) QA & launch process. Confirm TMS (Phrase, Lokalise, etc.) and release cadence.

---

Stage 1: Strategy & Scope

Goal: Which locales, what ships together, quality bar.

Decisions

• Locale list vs language only; regional variants (pt-BR vs pt-PT)
• Tier: full UI vs partial; legal must-have strings
• Fallback chain: es-MX → es → en

Exit condition: Scope document and priority locales for launch.

---

Stage 2: Extraction & Keys

Goal: Stable keys, developer context for translators.

Practices

• No string concatenation across translations—one message id per sentence
• Descriptions for translators: where shown, max length hint if UI constrained
• Namespaces per feature; avoid reusing ambiguous English in multiple keys

Workflow

• Freeze strings for release branches; diff notifications for late changes

Exit condition: Naming convention for keys; PR checklist for new strings.

---

Stage 3: ICU & Placeholders

Goal: Grammatically correct in all target languages.

Patterns

• Plural, select, ordinal rules via ICU MessageFormat (or platform equivalent)
• Variables named ({userName}), reordered per locale rules—never positional %s soup for user-visible text

Pitfalls

• Nested plurals; gender agreement languages—linguist review when needed

Exit condition: Lint or test that parses ICU per message.

---

Stage 4: Formatting & Locale Data

Goal: Numbers, dates, currency, units follow locale—not manual strings.

Practices

• Intl APIs (JS), babel / ICU (other stacks); timezone policy explicit (UTC vs user local)
• First day of week, calendars where relevant

Exit condition: Golden tests for format snapshots per locale sample.

---

Stage 5: Layout & RTL

Goal: UI works in long translations and RTL.

Practices

• Flexible layouts; truncate with tooltip only when necessary—German expands
• RTL: mirror icons/direction; bidirectional text in mixed content
• Vertical space for CJK line breaks when needed

Exit condition: Visual QA checklist per template; screenshots in worst-case language often de or fi for length stress.

---

Stage 6: QA & Launch

Goal: Linguistic + functional QA before traffic.

Process

• Pseudo-localization in CI: expand strings, accent—catches truncation early
• In-context review (on-device) when possible
• Smoke tests per locale on critical paths post-deploy

---

Final Review Checklist

• Locale scope and fallbacks defined
• Keys and translator context disciplined
• ICU for plurals/gender; no unsafe concatenation
• Intl formatting for numbers/dates/currency
• RTL and long-string layout verified
• QA process for each release train

Tips for Effective Guidance

• Concatenation is the #1 source of untranslatable bugs.
• English plural ≠ other languages—always use ICU.
• Legal copy may need jurisdiction review—flag early.

Handling Deviations

• Single extra language: still use ICU and Intl—habits scale.
• Community translations: glossary and style guide critical.