10 个常见的 i18n 错误及其避免方法

一个开发者在 JSX 中直接编写按钮标签：<button>Submit Order</button>。

該應用程式以英語版本發布，運作正常。六個月後，該公司向德國拓展。

本地化团队发现了 2000+ 的硬编码字符串。后续改造需3周并导致47个错误。

在编写第一个组件之前，设置一个翻译框架（例如 next-intl、react-i18next、vue-i18n）。

创建一个资源文件结构（例如 messages/de.json），并通过翻译键（如 t('checkout.submitButton')）引用所有字符串。

添加一个 lint 规则或 pre-commit 钩子，用于标记 UI 组件中的原始字符串字面量。

一个翻译文件包含公司名称 'CloudForge Inc.' 和技术术语 'OAuth 2.0 Token' 作为可翻译的字符串。

西班牙翻译将「CloudForge」翻译为「ForjaNube」，并将「OAuth 2.0 Token」翻译为「token OAuth 2.0」。

结果：用户无法以其真实名称找到该公司，阅读西班牙文档的开发人员会被翻译得不熟悉的专业术语所困惑。

创建一个“不翻译”词汇表，列出所有必须保持不变的品牌名称、产品名称、法定实体和专业术语。

使用单独的命名空间或专用键来处理不可翻译的内容。许多 i18n 工具支持“锁定”段，译者无法修改。

在你的翻译文件中添加译者注释/描述以解释上下文：'这是一个商标名——不翻译' 或 '术语——保留英文'。

开发者写道：'You have ' + count + ' items in your ' + cartType + ' cart' — 在英语中完美运行。

德语翻译收到三个独立的片段，无法组成一个语法正确的句子，因为词序必须改变。

结果：德语用户看到 'Sie haben 5 Artikel in Ihrem Warenkorb Standard'——生硬且不专业。

用带占位符的单一消息键替代拼接：'cart.summary': '你在'{cartType}'购物车中有{count}件商品'

将变量作为参数传递给翻译函数：t('cart.summary', { count: 5, cartType: 'Premium' }).

翻译者可以自由调整：'你的'{cartType}'购物车中有{count}件商品'——语法正确的德语。

开发者写道：count + (count === 1 ? ' Datei' : ' Dateien') —— 正确处理德语。

波兰语翻译需要4种形式：1 plik、2-4 pliki、5-21 plików、22-24 pliki。简单的三元运算无法表达这一点。

结果：波兰用户看到 '5 pliki'（错误形式）而非 '5 plików'（正确形式），应用看起来像是坏掉了。

用 ICU 语法定义消息：'fileCount': '{count, plural, one {# Datei} other {# Dateien}}'.

翻译者为他们的语言提供所有必需的复数形式。波兰语：'{count, plural, one {# plik} few {# pliki} many {# plików} other {# pliku}}'。

你的 i18n 库在运行时会基于活动区域设置的 CLDR 规则自动选择正确的形式。

设计师创建了一个包含 5 个按钮的导航栏，每个按钮宽度恰好为 100px——在英文界面看起来很棒。

德语翻译：'Settings' 将变为 'Einstellungen'（13 对比 8 字符），'Submit' 将变为 'Absenden'（8 对 6）。导航栏溢出。

结果：在移动设备上，按钮会堆叠在一起，或者文本被截断，从而使德国用户的导航无法使用。

将固定宽度替换为 min-width、max-width 和 Flex 布局。使用 CSS Grid 或 Flexbox 动态分配空间。

将文本容器设置为换行：使用 overflow-wrap: break-word，并在可翻译的内容上避免 white-space: nowrap。

使用伪本地化对 UI 进行测试，将所有字符串扩展 40% 以模拟最坏情况——在发送字符串给翻译人员之前。

开发者将日期格式化为 MM/DD/YYYY，将价格格式化为 $1,234.50——这对美国用户是正确的。

