`/i18n/locales` advertises locales the app never opted into (returns 4, app declares 2)

[huangyiirene]

Symptom

GET /api/v1/i18n/locales returns four locale descriptors — en, zh-CN, ja-JP, es-ES — on the showcase app, whose artifact declares i18n.supportedLocales = ['en','zh-CN']. The envelope half is correct ({success,data:{locales}} with isDefault, the #3636 shape); the set is a superset. ja-JP and es-ES are real and servable here (200) but the app never opted into them. This is the FAIL of surface-matrix clause 6. Reproduced on two boots.

Root cause

Located, and verified still present on origin/main as of this filing. Nothing narrows the i18n service's locale set to the app's declared supportedLocales.

• packages/runtime/src/app-plugin.ts loadTranslations() reads i18nConfig.defaultLocale only (it calls setDefaultLocale), then loads every locale key of every bundle. It never consults i18nConfig.supportedLocales.
• Each platform plugin independently pushes its own 4-locale bundle at kernel:ready — packages/platform-objects/src/plugin.ts (~206-230), plus service-settings, service-storage, service-messaging, service-realtime, plugin-security, plugin-sharing, plugin-webhooks — each shipping en/zh-CN/ja-JP/es-ES.
• getLocales() then returns the loaded key set (packages/core/src/fallbacks/memory-i18n.ts; same in packages/services/service-i18n/src/file-i18n-adapter.ts:192), and both the dispatcher /i18n domain and the service-i18n route map that set straight to the response.

Fix site / routing. The app's supportedLocales is only visible at the runtime app-plugin layer — loadTranslations() already reads i18nConfig and sets the default locale there. core's getLocales() has no knowledge of the app's declared set, so the narrowing must originate in packages/runtime (thread supportedLocales the way defaultLocale is already threaded, and narrow what getLocales() reports). Routed domain:cli on that basis.

Consequence. Any client building a locale picker from this route — including the platform's own Settings > Localization select, which already offers all four — offers locales in which only sys_* objects are translated. Picking ja-JP or es-ES guarantees a mixed-language session for app-owned metadata.

Related but distinct: #5418 (closed) covered the console's hardcoded language menu — a different layer (the console's own list), not this server-route superset.

Reproduction

Boot the showcase on a fresh file DB, sign in, then GET /api/v1/i18n/locales.

• Expected: descriptors for the artifact's declared i18n.supportedLocales = ['en','zh-CN'].
• Actual: four descriptors — en, zh-CN, ja-JP, es-ES.

Source

Extracted from the QA run #7640 (framework 92f26f7, console 09987b680).

[os-help]

🔒 Claimed by the domain:cli PM seat (seat post #6024), round 7.

• Session: session_0158ZQo7LiHSxGWpYKuPq1wu
• Branch: claude/issue-7679-i18n-supported-locales

Dispatching to a developer agent now. If you are another agent reading this: the assignee field cannot tell you whose claim this is — this comment can. A claim under a different session ID means the card is taken regardless of what the assignee says; please pick another.

Scope as dispatched: thread the app artifact's i18n.supportedLocales through loadTranslations() in packages/runtime/src/app-plugin.ts the way defaultLocale is already threaded, and narrow what getLocales() reports to that declared set. The filing's routing call is sound — core's getLocales() cannot see the app's declared set, so the narrowing has to originate in packages/runtime, not in core/service-i18n.

Two things the developer agent is told to decide in the issue thread rather than silently in code, because the filing does not settle them and guessing either way is a behaviour change:

1. Unset supportedLocales. An app that declares nothing must keep today's behaviour (report every loaded locale) — narrowing an undeclared app to zero or to the default alone would be a silent regression for every app that never opted in. Treat absent as "no narrowing".
2. A declared locale with no loaded bundle. If an app declares a locale the platform plugins never shipped, the honest answer is to report it as declared-but-unserved or to drop it — not to silently intersect and leave the client no signal. Whichever is chosen, it needs a test and a line in the changeset.

Narrowing the reported set is in scope; unloading the bundles is not — sys_* translations for unreported locales staying loaded is harmless, and dropping them is a bigger change than this card.

---

Generated by Claude Code

[os-help]

{
  "issue": 7679,
  "status": "done",
  "branch": "claude/issue-7679-i18n-supported-locales",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/7812",
  "pr_url": "https://github.com/objectstack-ai/objectstack/pull/7812",
  "premise_still_valid": true,
  "summary": "The filing's premise and root-cause routing both held on origin/main. II18nService gains an optional setSupportedLocales(locales); AppPlugin.loadTranslations threads the artifact's i18n.supportedLocales into it exactly the way it already threads defaultLocale, and both providers of the i18n slot (createMemoryI18n in core, FileI18nAdapter in service-i18n) narrow what getLocales() reports to that declaration. The narrowing is a READ-time filter, never a prune of what is stored, because the platform plugins push their four-locale bundles at kernel:ready, after the app plugin has run. Verified on a live showcase boot (fresh file DB, 47 plugins): GET /api/v1/i18n/locales now returns descriptors for en and zh-CN only, while GET /api/v1/i18n/translations/ja-JP still answers -- only the reported set narrowed.",
  "files_changed": [
    "packages/spec/src/contracts/i18n-service.ts -- declares optional setSupportedLocales, with the read-time-filter requirement and both decisions written into the contract",
    "packages/spec/src/system/i18n-resolver.ts -- new shared normalizeSupportedLocales, next to toLocaleDescriptors so both providers apply one rule",
    "packages/core/src/fallbacks/memory-i18n.ts -- createMemoryI18n stores the declaration and narrows getLocales()",
    "packages/services/service-i18n/src/file-i18n-adapter.ts -- same, for the production provider",
    "packages/runtime/src/app-plugin.ts -- threads i18nConfig.supportedLocales, guarded on 'declared something' so a sibling app cannot clear it",
    "packages/spec/export-origins/system.json, packages/spec/api-surface/system.json -- regenerated for the new export",
    ".changeset/i18n-locales-supported-locales.md -- new",
    "tests: packages/runtime/src/i18n-supported-locales.test.ts (new), plus packages/core/src/fallbacks/fallbacks.test.ts, packages/services/service-i18n/src/file-i18n-adapter.test.ts, packages/runtime/src/app-plugin.test.ts, packages/spec/src/system/i18n-resolver.test.ts"
  ],
  "tests_added": "39 new cases across 5 files. The load-bearing one is packages/runtime/src/i18n-supported-locales.test.ts (8 cases): it wires the real AppPlugin, the real createMemoryI18n provider and the real dispatcher /i18n domain together IN THE REAL LIFECYCLE ORDER (app declares first, platform's four-locale bundle pushed afterwards) and asserts the response body against GetLocalesResponseSchema -- a unit test on either half alone passes while the route still answers wrong. The rest: 9 provider cases in core, 8 in service-i18n (including that both providers answer one declaration identically), 5 threading cases in app-plugin.test.ts (declared / declared-with-no-bundles-of-its-own / undeclared-does-not-CALL / empty-array / provider without the optional method), 7 normalizer cases in spec.",
  "tests": "All green. pnpm --filter @objectstack/spec test => 'Test Files 378 passed (378) / Tests 9955 passed (9955)'. @objectstack/runtime => 'Test Files 130 passed (130) / Tests 2042 passed (2042)'. @objectstack/core => 'Test Files 32 passed (32) / Tests 772 passed (772)'. @objectstack/service-i18n => 'Test Files 5 passed (5) / Tests 70 passed (70)'. Typecheck green on spec (incl. check:scripts-typecheck and check:test-typecheck), runtime and service-i18n; core has no typecheck script (ERR_PNPM_RECURSIVE_RUN_NO_SCRIPT) and is covered by its build's DTS step. REVERSE VERIFICATION, direction predicted as standard red and confirmed: reverting memory-i18n.ts to origin/main and rebuilding turns 5 of the new suite's 8 cases red with the reported symptom verbatim -- \"expected [ 'en', 'zh-CN', 'ja-JP', 'es-ES' ] to not include 'ja-JP'\" -- and the 3 that stay green are exactly the DECISION-1 no-narrowing cases and the stays-servable case, which assert behaviour this PR does not change.",
  "decisions": {
    "unset_supportedLocales": "NO narrowing -- report every loaded locale, today's behaviour. Every app written before this change declared nothing, so narrowing an undeclared app to zero (or to its default alone) would empty the picker on every stack whose author never opted in. An i18n block carrying only defaultLocale, and a supportedLocales: [] declaring no usable code, are read the same way ([] is an authoring accident, not an intent to serve nothing: TranslationConfigSchema REQUIRES supportedLocales whenever i18n is declared at all, so the spec never asks anyone to write it). At the runtime layer this is a SKIPPED CALL rather than a call with undefined -- several AppPlugins share one kernel (the config apps are AppPlugins too), and an app with no i18n block must not clear a sibling's declaration.",
    "declared_locale_with_no_bundle": "REPORTED as declared-but-unserved, not dropped. Three grounds. (1) Honesty: the declaration is the app's statement of intent and the client is entitled to see it; a silently shortened list hides the authoring gap from author and client at once, which is the 'no signal' outcome the card ruled out. (2) There is no bright line to intersect on -- partial translation is the normal state (ObjectTranslationDataSchema is built for it), so a zero-key bundle and a one-key bundle differ by nothing a user perceives; dropping only the zero case is an arbitrary cliff, and a declared-but-unserved locale degrades to the default/fallback exactly as a half-translated bundle's missing keys already do. (3) An intersection is not STABLE: bundles are still arriving at kernel:ready, so its result would depend on when it was computed, whereas declared-wins is order-independent -- the same property that makes the read-time filter correct.",
    "also_decided_order": "Reported locales follow the DECLARED order rather than the insertion order of whichever plugin loaded first, so a picker renders the ordering the app author wrote. The order it replaces was an accident of plugin registration.",
    "also_decided_shared_rule": "normalizeSupportedLocales lives in packages/spec next to toLocaleDescriptors rather than being duplicated per provider. Either provider can mount GET /i18n/locales, and each holding its own copy of a rule is exactly how this route family came to answer in two shapes before (#3636, and #3833 one route over)."
  },
  "checks": {
    "lint": "npx eslint over all 10 changed source/test files -- no output, clean.",
    "typecheck": "pnpm --filter @objectstack/spec --filter @objectstack/runtime --filter @objectstack/service-i18n typecheck => all 'Done'. @objectstack/core defines no typecheck script.",
    "tests": "spec 9955 passed / runtime 2042 passed / core 772 passed / service-i18n 70 passed. Zero failures.",
    "gates": "node scripts/check-nul-bytes.mjs => 'OK (scanned 7131 text file(s) ... no raw ASCII control bytes)'; plus a manual grep -naP over the changed files for [\\x00-\\x08\\x0b\\x0c\\x0e-\\x1f\\x7f], no hits. pnpm --filter @objectstack/spec check:export-origins => 'export-origins/ is current: 5013 exports across 16 entry points resolve exactly as recorded'. check:generated => 'All 13 generated artifacts are up to date'. Both required regenerating first (gen:export-origins, gen:api-surface after a spec build) because the new export changed the recorded surface.",
    "live_repro": "objectstack dev --seed-admin on a fresh file DB, 47 plugins, showcase seeded. GET /api/v1/i18n/locales => {\"success\":true,\"data\":{\"locales\":[{\"code\":\"en\",\"label\":\"en\",\"isDefault\":true},{\"code\":\"zh-CN\",\"label\":\"zh-CN\",\"isDefault\":false}]}}. GET /api/v1/i18n/translations/ja-JP still 200 with the sys_* bundle. The built artifact was checked to carry the declaration the fix reads: artifact.i18n = {\"defaultLocale\":\"en\",\"supportedLocales\":[\"en\",\"zh-CN\"],\"fallbackLocale\":\"en\"} at the TOP level (manifest.i18n is undefined), which is the path app-plugin reads.",
    "ci": "not read -- reporting at draft-PR time per the current contract. PR #7812 was opened seconds before this report; gate conclusions are the PM's read."
  },
  "scope_deviations": [
    "Two generated spec artifacts were regenerated (export-origins/system.json, api-surface/system.json). Not optional: adding one export to packages/spec turns check:export-origins and its runtime-parity test red until they are, and the failure names the generator to run.",
    "The narrowing landed in packages/spec + packages/core + packages/services/service-i18n as well as packages/runtime. The filing routed the ORIGIN of the narrowing to runtime, which is where it is; the providers had to implement the method the runtime calls, and the contract had to declare it rather than leave a probed-but-undeclared method behind (the #4127 shape).",
    "No author-facing 'you declared a locale nobody ships' warning was added. The obvious placement is a kernel:ready hook, but hooks fire in plugin-REGISTRATION order, so a diagnostic there would false-positive on any platform plugin registered after the app -- a noisy warning on correctly-authored stacks. The signal the card asked for is delivered instead by the response itself (declared-but-unserved is reported, so the gap is visible to the client), and the narrowing is logged at debug level with the declared set."
  ],
  "out_of_scope_findings": [],
  "open_questions": [],
  "blockers": []
}

---

Generated by Claude Code