docs(i18n): document inline I18nLabel locale maps in the translations guide - #16250
Merged
baozhoutao merged 1 commit intoSep 6, 2026
Merged
Conversation
… guide The user-facing guide described exactly one localisation route — a plain-string label translated in a bundle — and never mentioned the second authorized form of an `I18nLabel`, the inline locale map. Since the coverage gate began reading a map's own locales, an author writing one gets a real `missing translation for locale "..."` finding about a prop this page gave them no vocabulary for. Adds a row to "What you can translate" and a "Current boundaries" bullet stating, in order: both forms are authorized; the map is rendered but never extracted; coverage counts the locales the map carries; and no bundle key exists for it, nor is one synthesised from a node's position in the component tree (a settled maintainer ruling, transcribed as a refusal). Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Vbw3RPgdtqesx4azk9SbW8
This was referenced Sep 6, 2026
baozhoutao
marked this pull request as ready for review
September 6, 2026 08:14
baozhoutao
enabled auto-merge
September 6, 2026 08:14
baozhoutao
deleted the
claude/issue-15984-translations-inline-locale-maps
branch
September 6, 2026 08:49
This was referenced Sep 6, 2026
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
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.
Fixes #15984
content/docs/ui/translations.mdxis the user-facing guide for localising anapp, and read end to end it described exactly one localisation route: a
plain-string label, translated in a bundle addressed by convention. It never
mentioned the second authorized form of an
I18nLabel— the inline locale map,label: { en: 'Members', 'zh-CN': '成员' }.That omission used to cost an author nothing observable. It no longer does: the
coverage gate now reads a map's own locales, so an author who writes
{ en, 'zh-CN' }on a stack declaringsupportedLocales: ['en', 'zh-CN', 'ja-JP']gets a real
missing translation for locale "ja-JP"finding about a prop thispage gave them no vocabulary for.
What changed
One file, two additions, no restructuring:
map. Its "where it lives in the bundle" cell is the point of the row:
nowhere — the map is written on the metadata and resolved at render time.
both forms are authorized; the map is rendered but never extracted, so a
translator working from the bundle will not find those strings; coverage
counts the locales the map carries and reports the ones it omits against
supportedLocales; and no bundle key exists for a map, nor is onesynthesised from a node's position in the component tree — transcribed as
the settled refusal it is (maintainer ruling 2026-09-03, Inline
I18nLabelmaps are invisible toos i18n extractandcheck:i18n-coverage— should the extractor and the coverage gate see them? (objectstack#14412 ruling A follow-up) #14749), not as a"not yet".
The sentence the passage is built around is rendered but never extracted: two
tools treat the same prop differently and both are right — the coverage gate
reports what the author did and did not write, while the extractor refuses to
invent a key that a later reordering of two sibling components would silently
reassign.
The page's existing "inline
label:" mentions (:159,:254,:264) areabout a plain-string label as source text and are untouched.
Sources transcribed
packages/cli/src/utils/i18n-extract.tsheader — "Inline locale maps are NOTextracted — and are not 'unauthored' either", where the Inline
I18nLabelmaps are invisible toos i18n extractandcheck:i18n-coverage— should the extractor and the coverage gate see them? (objectstack#14412 ruling A follow-up) #14749 Q3 = C3 refusaland the Q2 = B1 coverage record live.
packages/spec/src/ui/i18n.zod.ts—I18nLabelSchema, the union of a plainstring and an inline locale map, and the note that both are real and neither
is deprecated.
packages/cli/src/utils/i18n-coverage.ts— the tag-matched lookup that makesa carried locale covered and an omitted one a gap.
No source file paths are linked from the page itself; docs link pages, not code.
Premise re-verified on the fresh tree
'zh-CN':appears once on the page, at:38, followed by{— bundle-filestructure, not an inline map. The page genuinely showed the second form
nowhere.
locale mapappeared zero times on the page before this change.Verification
skip-changeset:content/docs/**publishes nothing from any package.Gates run locally are listed in the report on the issue.
pnpm lintand thefull gate farm are CI's run.
Generated by Claude Code