多语言
Manifest locale、严格 en/zh 消息目录、语言偏好和 HTML lang。
Web 的多语言由 Manifest 声明支持范围,由严格消息目录保证每个 locale 的 key 完整。当前项目正式启用 en 与 zh,首次访问默认使用英文,用户可以从 Header 切换中文。
配置语言
{
"locale": {
"default": "en",
"supported": ["en", "zh"]
}
}default 必须包含在 supported 中,列表不能重复。修改后运行初始化器生成公共配置;不存在完整消息目录的 locale 会被拒绝。
消息与消费
composables/i18n/messages.ts:完整 en/zh 文案和类型化 key。composables/i18n/locale.ts:默认回退、浏览器偏好、跨组件事件和<html lang>。composables/i18n/use-i18n.ts:页面与组件使用的locale/t()hook。@tanplate/ui:缺失 locale、key 或插值变量时显式失败。
组件不得内联第二份翻译 map。服务端或 route metadata 使用默认 locale 的确定性 translate;交互组件使用 useI18n() 响应语言切换。
当前 URL 语义
首版语言偏好保存在浏览器 localStorage,并同步更新根 lang;URL 不包含 locale 段。canonical 因此仍指向同一页面 URL,不生成不存在的 /en、/zh route 或 hreflang。
如果未来引入 locale URL,需要同时改变 TanStack route、canonical/hreflang、内容索引、redirect、sitemap 和偏好迁移,不能只替换语言切换按钮。
新增或修改文案
新增 key 时一次性补齐所有支持语言,并运行 Web typecheck、单元测试和 tests/design-i18n-seo.spec.ts。Homepage、Header/Footer、状态文案和页面 SEO 必须共用同一严格目录。