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 → INLINECODE2

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.