Skip to main content

Rails i18n: Πλήρης οδηγός διεθνοποίησης του Ruby on Rails

Από το πρώτο αρχείο locale έως την παραγωγή: ρυθμίστε το Rails I18n, χρησιμοποιήστε τη βοηθητική συνάρτηση t(), χειριστείτε τον πληθυντικό CLDR, διορθώστε συνήθεις παγίδες και προσθέστε έξυπνες αλυσίδες εναλλακτικών locale.

1

Κατανοήστε την αρχιτεκτονική του Rails I18n

Το Rails περιλαμβάνει ενσωματωμένο το gem I18n. Τα αρχεία μετάφρασης βρίσκονται στο config/locales/ ως αρχεία YAML (προεπιλογή) ή Ruby. Το framework παρέχει τη βοηθητική συνάρτηση t() (ψευδώνυμο του I18n.translate) σε views, controllers, models και mailers. Το Rails I18n είναι σκόπιμα απλό — χειρίζεται εξαρχής τη βασική μετάφραση, την παρεμβολή και τον πληθυντικό αριθμό.

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 φορτώνει αυτόματα όλα τα αρχεία .yml και .rb από το config/locales/. Μπορείτε να τα οργανώσετε όπως θέλετε — ανά γλώσσα (en.yml, de.yml), ανά λειτουργία (en/users.yml, en/orders.yml) ή και με τους δύο τρόπους (en/users.yml, de/users.yml). Το Rails συγχωνεύει όλα τα αρχεία κατά την εκκίνηση.
2

Ρυθμίστε τις επιλογές locale

Ορίστε τα default_locale, available_locales και τη συμπεριφορά εναλλακτικής γλώσσας στο config/application.rb ή σε έναν initializer. Ρυθμίστε τον εντοπισμό locale στο ApplicationController χρησιμοποιώντας before_action, ώστε το locale να ορίζεται από το URL, τη συνεδρία, ένα cookie ή την κεφαλίδα 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"
Ο ορισμός του I18n.locale σε before_action είναι ασφαλής ανά αίτημα, αλλά ο ορισμός του I18n.default_locale κατά την εκτέλεση είναι καθολικός και επηρεάζει όλα τα νήματα. Χρησιμοποιείτε πάντα το I18n.locale (τοπικό στο νήμα) για αλλαγές locale που περιορίζονται σε ένα αίτημα και ποτέ το I18n.default_locale.
3

Χρησιμοποιήστε τη βοηθητική συνάρτηση t()

Η βοηθητική συνάρτηση t() είναι διαθέσιμη παντού στο Rails — σε views, controllers, models, mailers και jobs. Δέχεται ένα κλειδί, προαιρετικές μεταβλητές παρεμβολής και επιλογές όπως προεπιλεγμένες τιμές και scope. Στα views, το Rails υποστηρίζει σχετικές αναζητήσεις που περιορίζουν αυτόματα τα κλειδιά στον τρέχοντα controller και action.

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

Χειριστείτε τον πληθυντικό αριθμό

Το Rails I18n χρησιμοποιεί τις κατηγορίες πληθυντικού CLDR: zero, one, two, few, many, other. Τα Αγγλικά χρειάζονται μόνο one και other, αλλά άλλες γλώσσες απαιτούν περισσότερες μορφές. Ορίστε τις μεταφράσεις πληθυντικού ως ένθετα κλειδιά YAML κάτω από τις κατηγορίες count που απαιτούν οι γλώσσες προορισμού.

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 προκαλεί I18n::InvalidPluralizationData αν λείπει μια απαιτούμενη κατηγορία πληθυντικού για το ενεργό locale. Αν το ρωσικό locale ορίζει μόνο one και other (αντιγραμμένα από τα Αγγλικά), πλήθη όπως 2, 3 και 4 θα προκαλέσουν σφάλμα, επειδή τα Ρωσικά απαιτούν κατηγορία few. Να ορίζετε πάντα όλες τις κατηγορίες CLDR κάθε γλώσσας.
5

Προσθέστε αλυσίδες εναλλακτικών locale

