Leitfaden zur Internationalisierung (i18n) und Lokalisierung von Rails

Rails Internationalisierung (i18n) konfigurieren

Die Rails-Internationalisierung erfordert drei Konfigurationsschritte: das Festlegen verfügbarer Locales, das Hinzufügen des Locales zu Ihren URLs und das Sicherstellen, dass Rails für jede Anfrage das richtige Locale lädt. Sie sollten auch das rails-i18n Gem installieren, das Locale-Daten wie übersetzte Monatsnamen, Pluralisierungsregeln und Standard-Rails-Fehlermeldungen bereitstellt.

Verfügbare Locales festlegen

Zuerst teilen Sie Rails in config/application.rb mit, welche Sprachen die App unterstützen soll, und legen ein Standard-Locale fest:

config.i18n.default_locale = :en
config.i18n.available_locales = [:en, :es, :de]

config.i18n.default_locale = :en
config.i18n.available_locales = [:en, :es, :de]

Dies teilt Rails mit, dass Englisch die Standardsprache ist und dass die App Englisch, Spanisch und Deutsch unterstützt. Sie können beliebige Sprachcodes hinzufügen, die Sie benötigen.

Locale zu URLs hinzufügen

Als Nächstes fügen Sie das Locale zur URL hinzu, sodass jede Sprache ihren eigenen Pfad hat, wie /en/time oder /es/time:

# config/routes.rb
scope "/:locale" do
  get '/time', to: 'home#index', as: :time_display
end

# config/routes.rb
scope "/:locale" do
  get '/time', to: 'home#index', as: :time_display
end

Locale-Wechsel konfigurieren

Stellen Sie schließlich in app/controllers/application_controller.rb sicher, dass Rails das richtige Locale aus der URL lädt und es in alle Links einbezieht:

class ApplicationController < ActionController::Base
  around_action :switch_locale

  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

  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

Dies liest die Locale aus dem URL-Parameter aus, greift auf die Standard-Locale zurück, falls keine vorhanden ist, und stellt sicher, dass alle generierten URLs die aktuelle Locale enthalten.

Das rails-i18n Gem installieren

Das rails-i18n Gem stellt Locale-Daten für mehrere Sprachen bereit, einschließlich übersetzter Monatsnamen, Pluralisierungsregeln und Standard-Rails-Fehlermeldungen. Dies erspart Ihnen die manuelle Übersetzung dieser Standardzeichenketten.

Fügen Sie es zu Ihrer Gemfile hinzu:

gem 'rails-i18n'

Dann ausführen:

bundle install

Rails ist nun vollständig für die Internationalisierung konfiguriert.

Einen Sprachumschalter hinzufügen

Da Ihre Rails-App nun mehrere Locales unterstützt, benötigen Ihre Nutzer eine Möglichkeit, zwischen den Sprachen zu wechseln. Da die default_url_options-Methode in ApplicationController automatisch die aktuelle Locale in alle generierten URLs einfügt, können Sie einen Sprachumschalter erstellen, der nur den Locale-Parameter aktualisiert, während der Nutzer auf derselben Seite bleibt.

Die Benutzeroberfläche des Sprachumschalters erstellen

Fügen Sie den Sprachumschalter zu Ihrer Layout-Datei hinzu. In unserer Demo-App geschieht dies in app/views/layouts/application.html.erb:

<nav>
  <%= link_to "English", url_for(locale: :en) %> |
  <%= link_to "Español", url_for(locale: :es) %> |
  <%= link_to "Deutsch", url_for(locale: :de) %>
</nav>

<nav>
  <%= link_to "English", url_for(locale: :en) %> |
  <%= link_to "Español", url_for(locale: :es) %> |
  <%= link_to "Deutsch", url_for(locale: :de) %>
</nav>

Jeder Link verwendet url_for(locale: :locale_code), um eine URL mit der angegebenen Locale zu generieren. Wenn ein Nutzer auf einen Link klickt, erkennt die switch_locale-Methode in ApplicationController die Änderung und Rails rendert die Seite in der neuen Sprache.

Da default_url_options definiert ist, bleibt die Locale beim Navigieren erhalten. Sie müssen nicht manuell Locale-Parameter zu jedem Link hinzufügen.

Ihren Sprachumschalter gestalten

Sie können den Sprachumschalter in app/assets/stylesheets/application.css an Ihr Design anpassen. Die Demo-App enthält eine grundlegende Gestaltung, um den Umschalter sichtbar und benutzerfreundlich zu machen.

Übersetzungsschlüssel in Rails Views einrichten

Bevor Sie Ihre App übersetzen können, muss der gesamte benutzerorientierte Text in Rails i18n-Dateien statt fest codiert sein. Rails bietet die t-Hilfsmethode (kurz für translate), um übersetzte Zeichenketten nachzuschlagen und anzuzeigen.

Fest codierten Text durch Übersetzungsschlüssel ersetzen

Fest codierter Text wird nicht in Ihrer YAML-Datei angezeigt, was bedeutet, dass er später nicht übersetzt werden kann. Verwenden Sie immer Übersetzungsschlüssel für jeden benutzerorientierten Text.

