Skip to main content

Rails i18n: täydellinen Ruby on Rails:in kansainvälistämisopas

Ensimmäisestä kieliversiotiedostosta tuotantoon: määritä Rails I18n, käytä t()-apufunktiota, käsittele CLDR-monikkosäännöt, korjaa tavalliset sudenkuopat ja lisää älykkäät varakieliketjut.

1

Ymmärrä Rails I18n -arkkitehtuuri

Rails sisältää I18n-gemin. Käännöstiedostot sijaitsevat config/locales/-hakemistossa YAML-tiedostoina (oletus) tai Ruby-tiedostoina. Ohjelmistokehys tarjoaa t()-apufunktion (I18n.translaten alias) näkymissä, kontrollereissa, malleissa ja postittajissa. Rails I18n on tarkoituksella yksinkertainen — se käsittelee heti peruskäännökset, interpoloinnin ja monikkomuodot.

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 lataa kaikki config/locales/-hakemiston .yml- ja .rb-tiedostot automaattisesti. Voit järjestää ne haluamallasi tavalla — kielen mukaan (en.yml, de.yml), ominaisuuden mukaan (en/users.yml, en/orders.yml) tai molemmilla (en/users.yml, de/users.yml). Rails yhdistää kaikki tiedostot käynnistyksen yhteydessä.
2

Määritä kieliversioasetukset

Aseta default_locale, available_locales ja varakielitoiminta config/application.rb-tiedostossa tai alustajassa. Määritä kieliversion tunnistus ApplicationControllerissa before_actionilla, joka asettaa kieliversion URL-osoitteesta, istunnosta, evästeestä tai Accept-Language-otsakkeesta.

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.localen asettaminen before_actionissa on pyyntökohtaisesti turvallista, mutta I18n.default_localen asettaminen suorituksen aikana on yleinen muutos ja vaikuttaa kaikkiin säikeisiin. Käytä pyyntökohtaisiin kieliversiomuutoksiin aina I18n.localea (säiekohtainen), älä koskaan I18n.default_localea.
3

Käytä t()-apufunktiota

t()-apufunktio on käytettävissä kaikkialla Rails:issa — näkymissä, kontrollereissa, malleissa, postittajissa ja töissä. Se vastaanottaa avaimen, valinnaiset interpolointimuuttujat sekä oletusarvojen ja käyttöalueen kaltaiset asetukset. Rails tukee näkymissä laiskoja hakuja, jotka rajaavat avaimet automaattisesti nykyiseen kontrolleriin ja toimintoon.

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

Käsittele monikkomuodot

Rails I18n käyttää CLDR-monikkoluokkia: zero, one, two, few, many, other. Englanti tarvitsee vain one- ja other-luokat, mutta muut kielet tarvitsevat useampia muotoja. Määritä monikkokäännökset sisäkkäisinä YAML-avaimina kohdekielten tarvitsemien määräluokkien alle.

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 aiheuttaa I18n::InvalidPluralizationData-virheen, jos aktiivisesta kieliversiosta puuttuu vaadittu monikkoluokka. Jos venäjän kieliversiosi määrittää vain englannista kopioidut one- ja other-luokat, määrät 2, 3 ja 4 kaatuvat, koska venäjä tarvitsee few-luokan. Määritä aina kaikki kielikohtaiset CLDR-luokat.
5

Lisää varakieliketjut

Rails:in sisäänrakennettu I18n.fallbacks tarjoaa vain perustason siirtymisen alueellisesta oletuskieliversioon. Puuttuvan avaimen kohtaava pt-BR-käyttäjä näkee pt-PT:n sijaan englannin. rails-locale-chain lisää määritettävät syväyhdistetyt ketjut, jotta alueelliset käyttäjät näkevät aina lähimmän saatavilla olevan käännöksen.

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 sisältää yli 75 varakieliketjua 11 kieliperheelle. Lisää se Gemfileen ja määritä alustajassa, niin alueelliset käyttäjät näkevät heti englanninkielisten aukkojen sijaan pääkieliversion käännökset.
6

Automatisoi käännökset

Kun Rails I18n on otettu käyttöön, käännä YAML-kieliversiotiedostosi tekoälyllä. i18n Agent tukee YAML:ia suoraan — osoita se lähdekielen tiedostoon, niin se luo kaikki kohdekielet säilyttäen sisäkkäiset avaimet, interpolointimuuttujat ja monikkomuodot.

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
Käännä vaiheittain — kun lisäät uusia avaimia, käännä vain diff. Näin nykyiset käännökset säilyvät eikä muuttumattomia merkkijonoja tarvitse luoda uudelleen.

Tavalliset sudenkuopat

InvalidPluralizationData-virheet

Rails kaatuu I18n::InvalidPluralizationData-virheeseen, kun vaadittu CLDR-monikkoluokka puuttuu. Näin käy useimmiten, kun englannin monikkomuodot (one/other) kopioidaan useampia luokkia tarvitseviin kieliin (venäjä tarvitsee few-luokan, arabia zero/two/few/many-luokat). Asenna rails-i18n oikeita CLDR-sääntöjä varten ja määritä kaikki luokat.

Laiskat haut näkymien ulkopuolella

Laiskat haut (t('.key')) toimivat vain näkymissä, joissa Rails tuntee kontrollerin ja toiminnon. t('.key') palauttaa mallissa, postittajassa tai palveluobjektissa puuttuvan käännöksen virheen. Käytä näkymien ulkopuolella täydellisiä avaimia (t('users.show.key')).

YAML-syntaksivirheet rikkovat kaikki käännökset

Yksi YAML-syntaksivirhe (virheellinen sisennys, lainausmerkitön erikoismerkki, sarkain välilyöntien sijaan) estää koko kieliversiotiedoston lataamisen. Kaikki tiedoston käännökset palauttavat puuttuvan avaimen virheen. Validoi YAML-tiedostot CI:ssä tarkistimella ja ympäröi kaksoispisteitä, sulkeita tai alun erikoismerkkejä sisältävät merkkijonot lainausmerkeillä.

Kokeile i18n Agent:ia nyt

Pudota käännöstiedostosi tähän

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

tai valitse napsauttamalla

Kohdekielet

Rekisteröitymistä ei tarvitaVälitön arvio

Usein kysyttyä Rails i18n:stä