Eine Rails-App lokalisieren

Rails-YAML mit Sprachwurzel übersetzen und Schlüsselauflösung, Interpolation, Pluralformen sowie die Sprachauswahl pro Anfrage kontrollieren.

Rails sorgt mit t und I18n.t bereits für stabile Meldungsnamen. Lingo.dev kann die dahinterliegenden YAML-Inhalte übersetzen, während Rails weiterhin Schlüsselauflösung, Interpolation und Sprachauswahl übernimmt. Beginne mit einer Begrüßung und der Anzahl der Benachrichtigungen und teste beides anschließend mit denselben Hilfsmethoden, die auch die Anwendung verwendet.

Quellmeldungen in einer Rails-Sprachdatei ablegen #

Erstelle oder erweitere config/locales/en.yml:

yaml
en:
  home:
    index:
      welcome: "Welcome, %{name}!"
      cta: "Create an account"
  notifications:
    unread:
      one: "One unread notification"
      other: "%{count} unread notifications"

In app/views/home/index.html.erb lässt sich die Begrüßung über einen zur View relativen Schlüssel auflösen:

erb
<h1><%= t(".welcome", name: @user_name) %></h1>
<p><%= t("notifications.unread", count: @unread_count) %></p>

Der View-Pfad gibt .welcome den vollständigen Schlüssel home.index.welcome. Die aufrufende Stelle übergibt name und count; diese Interpolationsnamen müssen in der Übersetzung erhalten bleiben. Pluralschlüssel wie one und other kennzeichnen die jeweiligen Zweige und bleiben unverändert.

Verschiebe beim Ausbau der Übersetzungsabdeckung die übrigen fest im Code hinterlegten View-Beschriftungen, Mailer-Texte und Modellfehlermeldungen in die passenden Sprach-Namensräume. Die Übersetzung einer Datei wirkt sich nur auf die aufrufenden Stellen aus, die ihre Meldungen laden.

YAML mit Sprachwurzel auswählen #

Rails liest die Sprache aus der YAML-Wurzel. Wenn du en.yml in es.yml umbenennst, aber en: beibehältst, definiert die Datei weiterhin englische Meldungen. Verwende den Handler yaml-root-key, um die Werte zu übersetzen und gleichzeitig die Wurzel umzubenennen.

Installiere und verknüpfe die CLI im Stammverzeichnis des Projekts:

sh
npm install --global @lingo.dev/cli
lingo login
lingo init --source en --targets es,fr --files 'config/locales/en.yml' --yes
lingo link

Behalte die in .lingo/config.json gespeicherten IDs der Organisation und der Lokalisierungs-Engine bei. Trage in das zugehörige Array files die Quelleinträge ein, die dein Projekt verwendet:

json
[
  { "pattern": "config/locales/en.yml", "format": "yaml-root-key" },
  { "pattern": "config/locales/*.en.yml", "format": "yaml-root-key" }
]

Der zweite Eintrag erfasst nach Themenbereichen getrennte Dateien wie mailers.en.yml, ohne deren übersetzte Gegenstücke auszuwählen. Entferne ihn, wenn das Projekt keine solchen Dateien enthält. Lege das Format ausdrücklich fest: Generisches YAML behält alle Wurzeln bei, während die automatische Dateierkennung der CLI für YAML-Quellen eine explizite Formatauswahl erfordert. YAML mit Sprachwurzel beschreibt die Anforderung an ein Mapping mit genau einem Wurzelschlüssel und das Verhalten bei der Rekonstruktion.

Übersetzen und geladene Werte ansehen #

Führe für fehlende Zieldateien Folgendes aus:

sh
lingo push --backfill-missing --wait

Öffne nach Abschluss des Durchlaufs config/locales/es.yml und stelle sicher, dass die Wurzel es: lautet. Kontrolliere, ob die verschachtelten Schlüssel und Interpolationsnamen mit der Quelle übereinstimmen. Sieh dir nach der Serialisierung auch alle Kommentare, Anker und Aliase an. Ein anderer Aufbau der Quelldateien kann einen expliziten Zielpfad erfordern.

Lade das Ergebnis in der Rails-Konsole oder in den Tests der Anwendung und wähle dabei die Sprache explizit aus:

