loom-i18n

Internationalization (i18n)

Overview

Designing software to adapt to languages/regions without code changes (i18n), then adapting it per-locale (l10n). Covers translation architecture, ICU pluralization, Intl-based formatting, RTL/bidi, and libraries (i18next, react-intl/FormatJS, gettext).

First: Check for an L10N.md Charter

Before writing or translating any string, check the project root for L10N.md. When it exists, it is the project's authoritative localization charter — read it in full and let it override the generic guidance in this skill wherever the two conflict. Derive from it:

• Project context — the domain the product operates in (financial, technological, medical, …). Domain dictates terminology register and tone: "credit" means one thing in a banking app and another in a game, and a payments product cannot afford a casual mistranslation of a regulated term.
• What to translate directly and what not — the charter's do-not-translate list: brand and product names, trademarks, legal or regulated terms, technical identifiers. Never translate an entry on that list, even when a natural target-language equivalent exists.
• Branding and glossary — approved per-locale renderings of recurring product terms. Reuse them verbatim; inventing a second translation for an established term fragments the product's voice across locales.

Only the root L10N.md is read. Some projects nest per-area charters (server/L10N.md) or per-locale overrides (L10N/es.md); those are not consulted here, so anything that must always apply belongs in the root file.

When L10N.md does not exist, skip this step entirely — proceed with the generic guidance below, and do not create the file unasked.

The Rules That Prevent Rework

1. Never concatenate translated fragments. Word order, gender agreement, and grammar differ per language. Use one full-sentence key with named placeholders; the translator controls order.

   // Wrong — impossible to translate; order is baked into code
   t("You have") + " " + count + " " + t("new messages");
   // Right — one message, interpolation + plural inside it
   t("inbox.newMessages", { count }); // "{count, plural, one {# new message} other {# new messages}}"