Localisierung (i18n) in Rails mit localeUI
Mehrsprachigkeit ist heute kein Spezialfeature mehr, sondern in vielen Projekten selbstverständlich. Egal ob SaaS-Produkt, interne Plattform oder öffentliches Webprojekt – sobald unterschiedliche Zielgruppen angesprochen werden, kommt das Thema Internationalisierung ins Spiel.
Das Gute: Ruby on Rails bringt mit seinem integrierten I18n-System bereits alles mit, was wir brauchen. Und wenn das Projekt wächst oder mehrere Personen an Übersetzungen arbeiten, hilft dir localeUI die Verwaltung deutlich vereinfachen.
In diesem Artikel bauen wir Schritt für Schritt eine neue Rails-App auf, richten Englisch und Deutsch ein (Englisch als Default), erstellen eine übersetzte „Hallo Welt“-Seite mit Sprachumschaltung per URL und binden anschließend localeUI an.
Wir starten mit der Erstellung einer neuen Rails App mit dem Konsolenbefehl:
rails new rails_localeui_demo cd rails_localeui_demo
Mit dem Befehl rails new erstellt Ruby on Rails automatisch eine vollständige Projektstruktur für eine neue Anwendung. Dabei werden unter anderem die typische MVC-Ordnerstruktur mit app/models, app/controllers und app/views angelegt. Zusätzlich erzeugt Rails wichtige Konfigurationsdateien im config-Ordner, richtet eine Datenbankkonfiguration ein und erstellt ein Gemfile, in dem die benötigten Abhängigkeiten des Projekts definiert sind. Außerdem wird eine Standard-Testumgebung vorbereitet, sodass Tests von Anfang an in das Projekt integriert sind.
Nach dem Start mit:
rails server
ist die Anwendung im Browser unter http://localhost:3000 erreichbar.
Rails bringt das I18n-System bereits mit. Standardmäßig ist allerdings nur Englisch aktiviert. Wir wollen zusätzlich Deutsch einbinden und Englisch als Standardsprache festlegen.
Dazu öffnen wir die Datei config/application.rb. Innerhalb der Applications-Klasse ergänzen wir folgende Konfiguration:
... module RailsLocaleuiDemo class Application < Rails::Application ... config.i18n.available_locales = [:en, :de] config.i18n.default_locale = :en config.i18n.fallbacks = true ... end end
Diese Einstellungen legen die grundlegende Sprachkonfiguration der Anwendung fest. Mit available_locales wird definiert, welche Sprachen offiziell unterstützt werden. default_locale bestimmt die Standardsprache, die verwendet wird, wenn keine andere Sprache angegeben ist. Die Option fallbacks = true sorgt dafür, dass Rails automatisch auf die Standardsprache zurückgreift, falls für einen bestimmten Text keine Übersetzung vorhanden ist. Damit ist die grundlegende Konfiguration der Mehrsprachigkeit abgeschlossen.
Alle Übersetzungen in Rails werden in YAML-Dateien gespeichert. YAML ist ein leicht lesbares Format, das hierarchische Strukturen unterstützt. Jede Sprache erhält eine oder mehrere eigene Datei. Im Ordner config/locales erstellen wir zwei Dateien.
en: hello_world: "Hello World" language: english: "English" german: "German"
de: hello_world: "Hallo Welt" language: english: "Englisch" german: "Deutsch"
Die oberste Ebene (en: oder de:) definiert jeweils die Sprache. Darunter folgen die eigentlichen Übersetzungsschlüssel. Diese Schlüssel sind später die Referenzen, die wir im Code verwenden. Wichtig ist, dass die Struktur in beiden Dateien identisch bleibt, damit alle Texte in jeder Sprache vorhanden sind.
Um die Übersetzungen auf einer Seite in der App ansehen zu können erstellen wir nun eine einfache Startseite
rails generate controller Home index
Dieser Generator erstellt mehrere grundlegende Bestandteile der Anwendung. Dazu gehören der Controller app/controllers/home_controller.rb, in dem die Anwendungslogik implementiert werden kann, sowie die View app/views/home/index.html.erb, die die eigentliche Seite mit dem ausgelieferten HTML-Inhalt enthält. Zusätzlich wird ein Routeneintrag erstellt, damit die Seite über eine URL erreichbar ist. Außerdem generiert Rails automatisch Test- und Helper-Dateien, die die Entwicklung und Wartung der Anwendung unterstützen.
Öffne anschließend nun die app/views/home/index.html.erb und füge ein:
<h1><%= t('hello_world') %></h1> <p> <%= link_to t('language.english'), locale: :en %> <%= link_to t('language.german'), locale: :de %> </p>
Die Methode t ruft die jeweilige Übersetzung basierend auf der aktiven Sprache ab. Rails verwendet dafür intern I18n.t.
Nun wollen wir die Sprachauswahl per URL implementieren. Dafür haben wir bereits in der View Links erstellt für Englisch und Deutsch. Diese allerdings noch nicht die endgültige URL haben.
Hierzu sollen die Routen /en und /de erstellt werden. In der Datei config/routes.rb passen wir deswegen die Routen an:
Rails.application.routes.draw do scope "(:locale)", locale: /en/de/ do root "home#index" end end
Der scope sorgt dafür, dass optional ein locale-Parameter in der URL enthalten ist. Der reguläre Ausdruck stellt sicher, dass nur en oder de erlaubt sind.
Zusätzlich müssen wir Rails noch mitteilen, wie es mit diesem Parameter umgehen soll. Dafür öffnen wir app/controllers/application_controller.rb und ergänzen:
class ApplicationController < ActionController::Base before_action :set_locale private def set_locale I18n.locale = params[:locale] || I18n.default_locale end def default_url_options { locale: I18n.locale} end end
set_locale wird vor jeder Anfrage ausgeführt und setzt die aktuelle Sprache anhand des URL-Parameters. default_url_options stellt sicher, dass generierte Links automatisch die aktuelle Sprache enthalten.
Starte nun den Server neu mit rails server und rufe die URL http://127.0.0.1:3000/en. Es erscheint „Hallo World“. Rufe http://127.0.0.1:3000/de und es erscheint „Hallo Welt“.
Bis zu diesem Punkt haben wir unsere Übersetzungen direkt in YAML-Dateien innerhalb der Rails-Anwendung verwaltet. Für kleine Projekte ist das vollkommen ausreichend. Mit wachsender Anwendung wird diese Vorgehensweise allerdings schnell unübersichtlich. Spätestens wenn mehrere Entwickler, Produktmanager oder Übersetzer an den Texten arbeiten sollen, entsteht ein Problem: Änderungen müssen manuell in YAML-Dateien gepflegt werden, Git-Merges werden komplizierter und nicht-technische Personen haben keinen einfachen Zugriff auf die Inhalte.
Genau hier setzt localeUI an. Die Plattform dient als zentrale Verwaltung für Übersetzungen. Statt Texte direkt im Code zu bearbeiten, werden sie in einem Webinterface gepflegt und anschließend automatisch mit der Anwendung synchronisiert.
Der erste Schritt besteht darin, einen Account bei localeUI anzulegen. Nach der Registrierung und dem Login kann ein neues Projekt erstellt werden. Ein Projekt entspricht dabei in der Regel einer Anwendung oder einem Service. Eine Anleitung dafür findet sich in der Dokumentation von localeUI unter: Erste Schritte.
Beim Erstellen des Projekts wird zunächst die Default-Sprache festgelegt. In unserem Beispiel wählen wir Englisch, da dies auch die Standardsprache unserer Rails-App ist. Anschließend können weitere Sprachen hinzugefügt werden, beispielsweise Deutsch.
Sobald das Projekt erstellt wurde, stellt localeUI die notwendigen Zugangsdaten für die API bereit. Dazu gehören in der Regel ein API-Key, der zur Authentifizierung deiner Anwendung dient, sowie eine Project-ID, über die das konkrete Projekt eindeutig identifiziert wird. Diese beiden Werte werden später in der Rails-Anwendung hinterlegt, damit sie eine Verbindung zum localeUI-Projekt herstellen und Übersetzungen synchronisieren kann. Der API-Key stellt dabei sicher, dass nur autorisierte Anwendungen auf das Projekt zugreifen können, während die Project-ID angibt, in welchem Projekt die Übersetzungsdaten gespeichert und verwaltet werden.
Über die Weboberfläche von localeUI können anschließend Übersetzungen verwaltet, geändert oder ergänzt werden. Der große Vorteil: Auch Personen ohne Zugriff auf den Quellcode können Texte bearbeiten, während Entwickler weiterhin über automatisierte Synchronisation mit den lokalen Dateien arbeiten.
Detaillierte Informationen über die Schritte finden sie in den verknüpften Seiten zu diesem Artikel.
Nachdem das Projekt auf localeUI eingerichtet wurde, müssen wir unsere Rails-Anwendung mit dieser Plattform verbinden. Dafür stellt localeUI ein eigenes Ruby-Gem bereit, das sich direkt in Rails integrieren lässt.
Zunächst öffnen wir die Datei Gemfile im Projekt und ergänzen dort das Gem:
gem "localeui"
In der Gemfile werden in Rails zusätzliche Bibliotheken eingebunden. Nachdem das Gem dort eingetragen wurde, lässt es sich mit Bundler installieren und steht der Anwendung anschließend zur Verfügung.
Die Installation erfolgt mit:
bundle install
Dieser Befehl lädt das Gem aus dem RubyGems-Repository herunter und installiert alle benötigten Abhängigkeiten. Gleichzeitig werden auch neue Rails-Tasks aus dem Gem verfügbar, die später für die Synchronisation der Übersetzungen genutzt werden.
Als nächsten Schritt führen wir den Installationsgenerator des Gems aus:
rails generate localeui:install
Generatoren sind ein typisches Rails-Konzept. Sie erzeugen automatisch Dateien oder Konfigurationen, die für ein bestimmtes Feature benötigt werden. In diesem Fall erstellt der Generator eine Konfigurationsdatei für localeUI.
Nach dem Ausführen des Befehls findest du im config-Ordner eine neue Datei config/initializers/localeui.yml. Diese Datei enthält die Konfiguration für das Gem. Ebenfalls tragen wir die Zugangsdaten zur Authentifizierung und Projekt Identifikation ein.
Localeui.config do |config| ... # Authentication Token config.api_token = 'DEIN API KEY' # Project API ID config.project_id = 'DEINE PROJEKT ID' ... end
Der API-Key dient dabei als Authentifizierungsschlüssel. Über die Project-ID weiß localeUI, mit welchem Projekt die Anwendung synchronisiert werden soll.
Damit ist die technische Verbindung zwischen Rails und localeUI eingerichtet. Dies kann mit folgendem Befehl getestet werden.
rails localeui:project_info
Nach erfolgreicher Verbindung werden Informationen zum Projekt in der Konsole ausgegeben. Damit ist die Integration abgeschlossen und die Synchronisation der Übersetzungen kann beginnen.
Nachdem die Integration abgeschlossen ist, müssen die bestehenden Übersetzungen aus der Rails-Anwendung erstmals an localeUI übertragen werden. Unsere bisherigen YAML-Dateien enthalten bereits einige Schlüssel, beispielsweise hello_world oder language.english. Diese sollen nun in das localeUI-Projekt importiert werden.
Um die Übersetzungen zu übertragen nutzen wir den Befehl, der von dem Gem bereit gestellt wird:
rails localeui:upload
Mit diesem Befehl werden die YAML-Dateien aus dem Ordner config/locales an unser Projekt bei localeUI übertragen. Dort verarbeitet localeUI die Dateien automatisch und liest die enthaltenen Übersetzungsschlüssel aus. Die erkannten Keys werden anschließend im Projekt angelegt und stehen direkt in der Weboberfläche zur Verfügung. Ab diesem Zeitpunkt können die Übersetzungen bequem im localeUI-Interface gepflegt oder ergänzt werden, ohne dass die YAML-Dateien manuell angepasst werden müssen.
Nachdem Änderungen im localeUI-Webinterface gemacht wurden – zum Beispiel neue Übersetzungen oder angepasste Übersetzungen – können wir diese ganz einfach wieder in unsere Rails-Anwendung holen. Dafür rufen wir den Befehl:
rails localeui:download
Dieser Befehl ruft die aktuellen Übersetzungsdateien über die API von localeUI ab und legt anschließend die YAML-Dateien im Ordner config/locales. So bleiben die Dateien in der Anwendung automatisch auf dem gleichen Stand wie das Projekt in localeUI, ohne dass man Übersetzungen manuell kopieren oder an mehreren Stellen pflegen muss.
Mit wenigen Konfigurationsschritten lässt sich in Rails eine saubere Internationalisierung umsetzen. Das integrierte I18n-System ist flexibel, klar strukturiert und gut erweiterbar. Die URL-basierte Sprachumschaltung sorgt für transparente und SEO-freundliche Routen.
Durch die zusätzliche Integration von localeUI entsteht eine professionelle Lösung für größere Projekte, in denen Übersetzungen zentral verwaltet und von mehreren Beteiligten gepflegt werden.
Die Kombination aus Rails-I18n und einer spezialisierten Lokalisierungsplattform bietet damit eine solide Grundlage für mehrsprachige Anwendungen jeder Größe.