Localization

The docs system resolves content by locale and adapter. English shared content is the canonical fallback. Locale overlays can replace individual sections while preserving the same slug and route structure.

Routes follow:

/{locale}/{adapter}/docs/{slug}

Current locales:

• en
• zh-cn

Current adapters:

• react
• vanilla
• vue
• solid
• svelte

Docs content is layered:

1. shared/<locale>/<slug>.md
2. <adapter>/<locale>/<slug>.md
3. fallback to en when a locale file is missing
4. fallback to React adapter overlay only when an adapter-specific overlay is missing

Adapter overlays should be used only when the page truly differs by adapter. Do not duplicate shared content just to restate the same contract.

Localize user-facing prose:

• Page title and summary.
• Setup instructions.
• Example labels.
• Troubleshooting suggestions.
• Validation explanations.

Keep technical identifiers stable:

• Slugs.
• Section IDs in [id:...].
• Package names.
• Data attributes.
• ARIA attributes.
• Rule IDs.
• Command names.

Stable identifiers make translated docs easier for agents and validators to cross-reference.

When writing shared docs, avoid hard-coding a single adapter route unless the destination is intentionally adapter-specific. Prefer prose such as "open the route-local quick start" or link from adapter overlays where the correct adapter is known.

When writing adapter overlays, link to the same adapter route:

[Adapter Integration](/en/vue/docs/adapter-integration)

This prevents Vue, Solid, and Svelte pages from sending readers into React-only setup instructions.

Examples can localize visible labels while keeping behavior contracts stable:

• Option IDs remain stable.
• value fields remain stable unless the example is explicitly locale-specific.
• Accessible names are translated.
• aria-label and helper text are translated.
• data-ui and data-slot never change by locale.

Run:

pnpm content:build
pnpm content:check

Content checks validate frontmatter, links, generated indexes, and stale artifacts. They do not replace native-speaker review for translated prose.

• Translating package names or rule IDs.
• Changing slugs between locales.
• Hard-coding React links from shared pages.
• Letting untranslated fallback hide docs debt.
• Localizing visible text but forgetting accessible labels.

• Slug and section IDs match the canonical page.
• Technical identifiers are unchanged.
• Adapter-specific pages link to the current adapter route.
• Examples translate visible and accessible text together.
• Fallback pages are tracked as docs debt.