i18n: a generated en bundle, a hand-written zh-CN, and a coverage gate that discovers

[os-warren]

Fixes #18

objectstack.config.ts advertised supportedLocales: ['en', 'zh-CN'] while dulyTranslations was []. The app claimed Chinese and shipped none of it: every authored label reached a Chinese deployment in English. This closes that.

Verified end to end in a browser: 231 bundle keys, four gates green at 0a70856, and the screens below are a real zh-CN session against pnpm demo.

---

The constraint that decided the design: en is generated

A hand-edited en entry wins at render time, so the screen and the code disagree while every gate stays green. The usual answer — generate a file, add a staleness check — is only as good as whoever remembers to re-run the generator.

So there is no en literal anywhere in this diff. src/translations/en.ts derives the bundle at config load from the same walk the gate uses. Nothing is stored, so nothing can go stale, and there is nothing a person could usefully hand-edit: changing an English string means changing the label in src/objects/, src/views/ or src/apps/, which is the only place it was ever true.

That property is pinned rather than asserted in a comment — buildEnglishBundle is run over synthetic metadata and the output has to follow the input, which a hand-written bundle could not do. It also goes through defineTranslationBundle, so the strict TranslationDataSchema refuses a mis-built key at load rather than shipping it unread.

The coverage gate discovers; it does not enumerate

src/translations/authored-text.ts visits every string leaf in the metadata and demands a verdict per normalised path ([] for an array index, {} for a record key). A path with no verdict is a finding, and the gate fails naming it. The default is "unknown → red"; the tables are the exception list.

Three verdicts:

verdict	meaning
translate	display text with a bundle key — goes into en, zh-CN must carry it
untranslatable	display text with no key anywhere in the platform's schema — named, counted, filed, never silently dropped
machine	not display text (a machine name, a CEL source, an icon, a colour, a filter token)

What is translatable at all is the platform's answer, not ours: TRANSLATABLE_METADATA_TYPES is imported from @objectstack/spec/system ({ view, action, object, app, dashboard, page }) and pinned, so the day datasets become translatable the pin goes red and the walk gets extended instead of quietly staying behind. View keys come from the platform's own expandViewContainer, so _views.default cannot drift from the registry name the resolver looks up.

Beyond the two directions the card asks for, the gate fails on: an unclassified path, a stale exemption (an untranslatable verdict that stopped matching anything), prose hiding inside a subtree declared opaque, two strings claiming one key, and a metadata collection in objectstack.config.ts that has never been classified.

It caught #69 on merge, which is the argument for building it this way. Merging main turned it red twice over: the exemptions for the three notify nodes' inline title / message failed as stale because #69 removed those strings, and nine paths #69 introduced (config.template, config.templateData.*) had no verdict. Neither is a string this gate could have been told about in advance. The inline-notification count is now pinned at zero so that gap cannot silently reopen.

Email templates are deliberately not walked

They are not bundle-keyed. translation.zod.ts does not mention them, EmailTemplateDefinitionSchema.translations is z.ZodNever, and the platform resolves a template by (name, locale) — so a translation is a sibling row, not a key. Demanding a bundle key for a template subject would make this gate permanently and unfixably red.

That skip is named with its mechanism in COLLECTION_HANDLING rather than being implied by omission — a type that localizes differently must not look like a type the walk forgot. The equivalent question is asked of the row shape instead, against #69's real rows: one row per (name, locale) for every supportedLocales entry, and each locale row carrying its own words rather than a copy of the source row's. That second check compares literal text with {{holes}} stripped, because subject: '{{{subject}}}' is identical in both rows on purpose — it renders the task's own subject line, and flagging it would be flagging the data.

Terminology

Six words carry product meaning a literal translation loses. The decisions live in the bundle, with their reasoning, because they have to be consistent across 231 keys and are not recoverable from the English string alone.

term	zh-CN	why, and what it must not read as
duty	职责	the recurring obligation itself — the rule that produces tasks. 职责 is the ordinary word for role-attached duty (岗位职责). ⛔ not 任务 (that is a task), ⛔ not 义务 (legal/moral)
task	任务	one dispatched occurrence. Paired with 职责 it keeps "a duty is not a task" as sharp in Chinese as in English
period	周期, field 所属周期	bare 周期 beside 频率 reads as the cadence, not the window — so period_key is "the period it belongs to"
standing	常设	the register of 常设机构 / 常设委员会: permanent by establishment, by nature not a thing that finishes. ⛔ not 长期 / 持续, which read as an ongoing task — exactly the misreading that sends people looking for the tick box the product refuses to have
governed	组织认定	"the organisation established it". ⛔ not 纳入考核 ("counted towards assessment") — accurate about the metrics, wrong about a product that scores nobody
caliber	口径	统计口径 — the standard term. No user-facing label carries it today; recorded so nobody invents a second word later

due_offset_days.label took the judgement the issue's round-2 comment flagged: the parenthetical had to survive as an explanation, so it is 「偏移天数（0 = 锚点当天）」 rather than a word-for-word rendering of "anchor day", and its help text keeps both worked examples per anchor, translated for sense.

Verified in a browser, in Chinese

pnpm demo, a Chromium context with locale: 'zh-CN' and Accept-Language: zh-CN.

