fix(translation): validate dictionaries before caching

Draft
KN
2d ago
+77-0

Summary

The loader accepted JSON that is not a string-to-string translation dictionary. Non-string values can reach string rendering operations; JSON null replaced a working cached dictionary before Object.keys threw and reported failure.

  • Validate a non-null, non-array object whose values are strings before caching.
  • Reject invalid files through the existing failure callback without destroying the previous usable dictionary.
  • Preserve empty dictionaries, empty string translations and literal special keys.
  • Six production lines only; no selection-order, lookup, options, installer, dependency or workflow changes.

Verification

  • Based on main 83ceac969392e7ea1948652d0b2dd6d06233ddeb; separate from #7/#8/#9.
  • Twelve new cases on unchanged code: ten failures and two valid controls passing. Fixed: all twelve pass.
  • Full Jest suite: 80 pass; Python installer suite: 27 pass. node --check and diff checks pass.
  • npm ci used the unchanged lockfile; Python tests ran in an isolated environment. Local Node 24.22.1 / Python 3.12.14.
  • Independent read-only review reran all twelve targeted cases and found no blocker.
  • Synthetic XMLHttpRequest fixtures only; no actual game deployment. Draft only, no merge.
  • Hosted PR CI completed successfully (details below). The workflow does not run on feature-branch pushes.

Summary by Sourcery

Validate translation dictionaries before caching to prevent malformed data from breaking rendering or replacing usable translations.

Bug Fixes:

  • Validate translation JSON as a non-null object with string values before caching it, preserving the last usable dictionary when invalid data is loaded.

Documentation:

  • Document the translation-file schema, validation behavior, cache preservation, and regression coverage.

Tests:

  • Add regression coverage for invalid translation shapes and valid empty or special-key dictionaries.

Summary by cubic

Fixes translation loading so invalid JSON files no longer replace a working dictionary or feed non-string values into string rendering.

The loader now validates that a translation file is a non-null, non-array object whose values are all strings before caching it. Files that fail validation go through the existing failure callback and leave the previous usable dictionary intact. Empty dictionaries, empty string translations, and literal keys like hasOwnProperty remain valid.

  • Added validation in DynamicTranslation.js and a regression test suite covering ten invalid shapes and two valid controls.
  • Documented the translation file schema in docs/research/translation-file-schema.md.

Hosted verification completed

PR CI 43904797840 passed all three jobs: Node 18 and Node 20 each ran 80 passing Jest tests; Python 3.11 ran 27 passing installer tests. No reruns or skipped tests.

Job logs confirm checkout a9b8f3aa01cc07f9f24e700a4c1fa3c477549a46. Its verified parents are the stated base and head c4bd8430bc48c86ca4ebfd0bbb6bb7900d6fcf26; tree f89c7f8a6ace161b6d222c1263a990f3ee85fc16 equals the local tested/staged tree. All three remote modified files match the local content. This is verified PR merge-ref CI, not a separate bare-head push run.