localization-engineer

本地化工程师

概述

提供与框架无关的多语言应用构建模式，涵盖从语言区域检测到翻译渲染的完整 i18n 流程。解决 ICU 消息格式化、CLDR 复数规则、RTL 支持和 SEO 等通用问题。

适用场景： 添加多语言支持、语言区域感知格式化、RTL 布局、复数形式处理、翻译管理、语言区域协商、多语言 SEO。

不适用场景： 没有国际化计划的单语言应用、语言区域永不变化的内容、没有动态内容的纯服务端渲染静态站点。

关键决策： 新项目如需编译时类型安全和精简的打包体积，选择 Paraglide。如需广泛的生态系统支持，或在现有项目中逐步采用，选择 i18next。请参阅下方的库选择表。

库选择

标准	Paraglide JS	i18next
架构	编译时、可进行树摇优化的函数	运行时、基于插件的生态系统
类型安全	完整（生成带类型的消息函数）	部分（需要手动设置类型）
打包体积	精简（仅打包实际使用的消息）	运行时较大（基础约 40 kB，另加插件）
复数形式处理	通过消息格式插件	内置 CLDR 复数类别
框架支持	SvelteKit、TanStack Start、React Router、Astro、vanilla	React、Vue、Svelte、Angular、Node、vanilla
ICU 支持	通过 inlang-icu-messageformat-1 插件	通过 i18next-icu 插件
翻译工具	Fink 编辑器、Sherlock VS Code 扩展	Locize、i18next-parser，以及许多集成
语言区域策略	内置（cookie、URL、header、自定义）	通过 i18next-browser-languagedetector 插件
SSR 支持	基于 AsyncLocalStorage，按请求隔离	每个请求使用单独的 i18next 实例
学习曲线	低（编译器会生成简单函数）	中（API 范围广，插件众多）
命名空间支持	每个语言区域使用扁平消息文件	支持多命名空间，并可按路由延迟加载
消息格式	Inlang 格式，或通过插件使用 ICU	i18next JSON v4，或通过插件使用 ICU
社区规模	不断壮大（inlang 生态系统）	庞大（自 2015 年起发展成熟）
最适用场景	注重打包体积和类型安全的新项目	需要广泛生态系统支持的现有项目

快速参考

模式	方法	要点
ICU 复数形式	{count, plural, one {# item} other {# items}}	CLDR 类别：zero、one、two、few、many、other
ICU 选择（性别）	{gender, select, male {He} female {She} other {They}}	支持按性别和变体生成消息
ICU 序数选择	{rank, selectordinal, one {#st} two {#nd} other {#th}}	序数后缀因语言而异
数字格式化	Intl.NumberFormat(locale, options)	平台内置货币、百分比和单位格式化
日期格式化	Intl.DateTimeFormat(locale, options)	避免手动构造日期字符串
相对时间	Intl.RelativeTimeFormat(locale, options)	根据语言环境输出「3 小时前」「2 天后」
列表格式化	Intl.ListFormat(locale, { type: 'conjunction' })	根据语言环境使用连接词输出「Alice、Bob 和 Charlie」
RTL 布局	CSS 逻辑属性（inline-start、inline-end）	将 left/right 替换为对应的逻辑属性
RTL 检测	<html dir="rtl" lang="ar">	根据语言环境设置 dir 属性
从 URL 获取语言环境	/en/about、/de/about	最利于 SEO，且对用户清晰明了
从 Cookie 获取语言环境	locale=de cookie	在多个会话间保留偏好设置
从标头获取语言环境	Accept-Language: de-DE,de;q=0.9,en;q=0.8	浏览器偏好设置，可用作后备选项
Hreflang 标签	<link rel="alternate" hreflang="de" href="...">	每种语言环境各设置一个，并添加 x-default
命名空间拆分	按功能或路由对翻译进行分组	通过延迟加载减小资源包体积
消息提取	自动化工具扫描源代码中的翻译键	防止出现无对应引用或缺失的翻译
伪本地化	生成伪翻译以测试布局	发现文本截断、溢出和硬编码字符串

常见错误

错误	正确做法
将翻译片段拼接成句子	使用 ICU 消息格式和占位符，确保不同语言环境下的语法正确
在 RTL 排版中使用 margin-left/padding-right	使用 CSS 逻辑属性（margin-inline-start、padding-inline-end）
将复数规则硬编码为 count === 1	使用 CLDR 复数类别（有些语言有零、二、少量、多量等形式）
仅通过 IP 地理位置判断语言环境	依次使用 Accept-Language 标头、Cookie，最后再使用地理位置
hreflang 标签中缺少 x-default	始终包含 <link rel="alternate" hreflang="x-default"> 作为回退
每种语言环境使用一个庞大的翻译文件	按功能拆分为多个命名空间，以便延迟加载并提高可维护性
为每个组件创建新的 i18next 实例	在应用初始化时创建一次，并在各组件间共享
通过字符串拼接格式化日期	使用 Intl.DateTimeFormat 按语言环境格式化日期
将语言环境存储在组件状态中	将其存储在 URL 路径或 Cookie 中，以兼容 SSR 并便于共享
在客户端和服务端使用不同的 i18n 键	在客户端和服务端之间共享翻译文件和键结构
假设所有语言的文本扩展幅度都相同	为德语/芬兰语翻译预留比英语多 30-40% 的空间
将文本嵌入图片	使用 CSS/SVG 文本覆盖层，以便动态应用翻译
使用语言代码但不指定地区变体	在日期、货币等格式存在差异时，使用 en-US 与 en-GB

委派

• 审查代码库中的硬编码字符串：使用 Explore Agent 扫描组件，查找未翻译的面向用户文本
• 搭建完整的 i18n 流水线：使用 Task Agent 配置语言环境检测、翻译加载和渲染
• 规划本地化架构：使用 Plan Agent 设计命名空间结构、语言环境策略和翻译工作流
• 检查翻译覆盖率：使用 Task Agent 对比翻译文件，找出不同语言环境中缺失的键
• 审查代码是否符合 i18n 要求：委派给 code-reviewer Agent

如果有 tanstack-start 技能，请将服务端中间件和 SSR 语言环境模式委派给它。 如果有 tanstack-router 技能，请将基于 URL 的语言环境路由模式委派给它。 如果有 sveltekit 技能，请将 SvelteKit 特有的路由和钩子模式委派给它。 如果有 seo 技能，请将高级 hreflang 和站点地图模式委派给它。

参考资料

• Paraglide JS 模式 -- 编译时 i18n，支持类型化消息函数、SvelteKit/TanStack Start/React Router 集成和语言环境策略
• i18next 模式 -- 运行时 i18n，支持插件生态系统、React/Vue/Svelte/原生集成、命名空间和语言检测
• ICU 消息格式 -- 复数形式、选择、数字/日期格式化、嵌套消息、RTL 支持和 hreflang SEO