Internationalization

The app speaks two languages properly: English (the base locale) and Serbian in Latin script (sr-Latn-RS), using Paraglide JS.

How it is wired

• Locales are declared in project.inlang/settings.json (baseLocale: "en", locales: ["en", "sr-Latn-RS"]).
• The message catalog is flat JSON: messages/en.json and messages/sr-Latn-RS.json, sorted ascending so an editor lists a component's strings together.
• paraglide.config.ts extends the shared root config with one deliberate difference: the strategy is ['localStorage', 'baseLocale']. The locale lives in localStorage, never in the URL, so there is no locale routing and no link rewriting.
• scripts/i18n.ts compiles the catalog into src/paraglide/ (gitignored); dev and build run it first, and it must have run once before lint/typecheck.
• UI code imports { messages } from the lib/i18n seam; only that file touches src/paraglide directly. domain/ never imports i18n: labels stay in the UI layer (blocks/conditionLabel.ts, features/skin/skinLabel.ts).

Switching languages

LocaleProvider sets <html lang> and keys the subtree on the locale, so switching re-renders every messages.* call with no reload. The shell's header, footer and <meta name="description"> live outside the app tree, so ShellText writes their text on mount and on every locale change; the static index.html/404.html keep brand fallbacks and a bilingual <noscript> (the page must say something even with JavaScript off).

Serbian dialect

sr-Latn-RS uses standard Serbian ekavica (napred, levo, pomera, ovde, neverovatno, vreme), not the ijekavica used in Bosnian/Croatian (naprijed, lijevo, pomjeri, ovdje, nevjerovatno, vrijeme).

Key taxonomy

Keys are flat snake_case, prefixed with the feature that owns them: palette_, controls_, level_picker_, block_for_, outcome_details_, skin_chooser_, playground_cell_ and so on. Keys name the element, not the string (palette_drop_to_delete, not drop_to_delete_text). A small set of truly shared words is promoted to common_ (common_close, common_collapse, common_expand); everything else stays in its owner's prefix, because a translator could reasonably write a different sentence for two places that happen to share an English word.

Plurals and variables

• Variables are {name} and become typed inputs (messages.skin_pick({ color })).
• Count-based strings are complex messages using Intl.PluralRules, each locale listing its own categories: English one/other, Serbian one/few/other (for example block_container_collapsed_count).
• Cycle counts are bigint in domain/; the UI converts with Number(...) at the message boundary, never inside a message or domain/.
• Markup placeholders are not used: when a sentence must wrap a JSX element (the for loop letter), the message is split into ..._prefix / ..._suffix keys and the element stays inline.

Level titles

Level names are content, not UI chrome, so they live in the level JSON as a locale-keyed record ("title": { "en": "...", "sr-Latn-RS": "..." }), resolved with localized(values, locale) (current locale, then base, then the first entry). Levels that introduce a block or hazard name it in the title in both locales.

What is not translated

The documentation in documentation/ is written in English only. It is aimed at developers and reviewers, and every page is a single source file; a translated guide would be a folder per locale with its own link-checker run. The app itself is the bilingual part.

Adding a string

1. Add the key to messages/en.json in sorted position, with the right prefix.
2. Add the same key to messages/sr-Latn-RS.json (every locale must have it).
3. Import messages from the lib/i18n seam and replace the literal.
4. bun run i18n, then bun validate.

Next: Code export.