i18n-patterns

Rails 8 的 I18n 模式

概述

Rails I18n 提供国际化支持：

• 翻译查找
• 区域设置管理
• 日期／时间／货币格式化
• 复数规则
• 视图中的惰性查找

快速开始

# config/application.rb
config.i18n.default_locale = :en
config.i18n.available_locales = [:en, :fr, :de]
config.i18n.fallbacks = true

项目结构

config/locales/
├── en.yml                    # English defaults
├── fr.yml                    # French defaults
├── models/
│   ├── en.yml               # Model translations (EN)
│   └── fr.yml               # Model translations (FR)
├── views/
│   ├── en.yml               # View translations (EN)
│   └── fr.yml               # View translations (FR)
├── mailers/
│   ├── en.yml               # Mailer translations (EN)
│   └── fr.yml               # Mailer translations (FR)
└── components/
    ├── en.yml               # Component translations (EN)
    └── fr.yml               # Component translations (FR)

区域设置文件组织

按领域组织区域设置文件：models/、views/、mailers/、components/。

• 模型： activerecord.models、activerecord.attributes、activerecord.errors
• 视图： 按控制器名称和操作嵌套（例如 events.index.title）
• 共享： common.actions、common.messages、common.date.formats
• 组件： components.<component_name>.<key>

参见 locale-files.md，了解模型、视图、共享键和组件的完整 YAML 示例。

使用模式

核心原则

• 在视图中使用惰性查找：t(".title") 会解析为 "events.index.title"
• 对包含 HTML 标记的字符串使用 _html 后缀
• 对日期、时间和数字使用 I18n.l（本地化），而不是 I18n.t
• 在模型、服务和展示器中使用带完整键路径的 I18n.t
• 通过插值传递动态值：t(".greeting", name: user.name)

在视图中

<h1><%= t(".title") %></h1>
<%= link_to t(".new_event"), new_event_path %>
<p><%= t(".welcome", name: current_user.name) %></p>
<p><%= t(".intro_html", link: link_to("here", help_path)) %></p>

在控制器中

redirect_to @event, notice: t(".success")

在模型／展示器中

I18n.t("activerecord.attributes.event/statuses.#{status}")
I18n.l(event_date, format: :long)

参见 usage-patterns.md，了解包含展示器、组件、日期／货币格式化和复数处理的完整示例。

区域设置切换

基于 URL 的区域设置

# config/routes.rb
Rails.application.routes.draw do
  scope "(:locale)", locale: /en|fr|de/ do
    resources :events
  end
end

# app/controllers/application_controller.rb
class ApplicationController < ActionController::Base
  around_action :switch_locale

  private

  def switch_locale(&action)
    locale = params[:locale] || I18n.default_locale
    I18n.with_locale(locale, &action)
  end

  def default_url_options
    { locale: I18n.locale }
  end
end

用户偏好区域设置

class ApplicationController < ActionController::Base
  around_action :switch_locale

  private

  def switch_locale(&action)
    locale = current_user&.locale || extract_locale_from_header || I18n.default_locale
    I18n.with_locale(locale, &action)
  end

  def extract_locale_from_header
    request.env['HTTP_ACCEPT_LANGUAGE']&.scan(/^[a-z]{2}/)&.first
  end
end

测试 I18n

• 在 spec/rails_helper.rb 中配置缺失翻译时抛出异常
• 使用 i18n-tasks gem 检测缺失和未使用的键
• 编写视图翻译规格，断言渲染的内容

参见 testing.md，了解完整的规格示例和 i18n-tasks 配置。

最佳实践

应该做

# Use nested structure matching view paths
en:
  events:
    index:
      title: Events
    show:
      title: Event Details

# Use interpolation for dynamic content
en:
  greeting: "Hello, %{name}!"

# Use _html suffix for HTML content
en:
  intro_html: "Welcome to <strong>our app</strong>"

不应该做

# Don't use flat keys
en:
  events_index_title: Events  # BAD

# Don't hardcode in views
<h1>Events</h1>  # BAD - use t(".title")

# Don't concatenate translations
t("hello") + " " + t("world")  # BAD

检查清单

• 区域设置文件按领域组织（模型、视图等）
• 所有面向用户的文本都使用 I18n
• 在视图中使用惰性查找（t(".key")）
• 对可计数项目使用复数形式
• 本地化日期／货币格式
• 实现区域设置切换
• 配置 i18n-tasks
• 在测试中检测缺失翻译
• 配置回退

参考资料

• locale-files.md — 模型、视图、共享键和组件的 YAML 区域设置文件示例
• usage-patterns.md — 视图、控制器、模型、展示器、组件中的用法示例及格式化示例
• testing.md — 用于翻译覆盖率的 RSpec 规格和 i18n-tasks