新增与修改文案

在英文和中文两种语言下编辑文案、新增支持多语言的路由,并了解可选语言段和 i18n 校验器的工作方式。

每个页面都由同一个路由文件提供英文和简体中文两个版本。英文不带前缀(/pricing),中文在 /zh 下(/zh/pricing)。组件里不写文案。文案来自字典,两种语言的键完全一致。

准备工作

  • 一个能用 pnpm dev 运行的项目。
  • 两种语言的文字。只存在于一份字典里的键就是 bug,即使你正在测试的那种语言看起来一切正常。
  • 如果要新增整个页面,请按新增后台或工作台页面或替换落地页和定价页操作。本指南说明它们依赖的文案与路由机制。

了解文案放在哪里

存放位置文件读取方式
主字典src/i18n/locales/en/messages.ts 和 src/i18n/locales/zh/messages.ts通过 useI18n() 或 getDictionary(locale) 得到的 t("shell.nav.dashboard"),或用 getMessageNamespace(locale, "publicSite") 取整个命名空间
功能文案文件src/i18n/*.ts,例如 admin-plans.ts、auth-pages.ts、system-pages.ts导出的按语言索引的表:adminEditingMessages[locale]

两者保存的是同一类数据。主字典存放共享文案、公开站文案和所有导航标签。功能文件把某一块后台区域的文案和它的类型放在一起。你正在改的代码用哪一种,就沿用哪一种。

辅助函数都在 src/i18n/messages.ts 中:

函数用途
locales、defaultLocale["en", "zh"] 和 "en"
normalizeLocale(value)把路由参数转成 Locale;无法识别的值一律当作 en
localizedPath(path, locale)en 返回 /pricing,zh 返回 /zh/pricing。所有站内链接都用它生成
switchLocalePath(path, locale)同一页面在另一种语言下的路径,语言切换器使用它
getDictionary(locale)在路由组件之外获得 { locale, t }
getMessageNamespace(locale, key)把某个顶层命名空间作为带类型的对象取出,包含数组和格式化函数
localeToIntlTag(locale)供 Intl 数字和日期格式化使用的 en-US 或 zh-CN

修改已有文案

找到对应的键

在两份 messages.ts 和 src/i18n/ 中搜索页面上看到的英文文字。公开站和共享文案在主字典里,后台文案可能在功能文件里。

在两种语言里修改同一个键

在英文和中文条目的相同路径下修改值。值可以是字符串、数组,或用于带数字文案的函数:

src/i18n/locales/en/messages.ts
pricing: {
  title: "Plans",
  credits: (count: number) => `${count.toLocaleString("en-US")} credits included`,
},

不要为了改文字而重命名键,其他文件可能也在读取它。

新增文案

把键加到两份字典里

只有几条文字时,加到已有的命名空间里。新页面或新功能则单独建一个命名空间,在两个文件中放在相同的位置:

src/i18n/locales/en/messages.ts
reportsPage: {
  title: "Reports",
  empty: "No reports yet.",
},
src/i18n/locales/zh/messages.ts
reportsPage: {
  title: "报表",
  empty: "还没有报表。",
},

位于某个模块 // @module:<key> 区域里的键属于该模块。你自己的键要放在这些区域之外。

在组件里读取

在 {-$locale} 下的路由组件中:

import { useI18n } from "@/i18n/use-i18n";

const { locale, t } = useI18n();
return <h1>{t("reportsPage.title")}</h1>;

在通过属性接收 locale 的组件中,读取整个命名空间:

import { getMessageNamespace, type Locale } from "@/i18n/messages";

const copy = getMessageNamespace(locale, "reportsPage");

t() 的类型以英文字典为准,所以拼错的键会让 pnpm typecheck 失败。运行时,如果中文字典里缺少某个键,页面上会直接显示这个键名。

检查两份字典的键是否一致

pnpm validate:app-i18n

其中的 dictionaries-carry-the-same-keys 检查会运行 validateLocaleParity(),逐一比较键路径。任一语言多出或缺少键时,检查失败并列出这些键。

新增支持多语言的路由

在 {-$locale} 下创建文件

所有页面路由都在 src/routes/{-$locale}/ 里。{-$locale} 是 TanStack Router 的可选路径段。同一个文件在没有 locale 参数时响应 /reports,在 locale: "zh" 时响应 /zh/reports。

src/routes/{-$locale}/reports.tsx
import { createFileRoute } from "@tanstack/react-router";
import { normalizeLocale } from "@/i18n/messages";

export const Route = createFileRoute("/{-$locale}/reports")({
  component: ReportsPage,
});

function ReportsPage() {
  const { locale } = Route.useParams();
  return <ReportsView locale={normalizeLocale(locale)} />;
}

不要创建 src/routes/zh/ 目录,也不要为每种语言各写一个文件。这两种做法都会让 pnpm validate:route-i18n 失败。

未知语言交给父路由处理

src/routes/{-$locale}.tsx 是所有页面的父路由。第一个路径段不是已知语言时它返回 not found,并把解析出的 locale 放进路由上下文,useI18n() 读取的就是它。页面里不需要重复这项检查。

按语言生成链接和页面描述

链接用 localizedPath() 生成。公开页面把本地化后的路径传给 buildMeta(),并加上 hreflang 互链,写法参考 src/components/marketing/example-landing.tsx 中的 buildHomeHead()。根文档会根据 URL 自动设置 <html lang>(en 或 zh-Hans)。

重新生成路由树

运行一次 pnpm dev。它会重写 src/routeTree.gen.ts 收录新路由。在此之前 pnpm typecheck 会失败。

了解校验器检查什么

校验器关于 i18n 的断言
pnpm validate:route-i18n所有页面路由都在 src/routes/{-$locale}/ 下;不存在 src/routes/zh/ 文件;父路由校验语言;首页是围绕同一个共享组件的单个路由
pnpm validate:app-i18n外壳、导航标签、登录、系统、初始化和公开页面都从字典读取文案;导航项带有 labelKey;清单中的字符串没有被硬编码
pnpm validate:beui-consolesrc/i18n/ 下每个后台文案文件(文件名以 admin、asset、email、support、auth、system、billing 或 config 开头)都有键完全一致的 en 和 zh 条目,且没有其他语言
pnpm validate:system系统状态页及其文案

pnpm validate:app-i18n 还会比较主字典的键集合,并指出只存在于一种语言的键。

增加第三种语言

语言列表是 src/i18n/messages.ts 中的 locales 常量,每一项对应一份字典,并在 localeHrefLang 和 localeToIntlTag 中有对应的标签。后台文案文件和 pnpm validate:beui-console 只接受 en 和 zh,因此增加第三种语言需要修改这些文件和这个校验器。

验证

pnpm typecheck
pnpm validate:route-i18n
pnpm validate:app-i18n
pnpm validate:beui-console

分别用英文路径和 /zh 路径打开页面。使用页面上的语言切换器,页面切换到另一种语言的同一页面,所有标签随之变化。

下一步