[Verslabs]

Summary

First reviewable slice of #25, split out as requested in that PR's review. It adds the L10n translation chokepoint, a language-asset check in verify_contribution.py, the en_us.json keys, and four migrated call sites (HudOverlay, PlayerSearchScreen, TranscriptPanelScreen, WatchState). No translations are included.

The verifier's generated-key pins (check descriptions, presets, keybind hub rows, tier labels) are left for the migration PR, since those call sites aren't on L10n yet.

Changes

• New dev.iustitia.i18n.L10n: t(key, args) returns Text and s(key, args) returns String. It is fail-open: an unknown key renders as the key, and a malformed % spec renders the raw entry instead of vanilla's "Format error". Lookups aren't cached, so a language change applies without a restart.
• 22 new iustitia.* keys in en_us.json. The English text is identical to the old literals, including § colour codes.
• Migrated call sites: HUD lag icon, confidence header and FP line; player-search screen (title, header, hint, empty, footers, alerts/top); transcript panel (title, tier, stats, alerts/flags, note, last events, no flags, compact); and the watch-cancel messages.
• verify_contribution.py --static now checks that:
  • every literal key the source asks for exists in en_us.json;
  • every other shipped language has exactly the same key set;
  • lang files have no duplicate keys;
  • % specs are valid;
  • placeholders and § counts match English;
  • no-plural locales ship an empty pluralSuffix.
• CONTRIBUTING.md gets a "User-facing text" section, and the PR template gets a "Localization/translation strings" area.

Affected areas

• Detection/check logic
• Packet observation or inference
• Config or presets
• Commands or UI
• Rendering or HUD
• Replay, clips, camera, or input
• Persistence or local data
• Documentation/tests/tooling

Verification

Commands run (branch head cd66664):

python scripts/verify_contribution.py --static
./gradlew test
./gradlew build
python scripts/live_selftest.py --check pipeline-smoke

Results:

• Static verifier: PASS, including the new language-asset check. Warnings: no build/selftest-manifest.json before the first live run, and en_us.json key 'key.category.iustitia.keybinds' is not referenced by any L10n call. That key is used by the keybinding category, not through L10n, so the warning is a false positive: key.category. isn't in the verifier's namespace list.
• Tests: PASS, BUILD SUCCESSFUL, 49 tests, 0 failures, 0 errors
• Build: PASS, BUILD SUCCESSFUL

Live client verification

• Client launch/mixin application: PASS. The real 1.21.11 client booted with this branch through runClientGameTest, and pipeline-smoke passed (1/1).
• Scenario(s): client boot plus the detection pipeline smoke test (loads the lang assets).
• Expected result: the client loads with the new lang file and no errors.
• Observed result: as expected.
• Not tested: the automated suite doesn't render the migrated screens or HUD lines. I haven't done a manual runClient check that the player-search screen, transcript panel, HUD panel and watch-cancel chat show the same English text as before.

Safety and privacy review

• No telemetry, uploads, analytics, or remote reporting were added.
• No unintended outgoing gameplay packets were added.
• Fail-open behavior is preserved where appropriate.
• Local-world, camera, input, and persistence state restore after stop/error/world change where relevant.
• Logs, screenshots, clips, and test data contain no secrets or private information.

Documentation and migration

• User-facing documentation updated, or no update is needed. (CONTRIBUTING.md, PR template.)
• Config/clip migration reviewed, or no migration is needed.
• Generated documentation source data updated if applicable. (Not applicable.)

AI assistance

• AI tool(s) used: Claude Code (Claude Opus 5.5)
• What the tool contributed: wrote the L10n helper, verifier check, key extraction and call-site migration, and ran the static verifier, Gradle test/build and the live smoke test above.
• What I reviewed manually: the diff, with an AI-assisted review pass on 2026-10-12. Maintainer review requested.

Known limitations and follow-up work

• The L10n.s comment mentions CheckInfo / FeatureInfo / Keybinds relying on the "key returned when missing" sentinel. Those call sites only move in the follow-up PR.
• iustitia.hud.confidenceHead passes the colour code letter as a %s argument (§%s[...]). Translators need to keep that §%s intact. The verifier's §-count check catches a dropped §, but not a reordered one.
• The verifier warning for key.category.iustitia.keybinds (see above) could be silenced by adding key.category.iustitia. to the namespace list.
• Conflicts with hud: resolve crosshair target once per frame and cache panel model pe… #42: both PRs edit HudOverlay.kt. Whichever merges second needs a rebase.
• Remaining hard-coded strings and the generated-key pins come in the next slice of i18n: route all player-facing text through L10n #25.