ruby
I18n.with_locale(:es) do
  puts I18n.t("home.index.welcome", name: "Alex", raise: true)
  [0, 1, 2, 20].each do |count|
    puts I18n.t("notifications.unread", count: count, raise: true)
  end
end

Konfiguriere vor diesem Test :en, :es und :fr als verfügbare Sprachen. Das Beispiel testet Schlüsselauflösung und Interpolation; gleiche den Wortlaut mit der beabsichtigten Begrüßung und der Anzahl der Benachrichtigungen ab. Zielsprachen können Pluralregeln und Zweige erfordern, die über die englischen Formen der Quelle hinausgehen. Führe denselben Test für Französisch sowie für die Mailer- und Validierungs-Namensräume der Anwendung durch, sobald diese hinzukommen.

Für dieselbe Sprachauswahl in Anfragen sorgen #

Lege in der Rails-Konfiguration die unterstützten Sprachen und eine Standardsprache fest. Umschließe die Anfrageverarbeitung mit I18n.with_locale und verwende dabei einen Wert aus den unterstützten Sprachen. So wird der Sprachzustand nicht in eine andere Anfrage übernommen.

Konfiguriere für URLs wie /es sowohl den Geltungsbereich der Route als auch den Controller, der params[:locale] ausliest. Behalte die Sprache in generierten Links bei. Wenn die Anwendung auch Accept-Language aushandelt, werte Qualitätsgewichtungen und regionale Kennungen aus, statt einfach eine Teilzeichenfolge aus zwei Buchstaben zu verwenden. Eine explizite Sprachauswahl durch Nutzende sollte Vorrang haben, sofern die Anwendung sie unterstützt.

Lege das Fallback-Verhalten bewusst fest. Ein Fallback kann eine Seite nutzbar halten und zugleich eine fehlende spanische Meldung verbergen. Kontrolliere daher die erforderlichen Zieleinträge, ohne dich auf den Fallback zu verlassen. Verwende gegebenenfalls die Rails-Hilfsmethode l zur Lokalisierung von Datum und Uhrzeit, statt ein vorformatiertes Datum als Text zu übersetzen.

Öffne eine Seite in der Zielsprache sowohl direkt als auch über die Navigation. Vergewissere dich, dass Rails den Ziel-Namensraum auswählt, die erwarteten interpolierten Werte anzeigt und mit längeren Texten zurechtkommt. lingo check kontrolliert nicht die Vollständigkeit von Rails-YAML; das Laden und Rendern durch Rails sowie die sprachliche Prüfung müssen Teil des Abnahmeprozesses bleiben.

Übersetzungen bei späteren Quelländerungen pflegen #

Halte Quelldateien, akzeptierte Zieldateien, Konfiguration und .lingo/lock.json zusammen. Führe nach der Änderung einer Meldung lingo push --wait für die regulären Änderungen aus und vergleiche die geänderte Meldung mit einer unveränderten benachbarten Meldung. Für eine gezielte Korrektur bei unverändertem Quellwortlaut bearbeitest du das Ziel direkt: Der Übersetzungsumfang auf YAML-Schlüsselebene kann die vorhandene Übersetzung wiederverwenden. Um nach einer Änderung der Vorgaben neu zu generieren, sichere die akzeptierten Zieldateien, bevor du innerhalb des festgelegten Umfangs ganze Dateien ersetzt, wie unter Übersetzungsumfang beschrieben.

Wenn lokale Korrekturen in Zieldateien vor abweichenden Änderungen geschützt werden müssen, reiche den Auftrag ohne --wait ein, sieh dir lingo pull --dry-run an und rufe das Ergebnis im selben checkout ab, aus dem du den Auftrag eingereicht hast. Beim Zurückschreiben nach dem Warten fehlt diese erneute Konfliktkontrolle. Andere checkouts erhalten die per Commit gespeicherten Übersetzungen über die Versionsverwaltung. Siehe Übersetzungen nach der Prüfung bewahren.

Sobald der lokale Ablauf funktioniert, wähle die GitHub App oder die CI-Automatisierung. Führe vor dem Merge der Übersetzungsänderungen dieselben Rails-Tests für die generierten Ressourcen aus.