The console chrome does not stay English. This was the expected finding and it is not what happens — the platform ships its own zh-CN console bundle and picks it up from the browser locale. 新建 / 导入 / 行内编辑 / 筛选 / 分组 / 排序 / 搜索… / 5 条记录 / 已选择 1 项 / 清除 are all the platform's. Nothing to file against objectui.

Object label, description, view tabs (全部任务 / 我的本周 / 逾期 / 停滞), column headers, option badges (待办 / 进行中, 岗位职责库 / 自行申报), nav groups and every nav item are ours and all render. The English strings visible are seed data (Emissions return — Northgate), correctly untranslated.

Screenshots are on a throwaway branch (claude/issue-18-screenshots) so no binaries enter this diff.

Two gaps the walk predicted, confirmed on screen

Dashboard title, description and all five widget titles/descriptions are Chinese — and directly under each metric tile the dataset measure label renders Untouched > 14 days, Untouched > 30 days, Oldest touch.

The selection bar reads 已选择 1 项 · Complete · Skip · 清除 — two English words between two Chinese ones, which is exactly the failure mode that reads as a styling quirk rather than a missing translation.

Display text no bundle can reach — filed, not worked around

Per AGENTS.md rule 9 these are filed upstream rather than papered over. Each is a declared verdict with a stated reason, and the exact set is asserted, so a new one fails the gate and one that becomes translatable fails as stale.

surface	count	audience	filed
bulkActionDefs label / confirm / params	35	end user	objectstack-ai/objectstack#14253
dataset label / description / dimension / measure labels	26	end user (chart axes, tile captions)	objectstack-ai/objectstack#14253
custom validation rule message	11	end user (write refusals)	objectstack-ai/objectstack#14253
flow label / description / node / edge labels	39	designer (Studio)	—
job, hook, position, permission-set label / description	18	operator	—

The validation-message one is worth calling out against the card's scope line ("… validation message … gets a key"): measured on objectql 17.2.0, a rule's message is emitted verbatim ({ field, code: 'rule_violation', message: rule.message }). messages['validation.field.*'] overrides the platform's built-in field catalog — which already ships zh-CN — not an authored rule. So a deployment gets platform refusals in Chinese and author-written refusals in English, and no bundle key can currently change that.

Separately filed: objectstack-ai/objectstack#14254 — translateAction ignores _actions.ACTION.description and _actions.ACTION.params.*, which TranslationItemSchema declares and validateTranslationReferences lints. Those keys are authored here anyway, for the same reason the gantt's viewMode stays authored in src/views/task.view.ts: the key is the spec's own, it is served to REST/OpenAPI/MCP callers today, and it starts rendering the moment the resolver is fixed.

The platform already owns half of this — as a warning

@objectstack/rest ships validateTranslationReferences (translation-target-unknown / translation-option-key-unknown), which covers the reverse direction over objects, fields, option values, views, sections, actions, params, apps, nav ids, dashboards and widgets. Measured by renaming one bundle key to duly_task_undoo:

VALIDATE EXIT=0
  ✓ Validation passed (419ms)
  ⚠ locale "zh-CN" · object "duly_task" · action "duly_task_undoo": Translations are keyed to
    action "duly_task_undoo", which is defined by neither object "duly_task"'s `actions` nor a
    `stack.actions` entry bound to it. The button keeps its source-locale label.
    Did you mean "duly_task_undo"?

A warning, exit 0. This gate makes it an error and adds the forward direction, which nothing upstream checks.

Tests

test/i18n-coverage.test.ts — 29 tests. Reverse-verified rather than assumed; each mutation was confirmed on disk by an anchored count before the reading was taken, and restored by an EXIT/INT/TERM trap:

mutation	result
delete objects.duly_task.fields.status.label from zh-CN	exit 1 — 2 red, naming the key
rename duly_task_undo → duly_task_undoo in zh-CN	exit 1 — 3 red, including "every zh-CN key still has a source"
add placeholder: to duly_task.note (a slot the walk had never seen)	exit 1 — tripwire fires, naming object.fields{}.placeholder

Plus self-tests on synthetic metadata for every rule, including that a stack with no authored text makes every exemption stale, that prose inside an opaque subtree is caught, and both email-template rules (missing sibling, and a locale row that copies the source row's wording).

Gates

All four green on 0a70856, the final commit, after merging main (which had taken #69):

validate=0 typecheck=0 test=0 build=0  @ 0a70856
  ✓ Validation passed          (one expected warning: hierarchy-security, per AGENTS.md)
  Test Files  28 passed (28)
      Tests  703 passed (703)
  ✓ Build complete — dist/objectstack.json (166.8 KB)

Bundle confirmed in the artifact and served live: GET /api/v1/i18n/locales → en, zh-CN; GET /api/v1/i18n/translations/zh-CN returns the tree.

No changeset — this repo has no changeset mechanism (no .changeset/, no dependency, no script, no mention in AGENTS.md). The four gates are the whole contract.

Recorded gap

Filed as #102 rather than done here: the bundle half of the gate compares against zh-CN by name, so a third locale added later would satisfy the locale-set assertion and have its key coverage checked by nothing. The email-template half already iterates supportedLocales generically and does not have this problem. Left out deliberately — #18's scope is the first Chinese deployment — and filed so it is a decision on the record rather than a surprise.

---

Generated by Claude Code