fix(i18n): one translation shape — the translation type speaks objects., not o. (#3778) - #3808
Merged
Merged
Conversation
…ects.`, not `o.` (#3778) A translation authored in the product saved successfully and rendered nothing. Not a resolver gap — a contract split. The `translation` metadata type (`allowRuntimeCreate: true`) was registered against `AppTranslationBundleSchema`, an object-first shape keyed on `o.<object>`. Every resolver, `os i18n extract`, `os i18n check`, the objectui hooks, and all nine shipped bundles read `objects.<object>`. Nothing bridged them, so the save path and the read path never met. A converter was the obvious fix and the wrong one: throwaway code that would start producing *working* `o.`-shaped rows, closing the migration-free window that exists precisely because the feature never functioned. The retired shape's real-world footprint was zero — all three `*.translation.ts` files in the tree were already `objects.`-shaped, contradicting the type's own registered schema. Converging is a registration fix, not a migration. BREAKING: `AppTranslationBundleSchema`, `ObjectTranslationNodeSchema` and their types are deleted with no deprecation cycle — nothing worked end-to-end through them, so there is no consumer to protect, and a deprecated-but-present schema is exactly the exemplar an agent copies into new code. `II18nService.getAppBundle` / `loadAppBundle` go with them (zero implementers — a capability the runtime never delivered). `TranslationItemSchema` replaces them: one locale of the same `TranslationData` groups a file bundle uses, plus the `locale` it translates, with a `defineTranslation()` factory. Three details are deliberate, all aimed at making the failure loud instead of silent: - `locale` is required, not inferred from the item name. The sync skips an item whose locale it cannot resolve, and a skip is invisible to whoever authored it. - Retired keys are rejected, not stripped. Zod drops undeclared keys silently, which would reproduce this bug exactly. A pre-parse guard turns that silence into a 422 naming the right group, and runs ahead of the parse so the keys stay out of the schema — the generated JSON Schema and the Studio editor never advertise a shape that cannot work. - `ObjectTranslationData.label` becomes optional. Partial translation is the normal state; requiring it forced authors to restate the source label just to validate, filling bundles with fake translations that mask coverage gaps. Also here: the authored sync warns (naming the row and the fix) on a row still in the retired shape instead of loading it into nowhere, and no longer merges publish bookkeeping into the translation layer. `GET /i18n/labels/:object/:locale` reads the nested field data it is actually given — it scanned for flat dotted `o.<obj>.fields.<field>` keys, a third dialect no producer ever wrote, so it always returned `{}`. A `translation` create seed makes the Studio create flow round-trip. Docs, the i18n skill, and the sweep-test fixture no longer teach the retired shape. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017wPvotUdM6WFtJm1KKryLE
|
The latest updates on your projects. Learn more about Vercel for GitHub. 1 Skipped Deployment
|
github-actions
Bot
added
documentation
Contributor
📓 Docs Drift CheckThis PR changes 4 package(s): 116 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:
|
os-zhuang
marked this pull request as ready for review
July 28, 2026 06:42
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #3778.
The bug
A translation authored in the product saved successfully and then rendered nothing.
Not a resolver gap — a contract split. The
translationmetadata type (allowRuntimeCreate: true, so Studio / the metadata API / an agent can author it) was registered againstAppTranslationBundleSchema, an object-first shape keyed ono.<object>. Every resolver,os i18n extract,os i18n check, the objectui hooks, and all nine shipped bundles readobjects.<object>. Nothing bridged them, so the save path and the read path never met.The plumbing was never the problem: #2591's authored-translation sync is shape-agnostic, and the metadata door stores payloads verbatim. Only the registered authoring contract pointed at a shape nobody reads.
Why converge instead of bridge
A converter (normalize
o.→objects.at ingestion) was the obvious fix and the wrong one. It would be throwaway code, and worse, it would start producing workingo.-shaped rows — closing the migration-free window that exists precisely because the feature never functioned.The retired shape's real-world footprint was zero. All three
*.translation.tsfiles in the tree (platform-objects setup, CRM and todo examples) were alreadyobjects.-shapedTranslationBundles, contradicting the type's own registered schema. Converging is a registration fix, not a migration.objects.<name>is itself object-first — all of one object's content under one key — so the workbench/coverage benefits the protocol doc attributed too.are fully retained. The difference was spelling, plus a few divergent leaf names (confirmMessagevsconfirmText, nosuccessMessage, a duplicate_optionstrack, flat vs app-scoped nav) that disappear with the split.Breaking changes
AppTranslationBundleSchema,ObjectTranslationNodeSchemaand their types are deleted — no deprecation cycle. Nothing worked end-to-end through them, so there is no functioning consumer to protect, and a deprecated-but-present schema is exactly the exemplar an AI agent copies into new code. Everyo.exemplar (schemas, protocol doc section, skill section, diff examples) is purged in the same PR.II18nService.getAppBundle/loadAppBundleare removed: zero implementers, so they advertised a capability the runtime never delivered (Prime Directive chore: version packages #10).ObjectTranslationData.labelbecomes optional (see below).The two JSON Schemas were retired from
json-schema.manifest.json— the ratchet gate caught the removal and required the deliberate opt-out, as designed.The replacement
TranslationItemSchema— one locale of the sameTranslationDatagroups a file bundle uses, plus thelocaleit translates, with adefineTranslation()factory. An item is one entry of aTranslationBundle; that is the whole type.Three details are deliberate, all aimed at making the failure loud instead of silent — the property this bug lacked:
localeis required, not inferred from the item name. The sync skips an item whose locale it cannot resolve, and a skip is invisible to whoever — or whatever — authored it. (The name fallback still covers rows written before this.)Retired keys are rejected, not stripped. Zod drops undeclared keys silently, which would reproduce this bug exactly: save succeeds, nothing renders. A pre-parse guard turns that silence into a 422 naming the group to use:
It runs ahead of the parse rather than as a refinement on declared keys, so the retired keys stay out of the schema itself. Verified through the real
/meta/typespath — the emitted JSON Schema lists only real groups withlocalerequired, so neither it nor the Studio editor advertises a shape that cannot work. A test locks that in, because a regression there re-teaches the wrong shape to every agent reading the schema. Blanket.strict()was rejected: the protocol deliberately stores Studio auxiliary fields (isPinned, …) verbatim.ObjectTranslationData.labelbecomes optional. Partial translation is the normal state (that's why coverage tooling exists) and every resolver already treats each key as independent. Requiring it forced authors — human or AI — to restate the source label just to pass validation, filling bundles with fake translations that mask real coverage gaps.Aspirational groups with no consumer (
reports,notifications,errors,_globalOptions,_meta.direction,namespace) were not carried over, per the #3494 liveness precedent: schema-only fields invite agents to author dead data users then believe is live.Also in this change
_lockReason,_packageVersion, …) into the translation layer.GET /i18n/labels/:object/:locale's fallback reads the nestedobjects.<obj>.fields.<field>.labeldata it is actually handed. It scanned for flat dottedo.<obj>.fields.<field>keys — a third dialect no producer ever wrote — so it always returned{}. Its test fixture had been written to match the broken code, which is why it was green.translationcreate seed ({ locale: 'en', objects: {} }) so the Studio create flow round-trips instead of 422-ing on an empty body.i18n-standard.mdx,translations.mdx, regenerated references), the i18n skill, and themetadata-validation-sweepfixture no longer teach the retired shape. The skill matters most here — it is what an agent reads before authoring bundles.Verification
turbo run test --concurrency=4(CI-equivalent)pnpm buildcheck:skill-examples/check:skill-docscheck:liveness,check:spec-changes,check:upgrade-guide,check:doc-authoring@objectstack/docs buildNew tests: schema acceptance/rejection incl. per-key migration messages; the JSON-Schema-stays-clean assertion; and end-to-end — an authored
objects.row syncs and comes back translated throughtranslateMetadataDocument(object label, plural, field label, inline action label + confirm), a retired-shape row is skipped with the warning while a valid sibling still loads, and bookkeeping stays out of the layer.metadata-validation-sweep'stranslationfixture failed on this branch — it was authored in the old shape. That is the guard working, not a false positive; the fixture is corrected. Two other packages failed intermittently in early parallel runs (plugin-pinyin-searchbuild,plugin-approvalstest); both were environmental — a tsup/turbo dts ordering race and a stalenode_modulesafter mergingmain— and both pass in isolation and in the clean CI-concurrency run.Out of scope (recorded, not fixed)
translations.mdxunder "Current boundaries" rather than left buried.translationtype'sfilePatterns(**/*.translation.ts, …) look vestigial — the three matching files are multi-locale bundles loaded via code/config, not through the metadata door.docs/audits/2026-07-app-metadata-reference-integrity-assessment.mdcites the two schema shapes as a complexity factor for the proposedvalidate-translation-referenceslint; that estimate is now simpler (one shape). Left as a dated record rather than edited.🤖 Generated with Claude Code
https://claude.ai/code/session_017wPvotUdM6WFtJm1KKryLE
Generated by Claude Code