Skip to main content

Rails i18n: guia completo de internacionalização de Ruby on Rails

Do primeiro arquivo de localidade à produção: configure Rails I18n, utilize o auxiliar t(), trate a pluralização CLDR, corrija problemas comuns e adicione cadeias inteligentes de fallback regional.

1

Compreender a arquitetura de Rails I18n

Rails inclui a gem I18n por padrão. Os arquivos de tradução ficam em config/locales/, no formato YAML (predefinido) ou em arquivos Ruby. O framework fornece o auxiliar t() (um alias de I18n.translate) em vistas, controladores, modelos e mailers. Rails I18n é intencionalmente simples: trata de tradução básica, interpolação e pluralização sem configuração adicional.

config/application.rb
# Rails includes i18n out of the box via the i18n gem
# config/application.rb
module MyApp
  class Application < Rails::Application
    # Default locale
    config.i18n.default_locale = :en

    # Available locales
    config.i18n.available_locales = [:en, :de, :ja, :es, :fr, :'pt-BR']

    # Fallback to default locale when translation is missing
    config.i18n.fallbacks = true

    # Load translations from nested directories
    config.i18n.load_path += Dir[Rails.root.join('config', 'locales', '**', '*.{rb,yml}')]
  end
end
config/routes.rb
# config/routes.rb
Rails.application.routes.draw do
  scope "/:locale", locale: /en|de|ja|es|fr|pt-BR/ do
    root "home#index"
    resources :products
  end

  root "home#index"
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
Rails carrega automaticamente todos os arquivos .yml e .rb de config/locales/. Pode organizá-los como quiser: por idioma (en.yml, de.yml), por funcionalidade (en/users.yml, en/orders.yml) ou de ambas as formas (en/users.yml, de/users.yml). Rails combina todos os arquivos durante o início.
2

Configurar as configurações regionais

Defina default_locale, available_locales e o comportamento de fallback em config/application.rb ou em um inicializador. Configure a detecção da localidade no seu ApplicationController utilizando before_action para a definir a partir da URL, da sessão, de um cookie ou do cabeçalho Accept-Language.

config/locales/en.yml
# config/locales/en.yml
en:
  nav:
    home: "Home"
    about: "About"
    settings: "Settings"
  greeting: "Hello, %{name}!"
  cart:
    item_count:
      one: "%{count} item"
      other: "%{count} items"

# config/locales/de.yml
de:
  nav:
    home: "Startseite"
    about: "Über uns"
    settings: "Einstellungen"
  greeting: "Hallo, %{name}!"
  cart:
    item_count:
      one: "%{count} Artikel"
      other: "%{count} Artikel"
Definir I18n.locale em um before_action é seguro para cada requisição, mas definir I18n.default_locale em tempo de execução é global e afeta todos os threads. Utilize sempre I18n.locale (local ao thread) para alterações de localidade limitadas à requisição, nunca I18n.default_locale.
3

Utilizar o auxiliar t()

O auxiliar t() está disponível em todo o Rails: vistas, controladores, modelos, mailers e tarefas. Aceita uma chave, variáveis de interpolação opcionais e opções como valores predefinidos e âmbito. Nas vistas, Rails aceita pesquisas diferidas que limitam automaticamente as chaves ao controlador e à ação atuais.

app/views/example.html.erb
# In views (ERB)
<h1><%= t('nav.home') %></h1>
<p><%= t('greeting', name: @user.name) %></p>

# In controllers
flash[:notice] = t('flash.product_created')

# In models
validates :name, presence: { message: I18n.t('errors.blank') }

# With HTML (safe)
<%= t('terms_html', link: link_to(t('terms_link'), '/terms')) %>
4

Tratar a pluralização

Rails I18n utiliza as categorias de plural CLDR: zero, one, two, few, many e other. O inglês só precisa de one e other, mas outros idiomas precisam de mais formas. Defina as traduções plurais como chaves YAML aninhadas nas categorias de contagem exigidas pelos idiomas de destino.

Plural forms
# In YAML:
en:
  cart:
    item_count:
      zero: "No items"
      one: "%{count} item"
      other: "%{count} items"

