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.