产品要出海,第一版先上了英文。翻译做完、页面跑通,大家都觉得这件事结束了。第二版加德语,问题立刻冒出来:按钮写死了 width: 120px,「保存并继续」翻成 Speichern und fortfahren 之后,文字溢出按钮,压到了右边的图标上。再后来加阿拉伯语,整页方向没有变,返回箭头还在左上角,用户习惯从右边开始读,第一眼就找不到返回。
日期和数字更隐蔽。同一个订单日期,组件显示 01/02/2026,美国同事读成 1 月 2 日,国内同事读成 2 月 1 日,客服拿着截图对不上。金额 1234.5 在德语版里没有千分位,小数点是点,德国客户看着别扭。消息数量那一句写成 1 messages,语法错了,但没人及时发现,因为测试只看了中文版。
最麻烦的是文案本身。「确定」在几百个组件里出现四十多次,「提交成功」有七八种写法,改一句提示要全局搜索替换,还改错过两处业务含义不同的文案。这篇讲 i18n 落地:文案放哪、复数和插值怎么处理、日期数字货币怎么格式化、长词和 RTL 怎么适配、语言切换和 SEO 怎么取舍。
文案放哪:语言包、命名空间和 key 命名
文案不能留在组件里。写死在 JSX 里的中文,翻译工具提取不到,改语言时也换不掉。比较常见的做法是按语言和业务域组织语言包:一个公共命名空间放按钮、通用提示,一个业务命名空间放订单、客户、报表,组件按命名空间引用 key。
小项目里把文案放在组件旁边,包一层翻译函数,初期确实方便;但翻译工具提取不到,语言一多就会散,最后还是得收回来。
key 的命名要用语义,不要拿中文当 key,也不要把整句英文当 key。中文 key 改文案就得改 key,所有引用点跟着动;整句英文当 key 看起来可读,但句子一改,翻译记忆库和已有译文全部失效。用 order.submit、order.phoneInvalid 这种结构,改文案时 key 不动,翻译只需要更新值。
命名空间不要过度拆分。每个组件一个文件,找 key 要翻十几个目录,翻译人员也很难判断上下文。按业务域拆就够了,域内再按页面分组,超过两三百行再考虑拆细。
// src/locales/zh-CN/order.json
{
"submit": "提交订单",
"total": "共 {count} 件商品",
"phoneInvalid": "手机号格式不对"
}
// src/i18n/t.js:占位符替换加缺失回退
export function createT(messages, fallback) {
return function t(key, params = {}) {
const template = messages[key] ?? fallback?.[key] ?? key;
return template.replace(/\{(\w+)\}/g, (_, name) =>
params[name] === undefined ? "{" + name + "}" : String(params[name])
);
};
}
这段代码可以直接在浏览器控制台或 Node 里跑,把两个对象传进去就能得到翻译函数。缺 key 时先回退到默认语言,再回退到 key 本身。回退能避免页面出现空白,但也会把问题藏起来,所以开发环境要额外打一条警告,把缺失的 key 和当前语言一起打出来。
更稳的做法是在构建时检查。把所有语言的 key 集合对比一遍,缺了哪个、多了哪个,直接让检查失败。翻译是异步的,新功能上线时英文包常常晚几天,没有检查就只能等用户截图才发现。
插值与复数:不要把句子拆成碎片拼
插值看起来简单,把 {name} 替换成变量就行,但句子的语序在不同语言里不一样。中文说「共 3 件商品」,英文是 3 items,德语可能把数量放在别的位置。把句子拆成「共」「件商品」两段再拼接,翻译时语序就没法调整。正确的方式是整句作为一个 key,变量用占位符。
复数更不能用 count === 1 判断。英语只有单数和复数两类,阿拉伯语有零、一、二、少量、多量、其他六类,俄语、波兰语的规则也更复杂。手写条件判断,迟早会在某个数字上出错。Intl.PluralRules 就是干这个的,它按语言和数字返回该用哪种形式。
const rules = new Intl.PluralRules("en");
const forms = {
one: "{count} item",
other: "{count} items",
};
function itemCount(count) {
const form = rules.select(count);
return forms[form].replace("{count}", String(count));
}
console.log(rules.select(1)); // "one"
console.log(rules.select(2)); // "other"
console.log(itemCount(1)); // "1 item"
console.log(itemCount(5)); // "5 items"
阿拉伯语的分类是 zero、one、two、few、many、other,每一种都要有对应文案。不要只准备 one 和 other,否则数量是 0 或 2 的时候会落到一个不合适的句子。英语的序数词有单独规则,用 new Intl.PluralRules("en", { type: "ordinal" }) 的 select 得到 one、two、few、other 这类类别,再映射成 1st、2nd、3rd,不要自己判断。
ICU MessageFormat 的思路是把整句和分支写在同一条模板里,例如 {count, plural, one {# item} other {# items}}。它的好处是翻译人员能看到完整语境,不用猜变量放在哪。具体用哪套库、模板语法是否完全兼容 ICU,跟所选方案有关,接入前要核对,待确认。
还有一类问题不属于复数,而是语法性别。法语里「一个新的消息」和「一个新的订单」冠词不同,靠简单的占位符解决不了,需要 ICU 的 select 分支或语言包里的完整句式。遇到这种语言,不要硬用一套模板套所有名词。
日期、数字、货币和相对时间:交给 Intl,不要手拼
手拼日期是最常见的错误。year + "/" + month + "/" + day 这种写法,在中文语境里看着没问题,到了美国就变成月在前,到了德国又变成日在先。更糟的是月份从 0 开始,少加一就错一个月。用 Intl.DateTimeFormat,让运行环境按语言和地区决定顺序。
const date = new Date("2026-11-06T08:00:00Z");
const enGB = new Intl.DateTimeFormat("en-GB", {
timeZone: "UTC",
year: "numeric",
month: "2-digit",
day: "2-digit",
});
const enUS = new Intl.DateTimeFormat("en-US", {
timeZone: "UTC",
year: "numeric",
month: "2-digit",
day: "2-digit",
});
const deDE = new Intl.DateTimeFormat("de-DE", {
timeZone: "UTC",
year: "numeric",
month: "2-digit",
day: "2-digit",
});
console.log(enGB.format(date)); // "06/11/2026"
console.log(enUS.format(date)); // "11/06/2026"
console.log(deDE.format(date)); // "06.11.2026"
这三个结果依赖运行环境的 ICU 数据。现代 Node 默认带完整 ICU,浏览器也基本一致,但老版本 Node、裁剪过的运行环境或某些嵌入式 WebView 可能有差异,上线前以实际环境跑出来的结果为准,待确认。服务端渲染时一定要显式传 timeZone,否则服务器用 UTC、浏览器用本地时区,同一条数据会渲染出两个日期。
存储和展示要分开。数据库存 UTC 时间戳或带时区的 ISO 字符串,展示时按用户所在时区格式化。不要把「2026-11-06」这种纯日期当成时间戳处理,也不要在数据库里存格式化好的字符串,后续换语言就没法重排。
手拼格式
用字符串拼接年月日,代码短,但月日顺序、补零、分隔符全由开发者决定。换一个语言就要改代码,跨时区还容易差一天。
用 Intl
顺序、分隔符、月份名称由运行环境按 locale 决定,代码只描述「要年月日」。代价是要理解 locale、时区和 ICU 数据的差异。
数字和货币同理。千分位、小数点、货币符号的位置都随 locale 变。Intl.NumberFormat("de-DE").format(1234.5) 得到 "1.234,5",中文环境得到 "1,234.5"。货币还要区分「界面语言」和「交易币种」:德语界面里的订单如果是人民币,仍然要显示人民币,不能因为语言是德语就换成欧元。
console.log(Intl.NumberFormat("de-DE").format(1234.5)); // "1.234,5"
console.log(Intl.NumberFormat("zh-CN").format(1234.5)); // "1,234.5"
console.log(Intl.NumberFormat("zh-CN", {
style: "currency",
currency: "CNY",
}).format(1234.5)); // "¥1,234.50"
console.log(new Intl.RelativeTimeFormat("zh-CN").format(-1, "day")); // "1天前"
相对时间用 Intl.RelativeTimeFormat,不要自己拼「1 天前」「2 小时前」。传 numeric: "auto" 时会尽量用「昨天」这类词,默认则是「1天前」这种数字表达。两种都可以,但要在整个产品里统一,别一个页面「昨天」、另一个页面「1天前」。
Intl.NumberFormat("en-US", { currency: "CNY" }) 显示 CN¥1,234.50,德语环境则是 1.234,50 CN¥。金额展示要同时确认币种和 locale,涉及支付时还要跟后端核对小数位。布局适配:长词、RTL 和无空格语言
德语的长复合词是布局的第一道坎。Versicherungsbedingungen 这种词二十多个字母,塞进固定宽度的按钮或标签里,要么溢出,要么被截断成看不懂的片段。中文和英文的按钮宽度经验,在德语里基本失效。
阿拉伯语和希伯来语是从右往左读的。只翻译文案、不设方向,页面结构仍然是左对齐,返回图标还在左边,进度条从右往左填,用户会彻底迷失。方向不是 CSS 里把 left 改成 right 就完事,要从文档的 dir 属性开始,让浏览器处理文本方向、滚动条位置和表单控件的默认对齐。
日语和中文没有词间空格,换行规则和英文不同。一个长英文 URL 或代码片段放进中文段落,可能把容器撑开;反过来,英文界面里的中文用户名没有断行点,也会溢出。这些都要靠可换行策略和弹性布局兜底。
固定宽度和绝对定位为什么会坏
固定宽度假设了文案长度可控,绝对定位假设了元素之间的相对位置不变。这两条在单语言项目里通常成立,在多语言里几乎一定被打破:文案变长、方向翻转、图标位置互换,任何一个都会让布局错位。
.toolbar {
display: flex;
flex-wrap: wrap;
gap: 8px;
align-items: center;
}
.btn-primary {
min-width: 96px;
width: auto;
padding-inline: 16px;
margin-inline-end: 8px;
white-space: normal;
overflow-wrap: anywhere;
}
.notice {
border-inline-start: 3px solid #d0d0d0;
padding-inline-start: 12px;
}
padding-inline、margin-inline、border-inline-start 这些逻辑属性会跟着 dir 自动换边,比写死 margin-left 稳。按钮给最小宽度而不是固定宽度,允许文字换行;容器用 flex 加 flex-wrap,空间不够时换行而不是压扁。长单词再加 overflow-wrap: anywhere,避免撑破父容器。
图标要分方向。返回、前进、展开这类方向性图标,在 RTL 下应该镜像;公司 logo、播放按钮、勾选图标不要随便翻转。可以用 [dir="rtl"] 选择器只翻转指定类名,不要把整个页面的图标都 scaleX 反转。
数字和混排文本还要注意双向文本。阿拉伯语界面里夹一个英文订单号,浏览器会按 bidi 规则排列,偶尔出现数字顺序看起来奇怪的情况。不要手动反转字符串,给容器合适的 dir,必要时用 dir="auto" 让浏览器判断。规则可以参考CSS 布局与文档流。
语言切换、URL 策略和 SEO
语言放在哪里,决定了分享链接和搜索引擎能不能拿到正确版本。只存在 localStorage 或 cookie 里,用户把链接发给别人,对方打开是默认语言;搜索引擎抓取时也拿不到其他语言的内容。路径前缀 /zh/、/en/ 或者独立子域,能让每种语言有自己的 URL,分享和收录都稳定。
路径前缀
每种语言一个 URL,分享链接天然带语言,SEO 和缓存都好处理。代价是路由、静态资源和后端都要感知前缀,切换语言时要做一次跳转。
只存本地
实现最简单,不用改路由。代价是分享链接丢语言、搜索引擎只能收录默认语言,多语言内容等于白做。
切换语言时不要只改状态,要保留当前路径和查询参数,再跳转到对应语言的地址。下面的函数把路径里的语言段替换掉,没有就加在最前面。
function switchLocale(next, pathname, search) {
const supported = ["zh", "en", "de"];
const parts = pathname.split("/").filter(Boolean);
if (supported.includes(parts[0])) {
parts[0] = next;
} else {
parts.unshift(next);
}
return "/" + parts.join("/") + search;
}
console.log(switchLocale("de", "/en/articles/order", "?tab=detail"));
// /de/articles/order?tab=detail
SEO 方面,每种语言页面要有自己的 canonical,指向自己,不要所有语言都 canonical 到中文页。同时用 hreflang 告诉搜索引擎这些页面是同一内容的不同语言版本,并给一个 x-default 作为兜底。
<link rel="alternate" hreflang="zh-CN" href="https://docs.czgrzx.cn/zh/articles/order">
<link rel="alternate" hreflang="en" href="https://docs.czgrzx.cn/en/articles/order">
<link rel="alternate" hreflang="de" href="https://docs.czgrzx.cn/de/articles/order">
<link rel="alternate" hreflang="x-default" href="https://docs.czgrzx.cn/en/articles/order">
这套标签要和页面里的 canonical 对得上。语言代码用规范的 BCP 47 写法,中文区分 zh-CN 和 zh-TW,不要只写 zh 又指望搜索引擎自己猜。规则见HTML 元信息与 SEO,多语言站点最容易在这里出问题。
语言包要按需加载。把所有语言的 JSON 打进主包,首屏会多出几百 KB,而且大部分用户永远用不到。用动态导入按语言拆包,切换时再加载,加载期间给一个轻量的占位或骨架,不要让页面闪一下空白。默认语言可以直接内联进主包,减少第一次请求。
const loaders = {
"zh-CN": () => import("./locales/zh-CN/order.json"),
"en": () => import("./locales/en/order.json"),
"de": () => import("./locales/de/order.json"),
};
const messages = await loaders[locale]();
翻译流程里最容易被跳过的是最后一步。语言包合并进去、构建通过,不代表页面能看。德语要检查长词换行,阿拉伯语要检查方向和图标,日语要检查断行,每种语言都要用真实数据走一遍关键页面。
完整场景:英文版上线后被德语撑破的工具栏
需求是后台系统支持中文、英文、德文三种语言,日期按用户 locale 显示,金额按订单币种显示,分享链接要保留语言,后续还要能加语言。第一版的做法很省事:按钮固定宽度,日期用字符串拼,复数用三元判断,语言存在 localStorage。
// 第一版:三个问题写在一起
const label = count === 1 ? "item" : "items";
const dateText = year + "/" + month + "/" + day;
const html = "<button style='width:120px'>" + t("saveAndContinue") + "</button>";
德语上线后,工具栏先出问题。Speichern und fortfahren 比中文长一倍,固定宽度装不下,文字压到了图标;日期在英文环境显示成 01/02/2026,月日顺序靠猜;数量为 1 时显示 1 item,数量为 0 时也显示 0 items,英语没问题,到了阿拉伯语就不对。语言切换后刷新页面,又回到中文,因为地址里没有语言信息。
修复分三块。按钮改成最小宽度加逻辑内边距,允许换行;日期和数字统一走 Intl;复数和语言切换按前面说的方式重写。下面是最小改动的核心部分。
// 日期按 locale 格式化,服务端渲染也固定时区
function formatDate(iso, locale, timeZone = "UTC") {
return new Intl.DateTimeFormat(locale, {
timeZone,
year: "numeric",
month: "2-digit",
day: "2-digit",
}).format(new Date(iso));
}
console.log(formatDate("2026-11-06T08:00:00Z", "en-GB")); // "06/11/2026"
console.log(formatDate("2026-11-06T08:00:00Z", "en-US")); // "11/06/2026"
/* 按钮不再定宽,长文案可以换行,方向由 dir 决定 */
.btn-primary {
width: auto;
min-width: 96px;
padding-inline: 16px;
white-space: normal;
overflow-wrap: anywhere;
}
上线后仍然有一批问题,大多不是翻译本身,而是格式化和布局没跟着语言走。
| 现象 | 真实原因 | 第一步查什么 |
|---|---|---|
| 德语按钮文字溢出,压到图标 | 按钮写死宽度,文字不换行 | 查 CSS 里的 width 和 white-space |
| 日期 01/02/2026 被读成不同月份 | 手拼年月日,没有按 locale 格式化 | 查代码里有没有 Intl.DateTimeFormat |
| 阿拉伯语页面方向没变,返回键还在左边 | 只翻了文案,没设 dir,布局用了 left 和 right | 查 html 的 dir 和 CSS 里的物理属性 |
| 切换英文后刷新又变回中文 | 语言只存 localStorage,URL 没带语言 | 查地址栏和语言初始化逻辑 |
| 新增语言后页面直接显示 key | 语言包缺 key,回退逻辑没生效 | 查缺失检查和 fallback 配置 |
| 英文首屏空白了一瞬才出文案 | 语言包按需加载,加载期间没有占位 | 看网络请求时序和首屏渲染逻辑 |
表格里第三条最容易被低估。语言包翻译得再准,页面方向不对,用户仍然找不到北。RTL 不是「加一个 CSS 文件」的事,它会影响布局、图标、滚动、表单对齐,必须作为单独的一轮回归来做。
边界与代价:什么时候不该做多语言
国际化是一项持续成本,不是上线一次就结束的功能。每加一门语言,文案、截图、测试用例、布局回归都要跟着加一份。
- 只有一种语言、用户也只在一种语言环境里,不要提前做多语言。抽象语言包和格式化会拖慢开发,收益为零。
- 语言数量上来之后,key 的维护成本是乘法。新增一个字段要改 N 个语言包,翻译延迟会直接变成线上缺失文案。要有缺失检查和发布门槛。
- 机器翻译只能当草稿。业务术语、法律文案、按钮动词的细微差别,机器翻完必须有人审,否则会出现「删除」被翻成「释放」这种事故。
- RTL 支持的成本常被低估。它不是加个
dir="rtl"就完,图标、图表、进度条、轮播、滚动条都可能要单独处理。 - 按需加载语言包会带来额外的网络请求和加载态。语言切换时要处理失败重试,不能让用户卡在半翻译状态。
- 多语言页面的缓存要按语言区分,CDN 的
Vary或 URL 策略没设计好,会把中文页面发给英文用户。 - 不要翻译用户生成内容、品牌名、代码、日志。这些翻了反而增加误解,语言包里也不该出现它们。
- SEO 的 hreflang 要成对维护,漏一个或指错地址,搜索引擎可能整组忽略。语言多了以后,最好由路由配置自动生成,而不是手写。
判断标准:如果目标用户真的会在不同语言下使用产品,并且内容需要被搜索到,多语言就值得做;如果只是内部工具、用户都在一个地区,先把单语言的文案和格式规范做好更实际。
今天就能验证的练习,和小结
- 在浏览器控制台依次运行
Intl.NumberFormat("de-DE").format(1234.5)、new Intl.PluralRules("en").select(1)、new Intl.RelativeTimeFormat("zh-CN").format(-1, "day"),核对输出是不是 "1.234,5"、"one"、"1天前"。 - 把一个按钮的宽度写死,填入德语长文案,观察溢出;再改成
min-width加padding-inline,确认文字能换行且不压图标。 - 给一个卡片容器加
dir="rtl",看返回图标、边框、内边距是否跟着换边,记录哪些地方用了 left 和 right。 - 给一个页面加三行 hreflang 和对应的 canonical,用浏览器查看源代码,确认语言代码和 URL 都对得上。
- 在项目里搜中文文案,统计有多少条写死在组件里;挑一个页面抽成 key,跑一次缺失 key 检查。
国际化真正要改的不是文案,而是「所有写死的假设」:假设文案长度固定、假设从左到右、假设日期只有一种顺序、假设金额只有一种格式。把这些假设一个个拆掉,产品才算真的能换语言。
这是本组最后一篇。写到这里,「框架与库」这一组就收束了。前面讲组件怎么拆、React 和 Vue 怎么组织、状态放哪、路由怎么设计、样式怎么隔离、组件库怎么沉淀,再往后是数据怎么请求和缓存、表单怎么校验和提交、文案和格式怎么适配。这些部分单独看都是技巧,合起来才是一个能长期维护的前端应用:组件有边界,数据有来源,状态有归属,交互有反馈,文案和格式不写死。
但一个应用能维护,不等于每次都能稳定地交付。构建能不能复现、静态检查能不能拦住问题、测试覆盖到哪一层、依赖升级会不会把项目打挂、环境变量有没有漏配,这些属于另一组问题。工程化那一组会接着讲构建、检查、测试、依赖和发布流程;这篇先把「应用本身怎么组织」讲完整,后面才谈怎么把它稳定地发出去。