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]

Diese Konfiguration teilt Rails mit:

• Englisch (:en) ist die Standardsprache
• Die App unterstützt Englisch, Spanisch und Deutsch
• Benutzer können zwischen diesen drei Sprachen wechseln

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

Dies erstellt Locale-spezifische URLs für Ihre Rails-Anwendung. Benutzer können auf verschiedene Sprachversionen zugreifen, indem sie den Locale-Parameter in der URL ändern.

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

Dieser Code:

• Liest das Locale aus dem URL-Parameter
• Greift auf das Standard-Locale zurück, wenn kein Parameter vorhanden ist
• Stellt sicher, dass alle generierten URLs das 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

Nachdem Ihre Rails-App nun mehrere Locales unterstützt, benötigen Ihre globalen Benutzer eine Möglichkeit, zwischen den Sprachen zu wechseln. Rails macht dies einfach, da die default_url_options-Methode in ApplicationController das aktuelle Locale automatisch in alle generierten URLs einbezieht.

Das bedeutet, Sie können einen Sprachumschalter erstellen, der nur den Locale-Parameter aktualisiert, während der Benutzer auf derselben Seite bleibt.

Die Benutzeroberfläche des Sprachumschalters erstellen

Fügen Sie den Sprachumschalter zu Ihrer Layout-Datei hinzu. In unserer Demo-App wird der Umschalter in app/views/layouts/application.html.erb hinzugefügt:

<nav>
  <%= link_to "Englisch", url_for(locale: :en) %> |
  <%= link_to "Spanisch", 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 dem angegebenen Locale zu generieren. Wenn ein Benutzer auf einen Link klickt:

• Die switch_locale-Methode im ApplicationController erkennt die Änderung
• Rails rendert die Seite in der neuen Sprache

Da Sie default_url_options im ApplicationController definiert haben, fügt Rails das Locale automatisch in alle generierten Links ein. Das bedeutet, das Locale bleibt erhalten, während Benutzer durch Ihre App navigieren. 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

Rails verwendet den integrierten I18n.t (oder einfach t) Helfer, um Zeichenketten aus Ihren Übersetzungsdateien nachzuschlagen.

<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>

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.

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: „Aktuelle Uhrzeit: %{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:

<!-- Stattdessen: -->
<%= t('home.index.hello') %>

<!-- Sie können dies schreiben: -->
<%= 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 Definitionen im Verzeichnis config/locales/.

Schlüssel zu Ihrer englischen Datei hinzufügen

Rails-Übersetzungsdateien verwenden eine einfache Schlüssel-Wert-Struktur. Ö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: „Hallo“
 current_time: „Aktuelle Uhrzeit: %{time}“
 refresh: „Aktualisieren“

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

In dieser Rails i18n-Struktur:

• en ist der Sprachcode (Englisch)
• hello, current_time und refresh sind Übersetzungsschlüssel
• Die Zeichenketten auf der rechten Seite sind der eigentliche Text
• %{time} ist ein Placeholder für dynamische Inhalte (Interpolation)

Dies ist Ihre Quelldatei. Sie enthält den gesamten Text in Ihrer Standardsprache. Später in diesem Tutorial werden Sie PTC verwenden, um automatisch spanische, deutsche und andere Sprachversionen zu generieren.

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: „Hallo“
 current_time: „Aktuelle Uhrzeit: %{time}“
 refresh: „Aktualisieren“

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

Ihre Rails-Views sind jetzt internationalisiert, aber was ist mit JavaScript? Rails extrahiert Text nicht automatisch aus JavaScript-Dateien. Wenn Ihre Anwendung clientseitigen Text wie Warnungen, Tooltips oder Bestätigungsmeldungen enthält, müssen Sie diese zu Ihrer englischen Übersetzungsdatei hinzufügen.

Um beispielsweise ein Bestätigungs-Popup zu übersetzen, fügen Sie die Zeichenkette zu config/locales/en.yml hinzu:

# config/locales/en.yml
en:
 confirm: „Sind Sie sicher?“

# 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.