Skip to content

Commit 63e3873

Browse files
feat(spec)!: a single-word language name (Chinese, English, Japanese) is refused as a locale (#26770)
<!-- claude-projects-attribution: {"github_login":"os-support-ai"} --> _Requested by **Yibo Wang** · [project thread](https://claude.ai/code/project/chan_01BVUyyPie8gHwoPM18iABwB?thread=cmsg_01BVUyyPie8gHwoPM18iABwBP2wUZwvu3z6Y7h5975xXQ2)_ Fixes #26463 Clause-②: no (narrowing) Metadata-protocol: narrowed Skills-docs: none — `content/docs/ui/translations.mdx` and `content/docs/protocol/kernel/i18n-standard.mdx` already say a language name is refused (this diff makes that sentence true), and `skills/objectstack-i18n/SKILL.md` already teaches tag-shaped codes only (`en`, `en-US`, `zh-CN`, `pt-BR`); nothing taught there changes ## 维护者速读 - 改了什么:locale 的主语言子标签从 2–8 个字母收紧为 2–3 个字母,`Chinese`、`English`、`Japanese` 这类单词语言名现在被拒;spec、`sys_user.locale` 列规则、通知读侧三处同一字符串同步改。 - 为什么改:作者写 `locale: 'Chinese'` 能保存成功,但没有会话会请求这个 locale,译文永远不显示;拒收文案和 #25822 的 changeset 早已承诺「语言名会被拒」。 - 风险与回滚:已存为 `Chinese` 之类的翻译行或用户 locale,解析时会被拒(存量行照常加载并由 `os migrate meta --stored` 列为 TODO);回滚即还原这三处正则。 - 先看:`packages/spec/src/system/translation.zod.ts`(正则与拒收文案)、`packages/platform-objects/src/identity/sys-user.object.ts`(列规则)、`packages/services/service-messaging/src/recipient-locale.ts`(读侧副本与 `null` 说明)。 - 两分钟验证:`pnpm --filter @objectstack/spec exec vitest run src/system/translation.test.ts`,预期 `Chinese`/`English`/`Japanese` 三行拒收、`en`/`zh-CN`/`zh-Hans-CN`/`es-419` 通过。 - 需要你做的:无,席位落地。 ## What changes `LOCALE_TAG_SHAPE` accepted a 2–8 letter language subtag, so any single English word of that length passed as a locale, though `LOCALE_TAG_REFUSAL` and the #25822 changeset both say a language name is refused. The primary subtag is now 2–3 letters, the ISO 639 codes every tag in use starts with: BCP-47 reserves 4 letters and registers no 5–8 letter language. Hyphen subtags, `zh-Hans-CN`, `es-419`, `yue-HK` and case folding are unchanged. The one shape lives in three places, and all three move in the same commit, still byte-identical: | Copy | Role | Edit | |---|---|---| | `packages/spec/src/system/translation.zod.ts` `LOCALE_TAG_SHAPE` | `LocaleSchema`: translation item `locale`, bundle keys, `i18n.*` locales, seed `locale` | pattern; docblock and refusal text re-read so each sentence is true (the refusal now names `Chinese` and says write the tag, not the name) | | `packages/platform-objects/src/identity/sys-user.object.ts` `SYS_USER_LOCALE_TAG_PATTERN` | the `locale_bcp47_shape` rule on `sys_user.locale` | pattern and docblock | | `packages/services/service-messaging/src/recipient-locale.ts` `LOCALE_TAG_SHAPE` | read side for a recipient's notification locale | pattern; docblock: `null` is now shape-refused on both sides, `NOTHING_LITERALS` stays as the read side's own floor | Also: the 18.x D3 entry `translation-locale-non-tag-refused` described the replacement as "a 2-8 letter language subtag"; this diff made that false, so it now reads 2-3 (one word). Its conversion already judges with `LocaleSchema`, so a stored item under `Chinese` is now listed as a TODO with no further change. ADR-0087 disposition: `not-required (already-registered translation-locale-non-tag-refused)` in the changeset. The D3 entry already prescribes rewriting a language name by hand; this diff narrows the same shape. ### Copies of the pattern deliberately not moved - `packages/plugins/plugin-hono-server/src/current-user-endpoints-localization.test.ts:69`: a fixture rule. Its own docblock says what is under test is that the endpoint evaluates whatever rule the registry declares, and none of its 13 cases depends on a 4–8 letter subtag (all 13 pass unchanged). Outside the claim's file surface. - `ui/packages/i18n/src/provider.tsx:224`: the no-`Intl` fallback of `isWellFormedLanguageTag`. The main branch is `Intl.getCanonicalLocales`, which accepts `Chinese`; narrowing only the fallback would make the two branches disagree. It reads a UI language preference, not stored metadata. - `ui/packages/app-shell/src/views/metadata-admin/previews/doc-draft.ts:28`: add-locale input hygiene for a doc's `translations` map, which the spec keys by any string. A different contract, outside the claim's file surface. ## Tests - `packages/spec/src/system/translation.test.ts`: refusal rows `Chinese`, `English`, `Japanese`, `chinese-CN`, `null` (each an `invalid_format` issue whose message names the shape and the release); controls `en`, `zh-CN`, `zh-Hans-CN`, `es-419`, `yue-HK`, `zh-cn` accepted; the card's reproduction at the item door (`locale: 'Chinese'` refused at `locale` only) and a `Chinese` bundle key refused. - `packages/plugins/plugin-auth/src/sys-user-locale-write-contract.test.ts`: the shape-not-membership pin is rewritten. `Japanese` is now refused by the column (`VALIDATION_FAILED`), and a well-formed tag nothing ships (`tlh-QQ`) is still accepted, which keeps the pin about shape, not membership. - `packages/services/service-messaging/src/recipient-locale-shape-parity.test.ts`: source equality unchanged; behavioural rows gain `Chinese`, `Japanese`, `null`; the `null` case now pins that both sides refuse it by shape and the read side refuses it anyway. ## Acceptance notes - Precedent #25983 declared `Clause-②: no (narrowing)`; this card follows it (the claim says the same). - `test:repo` (vitest `repo` project) was not run locally: the diff edits none of its tests and the derived list does not name it; CI `Test Core` runs it. ## Verification All readings on head `84506a0c` (this branch merged with `main` `5cc31c78`) unless noted. <details><summary>Tests and typecheck</summary> - Before the merge, on `ee3058c2`: `pnpm --filter @objectstack/spec test` 731 files, 21928 passed, 1 todo; `@objectstack/service-messaging test` 61 files, 732 passed; `@objectstack/plugin-auth test` 198 files, 3780 passed, 10 skipped; `@objectstack/platform-objects test` 96 files, 1361 passed; `plugin-hono-server` `src/current-user-endpoints-localization.test.ts` 13 passed. - `typecheck` exit 0 for spec, platform-objects, service-messaging and plugin-auth (plugin-auth after a full build; its examples leg needs its own dist). - After the merge, on `84506a0c`: `src/system/translation.test.ts` 189 passed; platform-objects 96 files, 1361 passed; `recipient-locale-shape-parity.test.ts` 19 passed; `sys-user-locale-write-contract.test.ts` 24 passed. - `pnpm build`: 116 of 116 tasks; `pnpm --filter @objectstack/spec check:generated`: all 14 generated artifacts up to date (no regeneration commit needed). </details> <details><summary>Ablation (one-time, not kept)</summary> `node scripts/ablation-replace.mjs` put the spec pattern back to the 2–8 letter subtag (anchor hit 1 to 0, blob `fa4a2333` to `1108375e`) and ran `src/system/translation.test.ts`: 6 failed, 183 passed. The red rows are `Chinese`, `English`, `Japanese`, `chinese-CN`, `null` and the door test that carries the card's reproduction. Restored: blob equals HEAD (`fa4a2333`) and `git diff HEAD` is empty. The test imports `src`, so no build leg applies. </details> <details><summary>Derived gates</summary> `node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack` derived 87 families on `84506a0c`. Each was run and recorded as `CMD :: exit N`: all 87 exit 0. `--ran` reconciliation: 87 derived, 87 run, 0 NOT-MEASURED, 0 UNRUN. `check-adr-0087-registration --base origin/main`: one declared-breaking changeset, disposition `not-required (already-registered)`. </details> <details><summary>Dogfood battery</summary> `pnpm --filter @objectstack/dogfood test` under the verify lock, after a full build. On `84506a0c`: VERDICT command-exit 0, 302 files passed and 3 skipped (305), 2505 tests passed and 20 skipped (2525). Also on the pre-merge head `32f73697`: the same counts. </details> `main` gained six more commits after the merge (none touch the eight files here); CI judges the merge ref. --- _Generated by [Claude Code](https://claude.ai/code/session_01WGufziYkxRFm6oPR7CmuDg)_ --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent b198f91 commit 63e3873

8 files changed

Lines changed: 97 additions & 49 deletions

File tree

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
---
2+
'@objectstack/spec': minor
3+
'@objectstack/platform-objects': minor
4+
'@objectstack/service-messaging': minor
5+
---
6+
7+
feat(spec)!: a single-word language name (`Chinese`, `English`, `Japanese`) is refused as a locale
8+
9+
The 18.x locale shape refused `zh_CN`, a padded value and a multi-word name such as `Chinese (Simplified)`, but its 2–8 letter language subtag still admitted any single word of that length. An author who wrote `locale: 'Chinese'` got a green save, and the strings were stored under a locale no session ever asks for, so they never rendered. The refusal text already said a language name is refused.
10+
11+
The language subtag is now 2–3 letters, the ISO 639 codes every tag in use starts with (BCP-47 reserves 4 letters and registers no 5–8 letter language). Everything else in the shape is unchanged: hyphen-separated 1–8 letter-or-digit subtags (`en`, `zh-CN`, `zh-Hans-CN`, `es-419`, `yue-HK`), and case is not judged. The one shape moves in all three places that hold it:
12+
13+
- `LocaleSchema` (`@objectstack/spec/system`): a `translation` item's `locale`, translation bundle keys, `i18n.defaultLocale` / `fallbackLocale` / `supportedLocales`, a seed dataset's `locale` scope and the seed loader's `locale`.
14+
- `SYS_USER_LOCALE_TAG_PATTERN` (`@objectstack/platform-objects/identity`): the `locale_bcp47_shape` rule on a user's own `sys_user.locale` column.
15+
- `LOCALE_TAG_SHAPE` (`@objectstack/service-messaging`): the read side that picks a recipient's notification locale, byte-identical to the column rule.
16+
17+
Clause-②: no (narrowing) — the locale shape refuses values it used to accept. Nothing is widened.
18+
19+
Metadata-protocol: narrowed (a locale whose language subtag is 4–8 letters, in practice a language name, is refused on translation items, bundle keys, the i18n configuration and seed datasets)
20+
21+
<!-- adr-0087: not-required (already-registered translation-locale-non-tag-refused) the 18.x D3 entry already prescribes rewriting a language name by hand, and its conversion already lists such a stored row as a TODO through LocaleSchema; this diff narrows the same shape and corrects that entry's subtag length -->
22+
23+
**BREAKING** for an author or user who wrote a language name as a locale.
24+
25+
- **Before.** `defineTranslation({ name: 'qa_x', locale: 'Chinese', … })` parsed and its strings never rendered; `PATCH` of a user's `locale` to `Japanese` was stored, and that user's notifications fell to the delivery ladder's floor.
26+
- **Now.** The value is refused at `locale` (or at the bundle key) with a message naming the tag shape, and the user's write is refused by the column's `locale_bcp47_shape` rule.
27+
- **Fix.** Write the tag, not the name: `Chinese` → `zh-CN`, `English` → `en`, `Japanese` → `ja-JP`. A language name has no single tag it can have meant, so `os migrate meta --stored` lists a stored translation row as a TODO (D3 entry `translation-locale-non-tag-refused`) and you rewrite it by hand. A user whose stored `locale` is already a name such as `Japanese` keeps loading: their notifications fall to the deployment default, and saving that value again is refused until it is replaced with a tag.

‎packages/platform-objects/src/identity/sys-user.object.ts‎

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,11 +4,17 @@ import { ObjectSchema, Field } from '@objectstack/spec/data';
44
import { INVITATION_ROLE_OPTIONS } from '@objectstack/spec/identity';
55

66
/**
7-
* The BCP-47 shape `sys_user.locale` accepts — a 2–8 letter language subtag
7+
* The BCP-47 shape `sys_user.locale` accepts — a 2–3 letter language subtag
88
* followed by any number of 1–8 alphanumeric subtags (`zh`, `zh-CN`,
99
* `zh-Hans-CN`, `es-419`). Shape only: membership in a shipped template bundle
1010
* is the bundle's business, and the delivery-time ladders handle a
11-
* shipped-nowhere tag by falling to their floor.
11+
* shipped-nowhere tag by falling to their floor. The primary subtag is held to
12+
* the 2–3 letters of the ISO 639 codes real tags start with, so a language
13+
* name (`Japanese`) or a stringified nothing (`null`) is refused as
14+
* malformed: BCP-47 reserves 4 letters and registers no 5–8 letter language.
15+
* The same pattern as `LOCALE_TAG_SHAPE` behind `LocaleSchema` in
16+
* `@objectstack/spec/system`, so a translation is stored only under a tag a
17+
* user can hold.
1218
*
1319
* A JS regex SOURCE string, because that is what a `format` validation rule
1420
* carries (`new RegExp(rule.regex)` in objectql's rule validator) — anchored at
@@ -30,7 +36,7 @@ import { INVITATION_ROLE_OPTIONS } from '@objectstack/spec/identity';
3036
* `recipient-locale-shape-parity.test.ts` in service-messaging asserts the two
3137
* spellings are byte-identical and names what breaks if they are not.
3238
*/
33-
export const SYS_USER_LOCALE_TAG_PATTERN = '^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*$';
39+
export const SYS_USER_LOCALE_TAG_PATTERN = '^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{1,8})*$';
3440

3541
/**
3642
* sys_user — System User Object

‎packages/plugins/plugin-auth/src/sys-user-locale-write-contract.test.ts‎

Lines changed: 13 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -202,16 +202,18 @@ describe('sys_user.locale — the guard and the shape check compose', () => {
202202
expect(refusal(data, 'update')).toMatchObject({ code: 'VALIDATION_FAILED' });
203203
});
204204

205-
it('the check is of SHAPE, not of membership — an 8-letter word is a legal tag', () => {
206-
// Measured while writing this file, and worth a pin rather than a comment:
207-
// `Japanese` is eight letters, so it satisfies the primary-subtag rule and
208-
// the column accepts it. That is correct and deliberate — membership in a
209-
// shipped template bundle is the bundle's business, and a tag nothing
210-
// ships falls to the delivery ladder's floor (`en-US` in `sendTemplate`,
211-
// `DEFAULT_LOCALE` in the store) rather than dead-lettering. The ruling's
212-
// safety property is about malformed values, NOT unknown ones, and a
213-
// reader who expects this rule to reject `Japanese` would "fix" it into a
214-
// closed vocabulary the platform does not have.
215-
expect(refusal({ locale: 'Japanese' }, 'update')).toBeNull();
205+
it('the check is of SHAPE, not of membership — a language name is malformed, an unshipped tag is not', () => {
206+
// The ruling asks for a BCP-47 SHAPE check and fixes no subtag length.
207+
// Since #26463 the primary subtag is the 2–3 letters of the ISO 639 codes
208+
// real tags start with (BCP-47 reserves 4 letters and registers no 5–8
209+
// letter language), so `Japanese` is refused as malformed: it is a name,
210+
// and no session ever asks for it. That is still shape, not membership —
211+
// a well-formed tag nothing ships (`tlh-QQ`) is accepted and falls to the
212+
// delivery ladder's floor (`en-US` in `sendTemplate`, `DEFAULT_LOCALE` in
213+
// the store) rather than dead-lettering. A reader who wants this rule to
214+
// reject an unshipped tag would "fix" it into a closed vocabulary the
215+
// platform does not have.
216+
expect(refusal({ locale: 'Japanese' }, 'update')).toMatchObject({ code: 'VALIDATION_FAILED' });
217+
expect(refusal({ locale: 'tlh-QQ' }, 'update')).toBeNull();
216218
});
217219
});

‎packages/services/service-messaging/src/recipient-locale-shape-parity.test.ts‎

Lines changed: 10 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -57,7 +57,7 @@ describe('recipient locale shape ↔ sys_user.locale write rule', () => {
5757

5858
it.each([
5959
'zh', 'zh-CN', 'zh-Hans-CN', 'es-419', 'en-US', 'yue-HK',
60-
'Chinese (Simplified)', 'zh_CN', '-CN', 'zh-Hansumlaut', '1zh', 'zh CN',
60+
'Chinese (Simplified)', 'Chinese', 'Japanese', 'null', 'zh_CN', '-CN', 'zh-Hansumlaut', '1zh', 'zh CN',
6161
'../../etc/passwd', '',
6262
])('agrees with the compiled write-side pattern on %j', (value) => {
6363
// The behavioural half. Redundant while the sources are equal — and that
@@ -69,17 +69,15 @@ describe('recipient locale shape ↔ sys_user.locale write rule', () => {
6969
expect(LOCALE_TAG_SHAPE.test(value)).toBe(writeSide);
7070
});
7171

72-
it('the read side is deliberately STRICTER on the stringified-nothing literals', () => {
73-
// `"null"` is four letters, so it is shape-legal on both sides — the write
74-
// rule accepts it and only `NOTHING_LITERALS` in this module stops it
75-
// reaching a template lookup. Pinned as intended asymmetry so a future
76-
// reader does not "fix" the shared regex to close it: a lossy producer's
77-
// stringified nothing arrives below the data API, where the write rule
78-
// never runs, so tightening the shape would cost real tags (`null` is not
79-
// a language, but neither is it reachable by a user picking one from a
80-
// list) without closing the path it arrived by.
81-
expect(new RegExp(SYS_USER_LOCALE_TAG_PATTERN).test('null')).toBe(true);
82-
expect(LOCALE_TAG_SHAPE.test('null')).toBe(true);
72+
it('the stringified-nothing literals fail the shape on both sides, and the read side refuses them anyway', () => {
73+
// Since #26463 the primary subtag is 2–3 letters, so `"null"` (four
74+
// letters) is shape-refused on both sides, like any language name.
75+
// `NOTHING_LITERALS` in this module still refuses it on its own: a lossy
76+
// producer's stringified nothing arrives below the data API, where the
77+
// write rule never runs, so the read side keeps that floor rather than
78+
// depending on the shared shape staying this narrow.
79+
expect(new RegExp(SYS_USER_LOCALE_TAG_PATTERN).test('null')).toBe(false);
80+
expect(LOCALE_TAG_SHAPE.test('null')).toBe(false);
8381
expect(normalizeRecipientLocale('null')).toBeUndefined();
8482
// `"undefined"` is nine letters and fails the shape on both sides — it
8583
// never depended on the literal list.

‎packages/services/service-messaging/src/recipient-locale.ts‎

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -78,7 +78,7 @@ export const RECIPIENT_LOCALE_FIELD = 'locale';
7878
export const USER_OBJECT = 'sys_user';
7979

8080
/**
81-
* BCP-47-shaped: a 2–8 letter language subtag, then any number of 1–8
81+
* BCP-47-shaped: a 2–3 letter language subtag, then any number of 1–8
8282
* alphanumeric subtags (`zh`, `zh-CN`, `zh-Hans-CN`, `es-419`). Shape only —
8383
* membership is the template bundle's business, and the ladders below handle
8484
* a shipped-nowhere tag by falling to their floor.
@@ -99,20 +99,20 @@ export const USER_OBJECT = 'sys_user';
9999
* This module keeps its independent job either way, and the two are NOT
100100
* redundant. The write-side rule guards values ARRIVING through the data API;
101101
* this guards values already at rest — rows written before the rule existed
102-
* and rows written below the data API. It is also strictly the stricter of the
103-
* two: `"null"` is four letters and therefore SHAPE-LEGAL, so the write rule
104-
* would accept it and only {@link NOTHING_LITERALS} below stops it reaching a
105-
* template lookup. That asymmetry is deliberate rather than a gap in the
106-
* regex — the shape is shared with the write side byte-for-byte, and a
107-
* lossy producer's stringified nothing is a data-at-rest problem, not a
108-
* language a user can be typing.
102+
* and rows written below the data API. It is also never the looser of the
103+
* two: the shape is shared with the write side byte-for-byte, and on top of it
104+
* {@link NOTHING_LITERALS} below refuses a lossy producer's stringified
105+
* nothing. Since the primary subtag is 2–3 letters both of those literals
106+
* also fail the shape, so the list no longer changes an answer; it stays as
107+
* the read side's own floor, so a future widening of the shared shape cannot
108+
* hand `"null"` to a template lookup again.
109109
*
110110
* Exported for that pin and for nothing else — the normalizer below is the
111111
* supported entry point, and a caller that reaches for the raw regex is
112112
* re-implementing {@link normalizeRecipientLocale} minus the parts that
113113
* matter.
114114
*/
115-
export const LOCALE_TAG_SHAPE = /^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*$/;
115+
export const LOCALE_TAG_SHAPE = /^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{1,8})*$/;
116116

117117
/**
118118
* The stringified-nothing literals a lossy producer can leave in a column.

‎packages/spec/src/migrations/entries/semantic/18.translation-locale-non-tag-refused.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ export const entry: SemanticMigration = {
1515
+ 'bundle locale key, i18n.defaultLocale / fallbackLocale / supportedLocales, a seed dataset '
1616
+ 'locale scope, the seed loader locale',
1717
replacement:
18-
'the BCP-47 tag the value was written for: a 2-8 letter language subtag, then hyphen-separated '
18+
'the BCP-47 tag the value was written for: a 2-3 letter language subtag, then hyphen-separated '
1919
+ '1-8 letter-or-digit subtags (`en`, `zh-CN`, `zh-Hans-CN`, `es-419`). Write `zh-CN` for '
2020
+ '`zh_CN` and drop surrounding whitespace; the conversion does both for stored rows and built '
2121
+ 'artifacts. A language name or any other text has no single tag it can have meant, so rewrite '

‎packages/spec/src/system/translation.test.ts‎

Lines changed: 12 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -47,13 +47,18 @@ describe('LocaleSchema', () => {
4747
});
4848
});
4949

50-
it.each(['zh-Hans-CN', 'es-419', 'yue-HK', 'zh-cn'])('accepts the tag %j (case is not judged)', (locale) => {
50+
it.each(['en', 'zh-CN', 'zh-Hans-CN', 'es-419', 'yue-HK', 'zh-cn'])('accepts the tag %j (case is not judged)', (locale) => {
5151
expect(LocaleSchema.safeParse(locale).success).toBe(true);
5252
});
5353

5454
// #25822: each of these saved green and was stored under a locale no session
5555
// ever asks for, so its strings never rendered.
56-
it.each(['zh_CN', 'zh-CN ', ' en', 'zh CN', 'Chinese (Simplified)', 'not a locale!!', '', '-CN', '1zh', 'zh-Hansumlaut'])(
56+
// #26463: a single-word language name passed the first 2–8 letter primary
57+
// subtag; the subtag is now the 2–3 letters real tags start with.
58+
it.each([
59+
'zh_CN', 'zh-CN ', ' en', 'zh CN', 'Chinese (Simplified)', 'not a locale!!', '', '-CN', '1zh', 'zh-Hansumlaut',
60+
'Chinese', 'English', 'Japanese', 'chinese-CN', 'null',
61+
])(
5762
'refuses %j as a regex-format issue that names the release',
5863
(locale) => {
5964
const result = LocaleSchema.safeParse(locale);
@@ -71,6 +76,10 @@ describe('LocaleSchema', () => {
7176
expect(item.success).toBe(false);
7277
expect(item.error!.issues.map((i) => i.path.join('.'))).toEqual(['locale']);
7378
expect(() => defineTranslation({ name: 'zh_cn', locale: 'zh_CN', messages: { x: 'y' } })).toThrow(/BCP-47 language tag/);
79+
// The card's reproduction: a single-word language name at the item door.
80+
const named = TranslationItemSchema.safeParse({ name: 'qa_bad_locale', locale: 'Chinese', objects: { t: { label: 'x' } } });
81+
expect(named.success).toBe(false);
82+
expect(named.error!.issues.map((i) => [i.path.join('.'), i.code])).toEqual([['locale', 'invalid_format']]);
7483

7584
// The bundle door: the map key itself (`defineTranslationBundle`, `stack.translations`).
7685
const bundle = TranslationBundleSchema.safeParse({ zh_CN: { messages: { x: 'y' } } });
@@ -79,6 +88,7 @@ describe('LocaleSchema', () => {
7988
expect(bundle.error!.issues[0]!.path).toEqual(['zh_CN']);
8089
expect(PlatformTranslationBundleSchema.safeParse({ 'en ': { messages: { x: 'y' } } }).success).toBe(false);
8190
expect(() => defineTranslationBundle({ zh_CN: { messages: { x: 'y' } } })).toThrow();
91+
expect(TranslationBundleSchema.safeParse({ Chinese: { messages: { x: 'y' } } }).success).toBe(false);
8292

8393
// The stack's i18n configuration.
8494
const config = TranslationConfigSchema.safeParse({ defaultLocale: 'en', supportedLocales: ['en', 'zh_CN'] });

‎packages/spec/src/system/translation.zod.ts‎

Lines changed: 16 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -14,27 +14,32 @@ import { SnakeCaseIdentifierSchema } from '../shared/identifiers.zod';
1414
import { textSlotTemplateRefusal } from '../automation/flow-text-slot-template';
1515

1616
/**
17-
* The shape a locale tag must have: a 2–8 letter language subtag, then any
17+
* The shape a locale tag must have: a 2–3 letter language subtag, then any
1818
* number of hyphen-separated 1–8 letter-or-digit subtags (`en`, `zh-CN`,
19-
* `zh-Hans-CN`, `es-419`). The same pattern as `SYS_USER_LOCALE_TAG_PATTERN`
20-
* (`@objectstack/platform-objects/identity`), the shape a user's own `locale`
21-
* column accepts, so a translation is stored only under tags a session can
22-
* ask for.
19+
* `zh-Hans-CN`, `es-419`, `yue-HK`). The same pattern as
20+
* `SYS_USER_LOCALE_TAG_PATTERN` (`@objectstack/platform-objects/identity`),
21+
* the shape a user's own `locale` column accepts, so a translation is stored
22+
* only under tags a session can ask for.
2323
*
2424
* Shape only, by decision: membership has no registry to check against
2525
* (`Intl.getCanonicalLocales('xx-YY')` succeeds, which is why
2626
* `shared/value-domain.zod.ts` dropped a `bcp47_locale` domain), and case is
2727
* not judged because the resolvers fold it (`zh-cn` resolves to `zh-CN`).
28-
* What it refuses is what no resolver ever matches: an underscore separator
29-
* (`zh_CN`), whitespace, a language name.
28+
* The primary subtag is held to the 2–3 letters of the ISO 639 codes every
29+
* tag in use starts with: BCP-47 reserves 4 letters and registers no 5–8
30+
* letter language, so the only values that wider grammar ever admitted were
31+
* words. What it refuses is what no resolver ever matches: an underscore
32+
* separator (`zh_CN`), whitespace, a language name (`Chinese`,
33+
* `Chinese (Simplified)`).
3034
*/
31-
const LOCALE_TAG_SHAPE = /^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*$/;
35+
const LOCALE_TAG_SHAPE = /^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{1,8})*$/;
3236

3337
const LOCALE_TAG_REFUSAL =
34-
'must be a BCP-47 language tag such as `en`, `zh-CN` or `zh-Hans-CN`: a 2–8 letter language '
38+
'must be a BCP-47 language tag such as `en`, `zh-CN` or `zh-Hans-CN`: a 2–3 letter language '
3539
+ 'subtag, then hyphen-separated subtags. Refused since @objectstack/spec 18, because a translation '
36-
+ 'stored under any other spelling (`zh_CN`, a trailing space, a language name) is under a locale no '
37-
+ 'session ever asks for, so its strings never render. Separate subtags with `-`, not `_`.';
40+
+ 'stored under any other spelling (`zh_CN`, a trailing space, a language name such as `Chinese`) '
41+
+ 'is under a locale no session ever asks for, so its strings never render. Separate subtags with '
42+
+ '`-`, not `_`, and write the tag, not the name (`zh-CN`, not `Chinese`).';
3843

3944
export const LocaleSchema = lazySchema(() => z
4045
.string()

0 commit comments

Comments
 (0)