Tanplate Docs

多语言

Manifest locale、严格 en/zh 消息目录、语言偏好和 HTML lang。

Web 的多语言由 Manifest 声明支持范围,由严格消息目录保证每个 locale 的 key 完整。当前项目正式启用 enzh,首次访问默认使用英文,用户可以从 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 必须共用同一严格目录。

On this page