Skip to content

docs(i18n): document inline I18nLabel locale maps in the translations guide - #16250

Merged
baozhoutao merged 1 commit into
mainfrom
claude/issue-15984-translations-inline-locale-maps
Sep 6, 2026
Merged

docs(i18n): document inline I18nLabel locale maps in the translations guide#16250
baozhoutao merged 1 commit into
mainfrom
claude/issue-15984-translations-inline-locale-maps

Conversation

@claude

@claude claude Bot commented Sep 6, 2026

Copy link
Copy Markdown
Contributor

Fixes #15984

content/docs/ui/translations.mdx is the user-facing guide for localising an
app, 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 declaring supportedLocales: ['en', 'zh-CN', 'ja-JP']
gets a real missing translation for locale "ja-JP" finding about a prop this
page gave them no vocabulary for.

What changed

One file, two additions, no restructuring:

  • A row in "What you can translate" for a label written as an inline locale
    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.
  • A bullet in "Current boundaries" carrying the four statements in order:
    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 one
    synthesised from a node's position in the component tree
    — transcribed as
    the settled refusal it is (maintainer ruling 2026-09-03, Inline I18nLabel maps are invisible to os i18n extract and check: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) are
about a plain-string label as source text and are untouched.

Sources transcribed

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-file
    structure, not an inline map. The page genuinely showed the second form
    nowhere.
  • locale map appeared 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 lint and the
full gate farm are CI's run.


Generated by Claude Code

… 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
@claude claude Bot added the skip-changeset PR has no user-facing published change; bypasses the changeset gate label Sep 6, 2026
@github-actions github-actions Bot added size/s documentation Improvements or additions to documentation labels Sep 6, 2026
@baozhoutao
baozhoutao marked this pull request as ready for review September 6, 2026 08:14
@baozhoutao
baozhoutao enabled auto-merge September 6, 2026 08:14
@baozhoutao
baozhoutao added this pull request to the merge queue Sep 6, 2026
Merged via the queue into main with commit 8adb9e8 Sep 6, 2026
37 checks passed
@baozhoutao
baozhoutao deleted the claude/issue-15984-translations-inline-locale-maps branch September 6, 2026 08:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation size/s skip-changeset PR has no user-facing published change; bypasses the changeset gate

Projects

None yet

2 participants