<h1><%= t(:hello) %></h1>
<p><%= t(:current_time, time: @time) %></p>
<button id="click-me"><%= t(:refresh) %></button>

<h1><%= t(:hello) %></h1>
<p><%= t(:current_time, time: @time) %></p>
<button id="click-me"><%= t(:refresh) %></button>

<h1>Hello</h1>
<p>Current time: <%= @time %></p>
<button>Refresh</button>

<h1>Hello</h1>
<p>Current time: <%= @time %></p>
<button>Refresh</button>

Interpolation in Übersetzungen verwenden

Beachten Sie den time: @time-Parameter im obigen Beispiel? Dies wird Interpolation genannt – sie ermöglicht es Ihnen, dynamische Werte in Ihre Übersetzungen einzufügen. Die Übersetzungszeichenkette in Ihrer YAML-Datei verwendet %{time} als Placeholder:

current_time: "Current time: %{time}"

current_time: "Current time: %{time}"

Wenn Sie den t-Helfer mit time: @time aufrufen, ersetzt Rails %{time} durch den tatsächlichen Wert. Sie können beliebige Variablennamen verwenden – stellen Sie einfach sicher, dass sie zwischen der YAML-Datei und Ihrer View übereinstimmen.

Lazy Lookup für saubereren Code

Wenn Ihre Übersetzungsschlüssel so organisiert sind, dass sie Ihrer View-Ordnerstruktur entsprechen, können Sie in Rails eine Abkürzung namens Lazy Lookup verwenden. Anstatt den vollständigen Schlüsselpfad zu schreiben, verwenden Sie einen führenden Punkt:

<!-- Instead of this: -->
<%= t('home.index.hello') %>

<!-- You can write this: -->
<%= t('.hello') %>

<!-- Instead of this: -->
<%= t('home.index.hello') %>

<!-- You can write this: -->
<%= t('.hello') %>

Rails prüft, in welcher View-Datei Sie sich befinden (home/index.html.erb), und fügt automatisch home.index vor Ihrem Schlüssel ein. Dies hält Ihren Code sauberer und erleichtert das Verschieben von Views. Wenn Sie eine View umbenennen oder verschieben, werden die Lazy Lookup-Pfade automatisch aktualisiert.

Übersetzungsdateien erstellen und organisieren

Nachdem Sie Übersetzungsschlüssel zu Ihren Views hinzugefügt haben, müssen Sie diese Schlüssel in einer YAML-Datei definieren. Rails speichert diese im Verzeichnis config/locales/.

Schlüssel zur Quelldatei hinzufügen

Öffnen Sie config/locales/en.yml und fügen Sie die Schlüssel hinzu, auf die Sie in Ihren Views verwiesen haben:

# config/locales/en.yml
en:
  hello: "Hello"
  current_time: "Current time: %{time}"
  refresh: "Refresh"

# config/locales/en.yml
en:
  hello: "Hello"
  current_time: "Current time: %{time}"
  refresh: "Refresh"

Dies ist Ihre Quelldatei – sie enthält den gesamten Text in Ihrer Standardsprache. Die Schlüssel auf der linken Seite sind das, worauf Ihre Views verweisen; die Zeichenketten auf der rechten Seite sind das, was angezeigt wird.

Schlüssel mit Verschachtelung organisieren

Um Lazy Lookup (die .hello-Abkürzung aus dem vorherigen Abschnitt) zu verwenden, organisieren Sie Ihre Schlüssel so, dass sie Ihrer View-Ordnerstruktur entsprechen:

en:
  home:
    index:
      hello: "Hello"
      current_time: "Current time: %{time}"
      refresh: "Refresh"

en:
  home:
    index:
      hello: "Hello"
      current_time: "Current time: %{time}"
      refresh: "Refresh"

Dies gruppiert alle Übersetzungen für app/views/home/index.html.erb unter home.index. Jetzt können Sie t('.hello') in dieser View anstelle von t('home.index.hello') verwenden.

Wenn Ihre Rails-Anwendung wächst, können Sie auch Namespaces für gemeinsame Übersetzungen (wie shared.navigation für Menüs) erstellen, um die Organisation zu erleichtern, dies ist jedoch optional.

JavaScript-Zeichenketten zu YAML hinzufügen

Rails extrahiert Text nicht automatisch aus JavaScript-Dateien. Wenn Ihre App clientseitigen Text wie Warnmeldungen, Tooltips oder Bestätigungsnachrichten enthält, fügen Sie diese Ihrer englischen Übersetzungsdatei hinzu:

# config/locales/en.yml
en:
  confirm: "Are you sure?"

# config/locales/en.yml
en:
  confirm: "Are you sure?"

An diesem Punkt enthält Ihre en.yml-Datei den gesamten Text, der in Ihrer App erscheint – sowohl in Rails-Views als auch in JavaScript.

Wenn Sie PTC verwenden, um Ihre Anwendung zu übersetzen (im nächsten Abschnitt behandelt), werden diese JavaScript-Zeichenketten zusammen mit allem anderen übersetzt.