德国用户看到日期 03/04/2025，并将其解读为 3 月 4 日（DD/MM/YYYY 规则）。价格 $1,234.50 看起来应该是 1.234,50。

结果：用户为错误的日期预订了航班，并质疑价格格式。在德国市场，支持工单数量上涨了15%。

用 Intl.DateTimeFormat(locale) 处理日期，用 Intl.NumberFormat(locale, { style: 'currency', currency }) 处理价格，替代手动格式化。

内部以 ISO 8601 格式（YYYY-MM-DD）存储数据，仅在显示时按照用户的 Locale 进行格式化。

用至少五个不同的区域设置（en-US、de-DE、ja-JP、ar-SA 和 zh-CN）测试关键的日期/数字显示，以覆盖最重要的格式变体。

开发人员在整个应用中使用 margin-left: 16px 和 text-align: left——这是标准的从左到右（LTR）做法。

应用程序在沙特阿拉伯启动。返回箭头显示为前进方向，侧边栏出现在错误的一侧，数字数据对齐错误。

结果：阿拉伯用户在 30 秒内离开应用。团队需要 4 周的紧急 CSS 重构来解决问题。

用逻辑等价属性替换所有物理 CSS 属性：margin-left → margin-inline-start，padding-right → padding-inline-end，text-align: left → text-align: start。

在 HTML 根元素上根據活動 Locale 設定 dir 屬性。使用 :dir(rtl) 的 CSS 偽類進行 RTL 覆寫。

检查所有图标的方向含义。用对称版本替换定向图标，或在 RTL 场景中使用 CSS transform: scaleX(-1)。

设计师直接在图片中嵌入文本“Start Your Free Trial”来创建促销横幅。

本地化团队翻译了所有 UI 字符串，但德语页面上的横幅仍然显示英文文本。

结果：德语着陆页有一个让人恼火的英文横幅。为15种语言创建本地化横幅需要3天的设计工作，推迟上线。

使用 CSS 将可翻译文本覆盖在背景图片上：通过对图像容器应用绝对定位来定位文本层。

对于信息图或图表，使用带有 <text> 元素的 SVG，引用翻译键而不是嵌入原始字符串。

在营销材料中的应用程序屏幕截图，使用 Fastlane（移动）或 Playwright（Web）等工具自动生成截图，覆盖每个语言区域的屏幕。

开发人员新增一个“Premium Features”区域，包含15个新的翻译键。英文版本会立即发布。

法语翻译尚未完成。法语页面显示原始键：'premium.feature1.title', 'premium.feature1.description'。

结果：法语用户看到一个充满开发者端键名的损坏页面。支持团队收到数十个错误报告。

在 i18n 配置中设置一个回退语言链：缺失的法语（fr）键将自动回退到英语（en）。

添加一个 Missing-Key 处理程序，当遇到未翻译的键时，将其记录到你的监控系统（如 Sentry、Datadog），以免影响用户体验。

创建一个翻译覆盖率仪表板，跟踪每个 Locale 的完成度；如果覆盖率低于阈值（例如 95%），则阻止版本发布。

开发人员将 MySQL 数据库配置为 latin1 排序规则（旧标准）。应用程序代码使用 UTF-8。

日本用戶以真實姓名註冊。資料庫以損壞的位元組儲存 '田中太郎'。

结果：用户资料显示被截断的文本。更糟的是：对所有 CJK 名称的搜索和排序都会失败，影响数千名用户。

将所有源文件设置为 UTF-8（配置编辑器和 .editorconfig）。在 HTML 中添加 <meta charset='UTF-8'>，在 API 响应中加入 'Content-Type: application/json; charset=utf-8'。

将数据库配置为 utf8mb4（不仅仅是 utf8，这是 MySQL 的 3 字节子集）。将连接的 Collation 设置为 utf8mb4_unicode_ci。

选择覆盖目标书写系统的字体：拉丁字母、西里尔字母、CJK、阿拉伯字母、天城文。使用系统字体栈或 Google Fonts 的语言子集以实现最佳加载。