Το ενσωματωμένο I18n.fallbacks του Rails παρέχει μόνο μια βασική μετάβαση από το περιφερειακό στο προεπιλεγμένο locale. Ένας χρήστης του pt-BR, όταν λείπει ένα κλειδί, βλέπει Αγγλικά αντί για pt-PT. Το rails-locale-chain προσθέτει ρυθμιζόμενες αλυσίδες συγχώνευσης σε βάθος, ώστε οι χρήστες περιφερειακών παραλλαγών να βλέπουν πάντα την πλησιέστερη διαθέσιμη μετάφραση.

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 περιλαμβάνει πάνω από 75 ενσωματωμένες αλυσίδες εναλλακτικών locale που καλύπτουν 11 γλωσσικές οικογένειες. Προσθέστε το στο Gemfile, ρυθμίστε το σε έναν initializer και οι χρήστες τοπικών παραλλαγών θα βλέπουν αμέσως μεταφράσεις του γονικού locale αντί για κενά που συμπληρώνονται στα Αγγλικά.
6

Αυτοματοποιήστε τις μεταφράσεις

Αφού ολοκληρώσετε τη ρύθμιση του Rails I18n, μεταφράστε τα αρχεία locale YAML με τη χρήση AI. Το i18n Agent υποστηρίζει εγγενώς το YAML — υποδείξτε του το αρχείο locale προέλευσης και θα δημιουργήσει τα αντίστοιχα αρχεία για όλες τις γλώσσες προορισμού, διατηρώντας τα ένθετα κλειδιά, τις μεταβλητές παρεμβολής και τις μορφές πληθυντικού.

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
Μεταφράζετε σταδιακά — όταν προσθέτετε νέα κλειδιά, μεταφράζετε μόνο τις διαφορές. Έτσι διατηρούνται οι υπάρχουσες μεταφράσεις και αποφεύγεται η εκ νέου δημιουργία αμετάβλητων συμβολοσειρών.

Συνήθεις παγίδες

Σφάλματα InvalidPluralizationData

Το Rails εμφανίζει I18n::InvalidPluralizationData όταν λείπει μια απαιτούμενη κατηγορία πληθυντικού CLDR. Αυτό συμβαίνει συνήθως όταν οι αγγλικές μορφές πληθυντικού (one/other) αντιγράφονται σε γλώσσες που χρειάζονται περισσότερες κατηγορίες (τα Ρωσικά χρειάζονται few και τα Αραβικά zero/two/few/many). Εγκαταστήστε το rails-i18n για σωστούς κανόνες CLDR και ορίστε όλες τις κατηγορίες.

Σχετικές αναζητήσεις εκτός των views

Οι σχετικές αναζητήσεις (t('.key')) λειτουργούν μόνο σε views, όπου το Rails γνωρίζει τον controller και το action. Η χρήση του t('.key') σε model, mailer ή αντικείμενο υπηρεσίας επιστρέφει σφάλμα ότι λείπει η μετάφραση. Χρησιμοποιήστε πλήρη κλειδιά (t('users.show.key')) εκτός των views.

Τα συντακτικά σφάλματα YAML διακόπτουν όλες τις μεταφράσεις

Ένα και μόνο συντακτικό σφάλμα YAML (λανθασμένη εσοχή, ειδικοί χαρακτήρες χωρίς εισαγωγικά, tab αντί για κενά) εμποδίζει τη φόρτωση ολόκληρου του αρχείου locale. Όλες οι μεταφράσεις του αρχείου επιστρέφουν σφάλματα για κλειδιά που λείπουν. Επικυρώνετε τα αρχεία YAML στο CI με linter και περικλείετε σε εισαγωγικά τις συμβολοσειρές που περιέχουν άνω και κάτω τελεία, αγκύλες ή ειδικούς χαρακτήρες στην αρχή.

Δοκιμάστε τώρα το i18n Agent

Αφήστε εδώ το αρχείο μετάφρασής σας

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

ή κάντε κλικ για να επιλέξετε αρχείο

Γλώσσες-στόχοι

Δεν απαιτείται εγγραφήΆμεση εκτίμηση

Συχνές ερωτήσεις για το Rails i18n