Internationalization architecture

The selected image shows a storyteller laying wordless picture cards out in two arrangements: a row in front of her and a different layout beyond it. The pictures stay the same; each language's telling orders them its own way.

At the storytelling table	In the app
one set of picture cards for every session	one key per message, shared by all locales (step 1)
each teller's script, written as whole sentences, lays the cards in that language's order	whole messages with placeholders; translators choose the order (step 2)
a teller swapping English words one at a time keeps the English order	concatenated fragments (step 2)
the script's phrasing for "one goat", "two goats", "a few goats", "many goats"	ICU plural branches by category (steps 3–5)
prices and dates read out the way the audience reads them	Intl formatting (steps 8–10)
a scene with no Mexican Spanish line uses the Spanish line, then the English original	the fallback chain (step 12)
the session a family booked at the desk sets the language; a guess from their accent applies only before booking	the URL carries the locale; Accept-Language suggests (step 13)

In real terms: the code names a message and passes values; the locale's catalog, plural rule and formatters decide every word, digit and separator.

Breaks down when: a teller can improvise a phrasing for an odd count; a catalog cannot, so a missing branch falls to other. Nor does the room have time zones (step 9).

Contrasting case: a word-by-word subtitle machine that swaps each English word for a French one. It keeps the English order and the English singular/plural rule, which is what string concatenation does.

4.1 EXH-2020: the Arabic start button

Arabic imperatives change with the person addressed; English ones do not. The Arabic catalog held one fixed string, which addresses a man, so every candidate saw it. MR !2320 gives the Arabic message a select on the form of address chosen at check-in. The /ar/exam/… route that selects the Arabic catalog also sets <html lang="ar" dir="rtl">.

// before (EXH-2020), the Arabic catalog: "start the exam", said to a man
start: 'ابدأ الاختبار'
// after (MR !2320), formatted with @messageformat/core for 'ar'; the English catalog keeps 'Start the exam'
start: '{address, select, feminine {ابدئي الاختبار} masculine {ابدأ الاختبار} other {ابدأ الاختبار}}'

ar address=feminine  · before "ابدأ الاختبار" · after "ابدئي الاختبار"
ar address=masculine · before "ابدأ الاختبار" · after "ابدأ الاختبار"
en address=feminine  · "Start the exam"

Glosses: "ابدأ الاختبار" is "start the exam" said to a man, and "ابدئي الاختبار" the same said to a woman. Each locale's message carries only the arguments its own grammar needs (steps 2 and 7).

4.2 One order, four locales

The same amount, instant and list, formatted for four locales with an explicit timeZone.

en-US America/New_York number "1,234,567.5" · date "3/5/26, 4:15 PM" · either "A, B, or C"
de-DE Europe/Berlin    number "1.234.567,5" · date "05.03.26, 22:15" · either "A, B oder C"
ar-SA Asia/Riyadh      number "١٬٢٣٤٬٥٦٧٫٥" · date "٦/٣/٢٠٢٦، ١٢:١٥ ص" · either "A أو B أو C"
ja-JP Asia/Tokyo       number "1,234,567.5" · date "2026/03/06 6:15" · either "A、B、またはC"

Separators, digits, date order and the word for "or" all come from the locale, and the time zone moves the hour and even the day (steps 8–10).

4.3 Negotiation and the fallback chain

A request matched by lookup, then a Mexican Spanish page for which the app ships no regional catalog.

match(['de-CH', 'it'], ['en', 'de', 'it'], 'en', { algorithm: 'lookup' }) -> de
i18next lng es-MX, fallbackLng en: chain es-MX -> es -> en
t('cart') -> Carrito
t('pay') -> Pagar
t('help') -> Help
t('returns') -> returns

Lookup trims de-CH to de (step 11). i18next walks es-MX, es, then en, and shows the key itself when no catalog has it (step 12).