# Arabic (6 forms):
ar:
  cart:
    item_count:
      zero: "لا عناصر"
      one: "عنصر واحد"
      two: "عنصران"
      few: "%{count} عناصر"
      many: "%{count} عنصرًا"
      other: "%{count} عنصر"

# Usage in views:
<%= t('cart.item_count', count: @cart.items.size) %>
Rails gera I18n::InvalidPluralizationData se faltar uma categoria de plural obrigatória na localidade ativa. Se a localidade russa definir apenas one e other (copiadas do inglês), contagens como 2, 3 e 4 provocam uma falha porque o russo exige a categoria few. Defina sempre todas as categorias CLDR de cada idioma.
5

Adicionar cadeias de fallback regional

I18n.fallbacks integrado de Rails fornece apenas um fallback básico da localidade regional para a localidade padrão. Um usuário pt-BR com uma chave em falta vê inglês em vez de pt-PT. rails-locale-chain adiciona cadeias configuráveis com combinação profunda para que os usuários regionais vejam sempre a tradução disponível mais próxima.

Lazy lookups
# Lazy lookups use the controller/action as scope
# app/views/products/index.html.erb
# Instead of t('products.index.title'), just use:
<h1><%= t('.title') %></h1>
<p><%= t('.description') %></p>

# Rails looks up: products.index.title and products.index.description

# config/locales/en.yml
en:
  products:
    index:
      title: "All Products"
      description: "Browse our catalog"
rails-locale-chain inclui mais de 75 cadeias de fallback integradas que abrangem 11 famílias linguísticas. Adicione-o ao seu Gemfile, configure-o em um inicializador e os usuários regionais verão imediatamente traduções da localidade principal em vez de lacunas em inglês.
6

Automatizar as traduções

Com a configuração de Rails I18n concluída, traduza seus arquivos YAML de localidade com IA. O i18n Agent é compatível nativamente com YAML: indique a ele o arquivo de localidade de origem e este gera todos os idiomas de destino, preservando chaves aninhadas, variáveis de interpolação e formas plurais.

config/initializers/locale_chain.rb
# Gemfile
gem 'rails-locale-chain'

# config/initializers/locale_chain.rb
Rails.application.config.i18n.fallbacks = {
  'pt-BR': ['pt', 'en'],
  'zh-Hant-TW': ['zh-Hant', 'zh', 'en'],
  'es-419': ['es', 'en'],
}

# The gem deep-merges translations across the chain
# pt-BR -> pt -> en
# Missing keys in pt-BR are filled from pt, then en
Traduza de forma incremental: quando adicionar novas chaves, traduza apenas as diferenças. Assim, preserva as traduções existentes e evita regenerar strings inalteradas.

Erros frequentes

Erros InvalidPluralizationData

Rails falha com I18n::InvalidPluralizationData quando falta uma categoria de plural CLDR obrigatória. Acontece sobretudo quando formas de plural inglesas (one/other) são copiadas para idiomas que precisam de mais categorias (o russo precisa de few e o árabe de zero/two/few/many). Instale rails-i18n para obter regras CLDR corretas e defina todas as categorias.

Pesquisas diferidas fora das vistas

As pesquisas diferidas (t('.key')) só funcionam em vistas nas quais Rails conhece o controlador e a ação. Utilizar t('.key') em um modelo, mailer ou objeto de serviço devolve um erro de tradução em falta. Utilize chaves completas (t('users.show.key')) fora das vistas.

Os erros de sintaxe YAML impedem todas as traduções

Um único erro de sintaxe YAML (indentação incorreta, caracteres especiais sem aspas ou tabulação em vez de espaços) impede o carregamento de todo o arquivo de localidade. Todas as traduções desse arquivo devolvem erros de chave em falta. Valide os arquivos YAML em CI com um linter e coloque entre aspas as strings que contêm dois-pontos, colchetes ou caracteres especiais iniciais.

Experimente já o i18n Agent

Solte aqui seu arquivo de tradução

JSON, YAML, PO, XML, CSV, Markdown, Properties

ou clique para selecionar

Idiomas de destino

Sem cadastroEstimativa imediata

Perguntas frequentes sobre Rails i18n