新增与修改文案
在英文和中文两种语言下编辑文案、新增支持多语言的路由,并了解可选语言段和 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/ 中搜索页面上看到的英文文字。公开站和共享文案在主字典里,后台文案可能在功能文件里。
在两种语言里修改同一个键
在英文和中文条目的相同路径下修改值。值可以是字符串、数组,或用于带数字文案的函数:
pricing: {
title: "Plans",
credits: (count: number) => `${count.toLocaleString("en-US")} credits included`,
},不要为了改文字而重命名键,其他文件可能也在读取它。
新增文案
把键加到两份字典里
只有几条文字时,加到已有的命名空间里。新页面或新功能则单独建一个命名空间,在两个文件中放在相同的位置:
reportsPage: {
title: "Reports",
empty: "No reports yet.",
},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。
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-console | src/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 路径打开页面。使用页面上的语言切换器,页面切换到另一种语言的同一页面,所有标签随之变化。