Localization

Internationalization (i18n) and Localization (l10n) Rules

1. Core Principles

• Externalize all user-facing strings — no hardcoded text in code
• Use ICU Message Format for plurals, gender, and selections
• Use Intl API for date, number, and currency formatting — never format manually
• Design for text expansion — translations can be 30-50% longer than English
• Separate translation files by namespace/feature for lazy loading
• Automate translation workflows with extraction tools and CI checks

2. ICU Message Format

The standard syntax for handling complex multilingual messages.

Basic Syntax

{variable, type, style}

Plural

{count, plural,
  =0 {No items}
  one {1 item}
  other {# items}
}

CLDR plural categories: zero, one, two, few, many, other. Languages use different subsets (English: one/other, Arabic: all six, Korean: other only). Always include other as fallback.

Select (Gender / Category)

{gender, select,
  male {He liked your post}
  female {She liked your post}
  other {They liked your post}
}

Nested Messages

{gender, select,
  male {{count, plural, one {He has # item} other {He has # items}}}
  female {{count, plural, one {She has # item} other {She has # items}}}
  other {{count, plural, one {They have # item} other {They have # items}}}
}

Rules

• Always provide the other category as fallback (required even for languages like Korean/Japanese that only use other)
• Use # as a placeholder for the numeric value in plural messages
• Keep messages as complete sentences — never concatenate fragments
• Provide translator context/description for ambiguous messages

3. i18n Library Patterns

Library Selection

react-intl (FormatJS)

import { FormattedMessage, useIntl } from "react-intl";

// Declarative
<FormattedMessage id="greeting" defaultMessage="Hello, {name}!" values={{ name }} />

// Imperative
const intl = useIntl();
intl.formatMessage({ id: "greeting" }, { name });
intl.formatNumber(1000, { style: "currency", currency: "USD" });
intl.formatDate(new Date(), { dateStyle: "long" });

i18next

import { useTranslation } from "react-i18next";
const { t } = useTranslation("common");

t("greeting", { name: "World" });      // "Hello, {{name}}!"
t("item", { count: 5 });               // plural: item_one / item_other keys
t("common:button.save");               // namespace prefix

vue-i18n

<template>
  <p>{{ $t("greeting", { name: "World" }) }}</p>
</template>

<script setup>
import { useI18n } from "vue-i18n";
const { t } = useI18n();
</script>

4. Translation File Management

Directory Structure

locales/
├── en/
│   ├── common.json        # Shared UI (buttons, labels)
│   ├── auth.json           # Authentication
│   ├── dashboard.json      # Dashboard page
│   └── errors.json         # Error messages
├── ko/
│   ├── common.json
│   ├── auth.json
│   └── ...
└── ja/
    └── ...

Key Naming

{
  "button.save": "Save",
  "button.cancel": "Cancel",
  "validation.required": "This field is required",
  "validation.minLength": "Must be at least {min} characters"
}

• Use dot-notation or nested keys consistently (don't mix)
• Use descriptive, hierarchical key names — not source text as keys
• Group by feature/component, not by page

Namespace Splitting

• Split by feature: auth.json, dashboard.json, settings.json
• Keep shared UI in common.json
• Align namespaces with code-splitting for lazy loading

5. Intl API Formatting

Use the browser/runtime Intl API — never write manual formatting logic.

Numbers and Currency

new Intl.NumberFormat("ko-KR").format(1234567);
// "1,234,567"

new Intl.NumberFormat("en-US", { style: "currency", currency: "USD" }).format(42);
// "$42.00"

new Intl.NumberFormat("en", { notation: "compact" }).format(1500000);
// "1.5M"

Dates and Times

new Intl.DateTimeFormat("ko-KR", { dateStyle: "long" }).format(date);
// "2026년 3월 24일"

new Intl.RelativeTimeFormat("ko", { numeric: "auto" }).format(-1, "day");
// "어제"

Lists

new Intl.ListFormat("en", { type: "conjunction" }).format(["A", "B", "C"]);
// "A, B, and C"

Collation (Sorting)

const collator = new Intl.Collator("de", { sensitivity: "base" });
["ä", "a", "z"].sort(collator.compare);
// ["a", "ä", "z"] (German sorting)

6. RTL (Right-to-Left) Support

RTL languages: Arabic (ar), Hebrew (he), Persian (fa), Urdu (ur).

HTML Direction

<html lang="ar" dir="rtl">

<!-- Bidirectional isolation -->
<p>User: <bdi>مستخدم</bdi> posted a comment</p>

CSS Logical Properties

Replace physical properties (left/right) with logical properties for automatic RTL support.

RTL Considerations

• Mirror directional icons (arrows, progress bars) with transform: scaleX(-1)
• Keep phone numbers, code snippets, and URLs in LTR direction
• Use HTML dir attribute over CSS direction (better for accessibility)
• Flexbox and Grid automatically adjust with dir="rtl"
• Test layouts in both LTR and RTL modes (if your application supports RTL languages)
• Icons to mirror in RTL: navigation arrows, progress bars, send/reply, undo/redo
• Icons NOT to mirror: media controls, clocks, checkmarks, logos, slashes

7. Unicode and CLDR

BCP 47 Language Tags

en          # English
en-US       # American English
zh-Hans     # Simplified Chinese
zh-Hant-TW  # Traditional Chinese (Taiwan)
sr-Latn     # Serbian (Latin script)
sr-Cyrl     # Serbian (Cyrillic script)

Grapheme Cluster Awareness

// String.length counts UTF-16 code units, not visible characters
"👨‍👩‍👧‍👦".length;                    // 11

// Use Intl.Segmenter for correct grapheme counting
const seg = new Intl.Segmenter("en", { granularity: "grapheme" });
[...seg.segment("👨‍👩‍👧‍👦")].length;   // 1

Locale-Aware String Operations

• Case conversion: use toLocaleLowerCase(locale) (Turkish i → İ)
• Sorting: use Intl.Collator (Swedish ä sorts after z)
• Word breaking: CJK languages have no spaces — use Intl.Segmenter
• Normalization: use String.prototype.normalize("NFC") before comparison

8. Translation Workflow and CI

Extraction

# FormatJS
formatjs extract 'src/**/*.tsx' --out-file lang/en.json

# i18next
npx i18next-scanner --config i18next-scanner.config.js

CI Checks

Validate on every PR:

• Missing keys: source code keys exist in all translation files
• Unused keys: translation files have no orphaned keys
• Syntax validation: ICU message format is parseable
• Placeholder match: variables in source match variables in translations

Translation Platforms

• Crowdin, Phrase, Lokalise, Transifex (SaaS)
• Weblate (open source, self-hosted)

Integrate via CLI + CI pipeline for automated upload/download.

9. Common Anti-Patterns

10. References

For detailed RTL implementation patterns and ICU format examples, see references/rtl-languages.md and references/icu-message-format.md.

External Resources

• ICU Message Format
• CLDR Plural Rules
• FormatJS
• i18next
• vue-i18n
• MDN Intl API
• CSS Logical Properties (MDN)
• W3C Internationalization