Skip to main content

Rails i18n: complete internationalisatiehandleiding voor Ruby on Rails

Van je eerste localebestand tot productie: configureer Rails I18n, gebruik de hulpfunctie t(), verwerk CLDR-meervoudsvormen, los veelvoorkomende valkuilen op en voeg slimme terugvalketens toe.

1

De architectuur van Rails I18n begrijpen

Rails wordt geleverd met de I18n-gem. Vertaalbestanden staan als YAML- (standaard) of Ruby-bestanden in config/locales/. Het framework biedt de hulpfunctie t() (een alias voor I18n.translate) in views, controllers, modellen en mailers. Rails I18n is bewust eenvoudig en verwerkt standaard basisvertalingen, interpolatie en meervoudsvormen.

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 laadt alle .yml- en .rb-bestanden uit config/locales/ automatisch. Je kunt ze naar wens ordenen: per taal (en.yml, de.yml), per functie (en/users.yml, en/orders.yml) of beide (en/users.yml, de/users.yml). Rails voegt alle bestanden tijdens het opstarten samen.
2

Locale-instellingen configureren

Stel default_locale, available_locales en het terugvalgedrag in config/application.rb of een initializer in. Configureer localedetectie in ApplicationController en gebruik before_action om de locale in te stellen op basis van de URL, sessie, cookie of Accept-Language-header.

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"
I18n.locale instellen in een before_action is veilig per verzoek, maar I18n.default_locale tijdens runtime instellen is globaal en beïnvloedt alle threads. Gebruik voor localewijzigingen binnen een verzoek altijd I18n.locale (threadlokaal), nooit I18n.default_locale.
3

De hulpfunctie t() gebruiken

De hulpfunctie t() is overal in Rails beschikbaar: in views, controllers, modellen, mailers en taken. De functie accepteert een sleutel, optionele interpolatievariabelen en opties zoals standaardwaarden en bereik. In views ondersteunt Rails uitgestelde zoekacties die sleutels automatisch beperken tot de huidige controller en actie.

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

Meervoudsvormen verwerken

Rails I18n gebruikt de CLDR-meervoudscategorieën zero, one, two, few, many en other. Engels heeft alleen one en other nodig, maar andere talen vereisen meer vormen. Definieer meervoudsvertalingen als geneste YAML-sleutels onder de aantalcategorieën die je doeltalen nodig hebben.

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 genereert I18n::InvalidPluralizationData als een vereiste meervoudscategorie voor de actieve locale ontbreekt. Als je Russische locale alleen one en other definieert (overgenomen uit het Engels), veroorzaken aantallen zoals 2, 3 en 4 een crash omdat Russisch de categorie few vereist. Definieer altijd alle CLDR-categorieën voor elke taal.
5

Locale-fallbackketens toevoegen

De ingebouwde I18n.fallbacks van Rails biedt alleen eenvoudige terugval van een regionale naar de standaardlocale. Een gebruiker met pt-BR en een ontbrekende sleutel ziet Engels in plaats van pt-PT. rails-locale-chain voegt configureerbare ketens met diepe samenvoeging toe, zodat regionale gebruikers altijd de dichtstbijzijnde beschikbare vertaling zien.

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 bevat meer dan 75 ingebouwde terugvalketens voor 11 taalfamilies. Voeg de gem toe aan je Gemfile en configureer deze in een initializer, zodat regionale gebruikers onmiddellijk vertalingen uit de bovenliggende locale zien in plaats van Engelse hiaten.
6

Vertalingen automatiseren

Nu je Rails I18n-configuratie klaar is, kun je YAML-localebestanden met AI vertalen. i18n Agent ondersteunt YAML rechtstreeks: verwijs naar het bronlocalebestand en de tool genereert alle doeltalen met behoud van geneste sleutels, interpolatievariabelen en meervoudsvormen.

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
Vertaal stapsgewijs: vertaal bij nieuwe sleutels alleen het verschil. Zo blijven bestaande vertalingen behouden en worden ongewijzigde tekenreeksen niet opnieuw gegenereerd.

Veelvoorkomende valkuilen

InvalidPluralizationData-fouten

Rails crasht met I18n::InvalidPluralizationData wanneer een vereiste CLDR-meervoudscategorie ontbreekt. Dit gebeurt meestal als Engelse meervoudsvormen (one/other) worden gekopieerd naar talen die meer categorieën nodig hebben (Russisch vereist few, Arabisch zero/two/few/many). Installeer rails-i18n voor correcte CLDR-regels en definieer alle categorieën.

Uitgestelde zoekacties buiten views

Uitgestelde zoekacties (t('.key')) werken alleen in views waarin Rails de controller en actie kent. t('.key') gebruiken in een model, mailer of serviceobject retourneert een fout over een ontbrekende vertaling. Gebruik buiten views volledige sleutels (t('users.show.key')).

YAML-syntaxisfouten maken alle vertalingen onbruikbaar

Eén YAML-syntaxisfout (verkeerde inspringing, speciale tekens zonder aanhalingstekens of een tab in plaats van spaties) voorkomt dat het hele localebestand wordt geladen. Alle vertalingen in dat bestand retourneren dan fouten over ontbrekende sleutels. Valideer YAML-bestanden in CI met een linter en zet tekenreeksen met dubbele punten, haakjes of speciale begintekens tussen aanhalingstekens.

Probeer i18n Agent nu

Zet je vertaalbestand hier neer

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

of klik om een bestand te selecteren

Doeltalen

Geen registratie nodigDirecte prijsindicatie

Veelgestelde vragen over Rails i18n