本地化 Rails 应用

翻译以语言区域为根节点的 Rails YAML,并验证消息查找、插值、复数形式和请求中的语言区域选择。

Rails 已通过 t 和 I18n.t 为消息提供了稳定的名称。Lingo.dev 可以翻译这些名称对应的 YAML,消息查找、插值和语言区域选择则仍由 Rails 处理。先从问候语和通知数量入手,再用应用实际使用的同一套辅助方法进行检查。

将源消息写入 Rails 语言区域文件 #

创建或扩展 config/locales/en.yml:

yaml
en:
  home:
    index:
      welcome: "Welcome, %{name}!"
      cta: "Create an account"
  notifications:
    unread:
      one: "One unread notification"
      other: "%{count} unread notifications"

在 app/views/home/index.html.erb 中,问候语可以使用相对于当前视图的查找方式:

erb
<h1><%= t(".welcome", name: @user_name) %></h1>
<p><%= t("notifications.unread", count: @unread_count) %></p>

视图路径使 .welcome 对应到完整键名 home.index.welcome。调用方提供 name 和 count,译文必须保留这些插值名称。one 和 other 等复数键用于标识分支,必须保持不变。

随着本地化覆盖范围扩大,将其余硬编码的视图标签、邮件文案和模型错误消息移入相应的语言区域命名空间。翻译一个文件,只会影响加载该文件消息的调用方。

选择以语言区域为根节点的 YAML #

Rails 从 YAML 根节点读取语言区域。如果将 en.yml 重命名为 es.yml,却保留 en:,定义的仍然是英文消息。使用 yaml-root-key 处理器,在翻译值的同时重命名根节点。

在项目根目录安装并关联 CLI:

sh
npm install --global @lingo.dev/cli
lingo login
lingo init --source en --targets es,fr --files 'config/locales/en.yml' --yes
lingo link

保留写入 .lingo/config.json 的组织 ID 和本地化引擎 ID。将其中的 files 数组设为项目使用的源文件条目:

json
[
  { "pattern": "config/locales/en.yml", "format": "yaml-root-key" },
  { "pattern": "config/locales/*.en.yml", "format": "yaml-root-key" }
]

第二个条目涵盖 mailers.en.yml 等按功能划分的文件,但不会选中同目录下对应的译文文件。如果项目没有此类文件,请移除该条目。请明确指定格式:通用 YAML 会保留所有根节点,而 CLI 的文件发现机制要求为 YAML 源文件明确选择格式。以语言区域为根节点的 YAML说明了单根节点映射要求和重建行为。

翻译并检查加载后的值 #

如果目标文件尚不存在,运行:

sh
lingo push --backfill-missing --wait

运行完成后,打开 config/locales/es.yml,确认根节点为 es:。检查嵌套键和插值名称是否与源文件一致,并检查序列化后的注释、锚点和别名。如果源文件的组织方式不同,可能需要使用显式目标路径。

在 Rails 控制台或应用测试中加载结果,并显式选择语言区域:

ruby
I18n.with_locale(:es) do
  puts I18n.t("home.index.welcome", name: "Alex", raise: true)
  [0, 1, 2, 20].each do |count|
    puts I18n.t("notifications.unread", count: count, raise: true)
  end
end

检查前,先将 :en、:es 和 :fr 配置为可用的语言区域。此示例用于测试查找和插值;请核对措辞是否准确表达了预期的问候语和通知数量。目标语言所需的复数规则和分支可能超出源语言英语的形式。对法语执行同样的检查,并在添加应用的邮件和验证命名空间后,对这些命名空间也进行检查。

让请求选择相同的语言区域 #

在 Rails 配置中声明支持的语言区域和默认值。从支持的语言区域中选取一个值,并在 I18n.with_locale 中执行请求处理,避免语言区域状态沿用到其他请求。

对于 /es 这类 URL,既要配置路由作用域,也要配置读取 params[:locale] 的控制器。生成链接时,请保留语言区域。如果应用还通过 Accept-Language 协商语言,请解析质量权重和区域标签,而不是简单截取两个字母。如果应用支持用户显式选择语言区域,应优先采用用户的选择。

请审慎选择回退行为。回退能让页面保持可用,却也可能掩盖西班牙语消息缺失的问题,因此请在不依赖回退的情况下检查必需的目标条目。在适当情况下,使用 Rails 的 l 辅助方法对日期和时间进行本地化,而不是将已格式化的日期作为文本翻译。

分别直接打开目标语言页面和通过导航进入该页面。确认 Rails 选择了目标命名空间、显示了预期的插值结果,并能妥善处理更长的文本。lingo check 不用于检查 Rails YAML 的完整性;验收流程仍应包含 Rails 加载、渲染和语言审核。

随源文件变更持续维护译文 #

将源文件、已接受的目标译文、配置和 .lingo/lock.json 一起保存。修改消息后,运行 lingo push --wait 处理常规增量变更,并将修改后的消息与相邻的未修改消息进行比较。如果源措辞未变,只需精确修正译文,请直接编辑目标文件:YAML 键作用域可能会复用现有译文。如果指导规则变更后需要重新生成译文,请先保存已接受的目标译文,再在指定范围内替换整个文件,具体参见翻译作用域。

如果需要保护本地目标译文的修正,避免差异被覆盖,请在提交时不使用 --wait,检查 lingo pull --dry-run,并在发起提交的 checkout 中获取结果。等待回写的方式不会执行这一针对最新状态的冲突检查。其他 checkout 通过版本控制获取已提交的译文。参见保留已审核的译文。

本地流程运行正常后,选择 GitHub App 或 CI 自动化。合并译文差异前,对生成的资源执行同样的 Rails 检查。