feat(ADR-0046): per-locale documentation content (doc i18n)#1848
Merged
Conversation
Docs can ship localized bodies via sibling `src/docs/<name>.<locale>.md` variant files (flat siblings; base `<name>.md` is the default + fallback), or inline `translations` for TS-first code packages. - spec: DocSchema.translations + resolveDocLocale (exact → primary subtag → base, per-field fallback, strips the map) - cli/collect-docs: fold variants into the base doc; lint orphan/duplicate variants + apply the v1 MDX/image bans to variant content - rest: /meta/doc (list + single) collapses to the request's Accept-Language/?locale and returns one body; doc detail bypasses cache - setup/studio: built-in overview docs ship zh translations (inline) - showcase: showcase_index.zh.md demonstrates the flat-file variant path Console already sends the UI language as Accept-Language, so doc content localizes on a language switch with no client change. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
github-actions
Bot
added
size/m
documentation
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.
Why
The console runs in many languages, but
docmetadata (ADR-0046) shipped a single body — so a Chinese console rendered English docs. This adds per-locale documentation content, reusing the REST layer's existingAccept-Languagenegotiation, so docs localize on a language switch.What
Authoring — two paths, both flat (ADR-0046's no-subdirectory rule holds):
src/docs/<name>.<locale>.md(e.g.crm_lead_guide.zh.md,..pt-BR.md). Base<name>.mdis the default + fallback.translationson theDocobject.Layers
DocSchema.translations(locale → {label?,description?,content}) +resolveDocLocale(doc, locale): collapses to the best match (exact → primary subtagzh-CN→zh→ base) with per-field fallback, and strips thetranslationsmap.translations; lints orphan + duplicate variants and applies the v1 MDX/image bans to variant content too./meta/doc(list + single) resolves the request locale from the existingAccept-Language/?localepath, returns one localized body, and never shipstranslations. Doc detail bypasses the response cache so a language switch can't return a stale-locale body.zhtranslations (inline).showcase_index.zh.mddemonstrates the flat-file variant path.No console change needed: it already sends the active UI language as
Accept-Language(createAuthenticatedFetch.ts).Verification
resolveDocLocale(exact/subtag-fallback/per-field-inherit/unknown) — 11/11; collect-docs variant fold + orphan + MDX-ban-on-variant — 16/16. All changed packages build/typecheck clean.GET /meta/doc/setup_overviewwithAccept-Language: zh→ "Setup 概览" + Chinese body,translationsstripped; default → English. Flat-fileshowcase_indexvariant → Chinese.<html lang=zh>) renders the Setup doc fully in Chinese (用户与认证 / 角色与权限 / 记录可见性), inlinesys_userhighlighted. Screenshot captured.🤖 Generated with Claude Code