Internationalization

Games use i18next keys instead of inline English strings.

Files

Locale JSON on disk uses 2-space indentation and a trailing newline. Scripts (translate, prune-locales, sync-game-names-locale, etc.) share scripts/locale-json-format.mjs; npm run lint runs check-locale-json-format so manual edits stay aligned with --write tools. | locales/{de,fr,it,es-US}/*.json | Translations only (Weblate + CI) | | locale-src/{de,fr,it,es-US}/*.json | English snapshot for machine-translation diffing (CI only) |

Community partial locales (es, uk, ta, pt, ms, zh-Hans, nb-NO, etc.) live under locales/ with no sidecars. Some folders contain only the categories object in apgames.json where volunteers translated tag labels before other game strings existed.

locale-src/ sidecars

Managed locales (de, fr, it, es-US) are machine-translated by scripts/translate.mjs when English changes on develop (Dev Server CI). The script compares each key against a flat English snapshot in locale-src/ to detect stale translations.

When you remove keys from English, develop CI prunes the matching entries from managed locales/ files and locale-src/ sidecars before translation runs (no Gemini API call). Community partial locales are not auto-pruned — they remain Weblate-managed.

• Weblate syncs only locales/ — never locale-src/
• Develop CI updates both locales/ and locale-src/ on auto-translate commits — if locale-src/ is still dirty after translate, the auto-commit step failed and the next run will retranslate the same keys
• Production CI (main) does not run prune or Gemini translate; it publishes whatever locale JSON is already on the branch (typically merged from develop and Weblate)
• S3 publish uploads locales/ directly (no _src stripping needed)

One-time migration: node scripts/split-locale-src.mjs (already run; kept for reference).

Weblate merges

1. Merge migration before accepting Weblate PRs that strip _src
2. Close bulk "Cleanup translation files" PRs — they delete metadata and unrelated keys
3. Small human-editing PRs merge normally; locale-src/ is never in the diff
4. In hosted Weblate: disable the "Cleanup translation files" add-on for managed components

Hosted Weblate vs GitHub develop

GitHub origin/l10n/weblate is reset to match develop after imports (npm run merge-weblate-branch). Hosted Weblate also keeps its own git export (weblate/develop remote). Those histories diverge easily; Weblate then reports “Could not merge the repository” for many locales/* files.

Do not resolve that with git merge weblate/develop and checkout --theirs — that drops develop machine translations.

1. git fetch origin weblate (remote weblate → https://hosted.weblate.org/git/abstract-play/gameslib/)
2. npm run overlay-weblate-locales -- --ours origin/develop --theirs weblate/develop (pass explicit locale paths, or rely on default diff vs last merge)
3. Commit and git push origin develop
4. npm run reset-weblate-export — force-with-lease origin/l10n/weblate to the same commit as origin/develop (you cannot git push to hosted.weblate.org; that remote is read-only)
5. In Weblate: lock → Repository → Update (or wlc pull) → unlock. If Diagnostics still show merge failures, use Repository maintenance → Reset (admin), then update again.

npm run check-weblate-branch compares origin/develop to origin/l10n/weblate only; hosted Weblate can still be out of date until step 5.

Weblate key naming

Weblate's i18next parser treats a bare key as conflicting with siblings whose names look like plural or context suffixes (_one, _other, _2, _11, etc.) in the same JSON object. For example, do not place INSTRUCTIONS alongside INSTRUCTIONS_one — rename the non-plural key (e.g. INSTRUCTIONS_ANY).

npm run lint runs check-weblate-keys against locales/en/*.json and fails on conflicts. Use a distinct stem for each purpose (e.g. nowhere_what vs nowhere_count_one/nowhere_count_other).

In game code

description: "apgames:descriptions.complica"

Add keys when introducing new user-visible text. Variant names in gameinfo also reference apgames.json.

Game titles (names.{uid})

Meta-game display titles use apgames:names.{uid} (e.g. apgames:names.agere → "Adere"). English values are generated from gameinfo.name in source via npm run sync-game-names-locale; CI enforces parity with npm run check-game-names-locale.

• gameinfo.name in each game file stays the English canonical string (export snapshot, i18n fallback).
• resolveGameName(uid, englishFallback?) resolves the localized title from the active i18next locale; callers pass gameinfo.name as fallback when the key is missing. Exported from the package root (index.js / index-browser.js), not public-api — browser builds must not pull in i18n-node (fs).
• Run npm run sync-game-names-locale when adding a game or renaming gameinfo.name.
• Managed locales (de, fr, it, es-US) default to English for names (most titles are proper nouns). scripts/translate.mjs never machine-translates names.*: it copies English only for missing keys and leaves existing locale values (including human Weblate edits) unchanged. Run npm run seed-game-names-managed-locales after updating English names to batch-seed new keys into locales + locale-src.

Descriptions and notes continue to use apgames:descriptions.{uid} and apgames:notes.{uid}.

Category tag labels (categories.*)

Explore filters, game pickers, and meta pages show gameinfo.categories tag ids using localized strings from locales/en/apgames.json → categories. Each tag id has tag, full, and description.

• Add or update all three when introducing a new tag id (same PR as the gameinfo change).
• Managed locales: categories.* entries live in locale-src/*/apgames.json and are machine-translated like other apgames keys.
• Tag semantics and catalog lists: Categories & tags.
• Front consumes the apgames namespace only for these keys (not apfront).

Many keys are dynamic (categories.${tagId}.tag); do not run prune tools that drop unreferenced paths.

Render area labels

Seat-specific stash and panel titles under validation.<game> should use the placeholder (not). Games emit structured labels via seatAreaLabel(); do not call i18next.t() for those labels inside render(). Front resolves keys at draw time. See Structured render labels.

Sidebar status and score table headers use apgames:status.* keys the same way: emit neutralAreaLabel() from sidebarStatuses() / sidebarScores(); front resolves in setStatus().

addResource

Front end merges bundles via APGames.addResource(lang) — see API.

Consumers (front, node-backend, node-backend crons)

Pin @abstractplay/gameslib via each repo's ci-deps.dev.json / ci-deps.prod.json. Front runs npm run sync-locales after bump to copy updated apgames (including names) into public/locales/.

Scripts

Example games

• Complica — typical apgames: key usage