文档

伪本地化

通过伪翻译功能预览页面,可提前发现未被收录的文本、被截断的标签以及布局错乱等问题,无需等待正式翻译即可排查多语言适配隐患。

伪翻译会将所有字符串替换为可识别的虚假内容。在左到右语言中,每个字母都会加上重音符号,且字符串会包含在括号内:保存更改会变为⟦Šáṽé çĥáñĝéš··········⟧。在右到左语言中,每个字符串会通过方向覆盖符反转,因此即便在阿拉伯语或希伯来语版本出现前,页面也会从右向左阅读。

以此方式渲染的页面上会显现出三个问题:

  • 纯文本并非来自目录:它是直接写入代码或在运行时生成的。
  • 文本被截断没有为长度更长的语言预留空间。
  • 布局固定不变在右到左页面中,会使用左右而非起始和结束来定位元素。
德语 · 伪本地化渲染/de-DE/
您的购物篮⟦您的购物篮·····⟧

所有订单均免运费

保存更改⟦保存更改····⟧

价格已含税费。⟦价格已含税费。·······⟧

阿拉伯语 · 伪本地化渲染/ar-SA/
您的购物篮‮您的购物篮‬

所有订单均免运费

保存更改‮保存更改‬

价格已含税费。‮价格已含税费。‬

探测结果
  1. 未来自目录的文本/{locale}/ · p#promo · “所有订单均免运费” · runtime_text (de-DE, ar-SA)
  2. 文本超出长度后被截断/{locale}/ · button#save · “⟦保存更改····⟧” · clipped_text (de-DE)
  3. 布局无法正确实现从右到左镜像/{locale}/ · p#note · “padding-left: 12px” · unmirrored_layout (ar-SA)

伪本地化页面的展示效果:同一页面在德语中字符串加注且变长,阿拉伯语则从右向左排列。探针标记写入代码的文本、截断文字的按钮及左侧保留的规则。仅为示意数据。

在全球化检查中

当配置文件指定了应用的启动方式时,全球化检查会在每次变更时渲染其页面并进行检查。它会在检查专属的沙盒中运行变更的副本,因此伪翻译绝不会进入你的代码库或其他检查流程:

  1. 它会将伪翻译分别写入项目的左到右语言和右到左语言版本中。
  2. 它会安装依赖项并启动应用。
  3. 它会在设置为对应语言版本的浏览器中打开两种语言下的所有页面,并读取屏幕上的显示内容。
  4. 它会停止应用并删除该副本。

它发现的内容会成为检查的成果:

代码发现的内容
runtime_text不含伪标记的可见文本
clipped_text被容器截断的伪文本,带有overflow被隐藏或显示为省略号
unmirrored_layout在右到左页面中:非右到左的页面、左/右对齐或浮动的元素,以及通过左右属性设置位置、外边距或内边距的元素

两种语言下发现的相同文本会被记为一项成果。这些成果会显示在任务的发现的问题中,包含页面、元素、文本及对应语言信息,例如/{locale}/ · p#promo · “Free shipping on every order” · runtime_text (de-DE, ar-SA)。

它们会被记录,且在你主动选择前不会阻塞流程。在Quality Control → 全球化、渲染页面会关闭该步骤,而需返工修复的页面问题会指定哪些代码会导致阻塞。

无法安装或启动的应用会被标记为未渲染,并显示其输出内容,而非视为正常渲染结果。只有当你选择阻塞页面问题时,该变更才会被保留。

进行设置

添加world.render到.coroid/i18n.json:

{
  "world": {
    "render": {
      "start": "npm run dev",
      "pages": ["/{locale}/", "/{locale}/pricing", "/{locale}/checkout"]
    }
  }
}
字段含义
start用于启动应用。应用必须监听指定端口上的请求。$PORT;HOST为127.0.0.1
pages最多可配置十条从应用根目录开始的路径。{locale}会对应为语言标签,因此/{locale}/pricing会打开/de-DE/pricing;可使用/?lang={locale}若语言以查询参数的形式传递,则使用
directory当应用所在文件夹并非仓库根目录时,需填写该字段。
install用于安装依赖项的命令。若未指定该命令,当存在 Coroid 时,Coroid 会默认执行 npm 命令。package.json声明了相关配置时才会生效。
locales最多可指定三种用于渲染的目标语言。若未指定,则默认采用首个从左到右排列的语言和首个从右到左排列的语言。
readyTimeoutMs应用响应请求的最长时长,默认值为 120,000。

浏览器也会将每种语言作为首选语言发送,因此无需额外配置,即可让根据浏览器语言选择语言的应用正常运行。{locale}。

该字段在配置中需要 CLI 1.16.0 或更高版本cli才能绑定对应版本;旧版引擎无法识别该配置。

遗漏的内容

该检查仅读取用户可见的内容,会跳过隐藏元素、代码code、pre、kbd、samp以及表单字段自身的取值和标记为translate="no"、aria-hidden="true"、data-i18n-ignore或带有对应类名的元素notranslate。配置中的world.allow列表里的产品名称等内容绝不会被当作纯文本上报。

来自自有数据的文本,比如产品名称或用户生成内容,也不会被目录功能翻译。只需标记其容器translate="no"或data-i18n-ignore,这样浏览器翻译工具也会忽略该内容。

亲自试试吧

伪翻译功能是命令行工具的一部分。请在临时分支中运行它,因为它会替换语言的翻译内容:

coroid-i18n pseudo --locale de-DE                # accented and longer
coroid-i18n pseudo --locale ar-SA                # reversed, right to left
coroid-i18n pseudo --locale de-DE --style rtl    # choose the style yourself

随后启动应用,并以对应语言打开其页面。占位符、复数形式和标记都会保持原样,因此应用可正常运行。Markdown 和 MDX 页面也会维持原状。