Phoenix I18n

() translation by (you can also view the original English article)

In meinen vorherigen Artikeln habe ich die verschiedenen Aspekte von Elixir behandelt - einer modernen funktionalen Programmiersprache. Heute möchte ich mich jedoch von der Sprache selbst entfernen und ein sehr schnelles und zuverlässiges MVC-Framework namens Phoenix diskutieren, das in Elixir geschrieben ist.

Dieses Framework ist vor fast fünf Jahren entstanden und hat seitdem einige Zugkraft erhalten. Natürlich ist es noch nicht so beliebt wie Rails oder Django, aber es hat großes Potenzial und ich mag es wirklich.

In diesem Artikel erfahren Sie, wie Sie I18n in Phoenix-Anwendungen einführen. Was ist I18n, fragen Sie? Nun, es ist ein Numeronym, das "Internationalisierung" bedeutet, da zwischen dem ersten Buchstaben "i" und dem letzten "n" genau 18 Zeichen liegen. Wahrscheinlich haben Sie auch ein L10n-Numeronym getroffen, das "Lokalisierung" bedeutet. Entwickler sind heutzutage so faul, dass sie nicht einmal ein paar zusätzliche Charaktere schreiben können, oder?

Die Internationalisierung ist ein sehr wichtiger Prozess, insbesondere wenn Sie davon ausgehen, dass die Anwendung von Menschen aus der ganzen Welt verwendet wird. Schließlich kann nicht jeder gut Englisch, und die Übersetzung der App in die Muttersprache eines Benutzers vermittelt einen guten Eindruck.

Es scheint, dass der Prozess der Übersetzung von Phoenix-Anwendungen etwas anders ist als beispielsweise die Übersetzung von Rails-Apps (aber dem gleichen Prozess in Django ziemlich ähnlich). Für die Übersetzung von Phoenix-Anwendungen verwenden wir eine sehr beliebte Lösung namens Gettext, die es bereits seit mehr als 25 Jahren gibt. Gettext arbeitet mit speziellen Dateitypen, nämlich PO und POT, und unterstützt Funktionen wie Scoping, Pluralisierung und andere Extras.

In diesem Beitrag werde ich Ihnen erklären, was Gettext ist, wie sich PO von POT unterscheidet, wie Nachrichten in Phoenix lokalisiert werden und wo Übersetzungen gespeichert werden. Außerdem werden wir sehen, wie Sie das Gebietsschema der Anwendung wechseln und wie Sie mit Pluralisierungsregeln und -domänen arbeiten.

Sollen wir anfangen?

Internationalisierung mit Gettext

Gettext ist ein kampferprobtes Open-Source-Internationalisierungstool, das 1990 von Sun Microsystems eingeführt wurde. 1995 veröffentlichte GNU eine eigene Version von Gettext, die heute als die beliebteste auf dem Markt gilt (die neueste Version war zum Zeitpunkt des Schreibens dieses Artikels 0.19.8). Mit Gettext können mehrsprachige Systeme jeder Größe und jedes Typs erstellt werden, von Web-Apps bis hin zu Betriebssystemen. Diese Lösung ist ziemlich komplex und wir werden natürlich nicht alle ihre Funktionen diskutieren. Die vollständige Gettext-Dokumentation finden Sie unter gnu.org.

Gettext bietet Ihnen alle erforderlichen Tools zur Durchführung der Lokalisierung und stellt einige Anforderungen an die Benennung und Organisation von Übersetzungsdateien. Zum Hosten von Übersetzungen werden zwei Dateitypen verwendet: PO und MO.

PO-Dateien (Portable Object) speichern Übersetzungen für bestimmte Zeichenfolgen sowie Pluralisierungsregeln und Metadaten. Diese Dateien haben eine recht einfache Struktur und können von einem Menschen leicht bearbeitet werden. In diesem Artikel werden wir uns also an sie halten. Jede PO-Datei enthält Übersetzungen (oder einen Teil der Übersetzungen) für eine einzelne Sprache und sollte in einem Verzeichnis gespeichert werden, das nach dieser Sprache benannt ist: en, fr, de usw.

MO-Dateien (Machine Object) enthalten Binärdaten, die nicht direkt von einem Menschen bearbeitet werden sollen. Es ist schwieriger, mit ihnen zu arbeiten, und ihre Erörterung fällt nicht in den Geltungsbereich dieses Artikels.

Um die Dinge komplexer zu gestalten, gibt es auch POT-Dateien (Portable Object Template). Sie hosten nur zu übersetzende Zeichenfolgen, nicht jedoch die Übersetzungen selbst. Grundsätzlich werden POT-Dateien nur als Blaupausen verwendet, um PO-Dateien für verschiedene Gebietsschemas zu erstellen.

Beispiel für eine Phoenix-Anwendung

Okay, jetzt lassen Sie uns weiter üben! Wenn Sie mitmachen möchten, stellen Sie sicher, dass Sie Folgendes installiert haben:

OTP (Version 18 oder höher)
Elixier (1.4+)
Phoenix Framework (Ich werde Version 1.3 verwenden)

Erstellen Sie eine neue Beispielanwendung ohne Datenbank, indem Sie Folgendes ausführen:

1	mix phx.new i18ndemo --no-ecto

--no-ecto sagt, dass die Datenbank nicht von der App verwendet werden sollte (Ecto ist ein Werkzeug zur Kommunikation mit der Datenbank selbst). Beachten Sie, dass der Generator möglicherweise einige Minuten benötigt, um alles vorzubereiten.

Verwenden Sie nun cd, um zum neu erstellten i18ndemo-Ordner zu wechseln, und führen Sie den folgenden Befehl aus, um den Server zu starten:

1	mix phx.server

Öffnen Sie als Nächstes den Browser und navigieren Sie zu http://localhost:4000, wo eine "Willkommen in Phoenix!"-Botschaft erscheint.

Hallo Gettext!

Das Interessante an unserer Phoenix-App und insbesondere an der Begrüßungsnachricht ist, dass Gettext bereits standardmäßig verwendet wird. Öffnen Sie die Datei demo/lib/demo_web/templates/page/index.html.eex, die als Standardstartseite fungiert. Entfernen Sie alles außer diesem Code:

1	<div class="jumbotron">
2	<h2><%= gettext "Welcome to %{name}!", name: "Phoenix" %></h2>
3	</div>

Diese Begrüßungsnachricht verwendet eine gettext-Funktion, die eine Zeichenfolge akzeptiert, die als erstes Argument übersetzt werden soll. Diese Zeichenfolge kann als Übersetzungsschlüssel betrachtet werden, unterscheidet sich jedoch etwas von den in Rails I18n und einigen anderen Frameworks verwendeten Schlüsseln. In Rails hätten wir einen Schlüssel wie page.welcome verwendet, während hier die übersetzte Zeichenfolge selbst ein Schlüssel ist. Wenn die Übersetzung nicht gefunden werden kann, können wir diese Zeichenfolge direkt anzeigen. Selbst ein Benutzer, der schlecht Englisch kann, kann zumindest einen grundlegenden Eindruck davon bekommen, was los ist.

Dieser Ansatz ist eigentlich sehr praktisch - halten Sie eine Sekunde inne und denken Sie darüber nach. Sie haben eine Anwendung, in der alle Nachrichten auf Englisch sind. Wenn Sie es internationalisieren möchten, müssen Sie im einfachsten Fall Ihre Nachrichten nur mit der Funktion gettext umschließen und Übersetzungen für sie bereitstellen (später werden wir sehen, dass das Extrahieren der Schlüssel leicht automatisiert werden kann, was die Geschwindigkeit Dinge noch mehr beschleunigt).

Okay, kehren wir zu unserem kleinen Code-Snippet zurück und werfen einen Blick auf das zweite Argument, das an gettext übergeben wurde: name: "Phoenix". Dies ist eine sogenannte Bindung - ein Parameter, der mit %{} umschlossen ist und den wir in die angegebene Übersetzung interpolieren möchten. In diesem Beispiel gibt es nur einen Parameter namens name.

Wir können dieser Seite zu Demonstrationszwecken noch eine weitere Nachricht hinzufügen:

<div class="jumbotron">
  <h2><%= gettext "Welcome to %{name}!", name: "Phoenix" %></h2>
  <h3><%= gettext "We are using version %{version}",
  version: "1.3" %></h3>
</div>

Hinzufügen einer neuen Übersetzung

Nachdem wir zwei Nachrichten auf der Stammseite haben, wo sollen wir Übersetzungen für sie hinzufügen? Es scheint, dass alle Übersetzungen im Ordner priv/gettext gespeichert sind, der eine vordefinierte Struktur hat. Nehmen wir uns einen Moment Zeit, um zu besprechen, wie Gettext-Dateien organisiert werden sollten (dies gilt nicht nur für Phoenix, sondern für jede App, die Gettext verwendet).

Zunächst sollten wir einen Ordner erstellen, der nach dem Gebietsschema benannt ist, für das Übersetzungen gespeichert werden sollen. Im Inneren sollte sich ein Ordner namens LC_MESSAGES befinden, der eine oder mehrere .po-Dateien mit den tatsächlichen Übersetzungen enthält. Im einfachsten Fall hätten Sie eine default.po-Datei pro Gebietsschema. default ist hier der Name der Domain (oder des Bereichs). Domänen werden verwendet, um Übersetzungen in verschiedene Gruppen zu unterteilen: Beispielsweise haben Sie möglicherweise Domänen mit den Namen admin, wysiwig, cart und andere. Dies ist praktisch, wenn Sie eine große Anwendung mit Hunderten von Nachrichten haben. Für kleinere Apps reicht es jedoch aus, nur eine default-Domäne zu haben.

Unsere Dateistruktur könnte also so aussehen:

en
- LC_MESSAGES
  - default.po
  - admin.po
ru
- LC_MESSAGES
  - default.po
  - admin.po

Um mit der Erstellung von PO-Dateien zu beginnen, benötigen wir zunächst die entsprechende Vorlage (POT). Wir können es manuell erstellen, aber ich bin zu faul, um es so zu machen. Lassen Sie uns stattdessen den folgenden Befehl ausführen:

1	mix gettext.extract

Es ist ein sehr praktisches Werkzeug, das die Projektdateien scannt und prüft, ob Gettext irgendwo verwendet wird. Nachdem das Skript seinen Job beendet hat, wird eine neue Datei priv/gettext/default.pot erstellt, die zu übersetzende Zeichenfolgen enthält.

Wie wir bereits erfahren haben, handelt es sich bei POT-Dateien um Vorlagen. Daher werden nur die Schlüssel selbst und nicht die Übersetzungen gespeichert. Ändern Sie diese Dateien daher nicht manuell. Öffnen Sie eine neu erstellte Datei und sehen Sie sich deren Inhalt an:

## This file is a PO Template file.
##
## `msgid`s here are often extracted from source code.
## Add new translations manually only if they're dynamic
## translations that can't be statically extracted.
##
## Run `mix gettext.extract` to bring this file up to
## date. Leave `msgstr`s empty as changing them here as no
## effect: edit them in PO (`.po`) files instead.
msgid ""
msgstr ""

#: lib/demo_web/templates/page/index.html.eex:3
msgid "We are using version %{version}"
msgstr ""

#: lib/demo_web/templates/page/index.html.eex:2
msgid "Welcome to %{name}!"
msgstr ""

Praktisch, nicht wahr? Alle unsere Nachrichten wurden automatisch eingefügt, und wir können leicht genau sehen, wo sie sich befinden. msgid ist, wie Sie wahrscheinlich erraten haben, der Schlüssel, während msgstr eine Übersetzung enthalten wird.

Der nächste Schritt ist natürlich das Generieren einer PO-Datei. Nutzen Sie:

1	mix gettext.merge priv/gettext

Dieses Skript verwendet die Vorlage default.pot und erstellt eine Datei default.po im Ordner priv/gettext/de/LC_MESSAGES. Derzeit haben wir nur ein englisches Gebietsschema, aber die Unterstützung für eine andere Sprache wird auch im nächsten Abschnitt hinzugefügt.

Übrigens ist es möglich, die POT-Vorlage und alle PO-Dateien auf einmal mit dem folgenden Befehl zu erstellen oder zu aktualisieren:

1	mix gettext.extract --merge

Öffnen wir nun die Datei priv/gettext/de/LC_MESSAGES/default.po, die folgenden Inhalt hat:

## `msgid`s in this file come from POT (.pot) files.
##
## Do not add, change, or remove `msgid`s manually here as
## they're tied to the ones in the corresponding POT file
## (with the same domain).
##
## Use `mix gettext.extract --merge` or `mix gettext.merge`
## to merge POT files into PO files.
msgid ""
msgstr ""
"Language: en\n"

#: lib/demo_web/templates/page/index.html.eex:3
msgid "We are using version %{version}"
msgstr ""

#: lib/demo_web/templates/page/index.html.eex:2
msgid "Welcome to %{name}!"
msgstr ""

Dies ist die Datei, in der wir die eigentliche Übersetzung durchführen sollen. Natürlich macht es wenig Sinn, dies zu tun, da die Nachrichten bereits auf Englisch sind. Fahren wir also mit dem nächsten Abschnitt fort und fügen Unterstützung für eine zweite Sprache hinzu.

Mehrere Gebietsschemas

Das Standardgebietsschema für Phoenix-Anwendungen ist natürlich Englisch. Diese Einstellung kann jedoch einfach durch Ändern der Datei config/config.exs geändert werden. Stellen Sie beispielsweise das Standardgebietsschema auf Russisch ein (Sie können sich auch an eine andere Sprache Ihrer Wahl halten):

1	config :demo, I18ndemoWeb.Gettext, default_locale: "ru"

Es ist auch eine gute Idee, die vollständige Liste aller unterstützten Gebietsschemas anzugeben:

1	config :demo, I18ndemoWeb.Gettext, default_locale: "ru", locales: ~w(en ru)

Jetzt müssen wir eine neue PO-Datei mit Übersetzungen für das russische Gebietsschema erstellen. Dies kann durch erneutes Ausführen des Skripts gettext.merge erfolgen, jedoch mit einem Schalter --locale:

1	mix gettext.merge priv/gettext --locale ru

Offensichtlich wird ein priv/gettext/ru/LC_MESSAGES-Ordner mit den darin enthaltenen .po-Dateien generiert. Beachten Sie übrigens, dass wir neben der Datei default.po auch die Datei error.po haben. Dies ist ein Standardort zum Übersetzen von Fehlermeldungen, aber in diesem Artikel werden wir ihn ignorieren.

Optimieren Sie nun die Datei priv/gettext/ru/LC_MESSAGES/default.po, indem Sie einige Übersetzungen hinzufügen:

#: lib/demo_web/templates/page/index.html.eex:3
msgid "We are using version %{version}"
msgstr "Используется версия %{version}"

#: lib/demo_web/templates/page/index.html.eex:2
msgid "Welcome to %{name}!"
msgstr "Добро пожаловать в приложение %{name}!"

Abhängig vom ausgewählten Gebietsschema wird Phoenix nun entweder englische oder russische Übersetzungen rendern. Aber warten Sie! Wie können wir in unserer Anwendung tatsächlich zwischen Gebietsschemas wechseln? Fahren wir mit dem nächsten Abschnitt fort und finden es heraus!

Zwischen Gebietsschemas wechseln

Nachdem einige Übersetzungen vorhanden sind, müssen wir unseren Benutzern ermöglichen, zwischen Gebietsschemas zu wechseln. Es scheint, dass es dafür einen Plug-in eines Drittanbieters namens set_locale gibt. Es funktioniert, indem das ausgewählte Gebietsschema aus der URL oder dem HTTP-Header in Accept-Language extrahiert wird. Um ein Gebietsschema in der URL anzugeben, geben Sie http://localhost:4000/de/some_path ein. Wenn das Gebietsschema nicht angegeben ist (oder wenn eine nicht unterstützte Sprache angefordert wurde), geschieht eines von zwei Dingen:

Wenn die Anforderung einen HTTP-Header in Accept-Language enthält und dieses Gebietsschema unterstützt wird, wird der Benutzer auf eine Seite mit dem entsprechenden Gebietsschema umgeleitet.
Andernfalls wird der Benutzer automatisch zu einer URL umgeleitet, die den Code des Standardgebietsschemas enthält.

Öffnen Sie die Datei mix.exs und legen Sie in set_locale die deps-Funktion ab:

  defp deps do
    [
      # ...
      {:set_locale, "~> 0.2.1"}
    ]
  end

Wir müssen es auch der application-Funktion hinzufügen:

  def application do
    [
      mod: {Demo.Application, []},
      extra_applications: [:logger, :runtime_tools, :set_locale]
    ]
  end

Als nächstes installieren Sie alles:

1	mix deps.get

Unser Router unter lib/demo_web/router.ex erfordert ebenfalls einige Änderungen. Insbesondere müssen wir der :browser-Pipeline einen neuen Plug hinzufügen:

1	pipeline :browser do
2	# ...
3	plug SetLocale, gettext: DemoWeb.Gettext, default_locale: "ru"
4	end

Erstellen Sie außerdem einen neuen Bereich:

  scope "/:locale", DemoWeb do
    pipe_through :browser

    get "/", PageController, :index
  end

Und das ist es! Sie können den Server starten und zu http://localhost:4000/ru und http://localhost:4000/en navigieren. Beachten Sie, dass die Nachrichten richtig übersetzt werden, genau das, was wir brauchen!

Alternativ können Sie eine ähnliche Funktion selbst mithilfe eines Modulsteckers codieren. Ein kleines Beispiel finden Sie im offiziellen Phoenix-Leitfaden.

Als letztes muss erwähnt werden, dass Sie in einigen Fällen möglicherweise ein bestimmtes Gebietsschema erzwingen müssen. Verwenden Sie dazu einfach eine with_locale-Funktion:

1	Gettext.with_locale I18ndemoWeb.Gettext, "en", fn ->
2	MyApp.I18ndemoWeb.gettext("test")
3	end

Pluralisierung

Wir haben die Grundlagen der Verwendung von Gettext mit Phoenix gelernt, daher ist es an der Zeit, etwas komplexere Dinge zu diskutieren. Pluralisierung ist einer von ihnen. Grundsätzlich ist das Arbeiten mit Plural- und Singularformen eine sehr häufige, wenn auch möglicherweise komplexe Aufgabe. Die Dinge sind auf Englisch mehr oder weniger offensichtlich, da Sie "1 Apfel", "2 Äpfel", "9000 Äpfel" usw. haben (obwohl "1 Ochse", "2 Ochsen"!).

Leider sind die Regeln in einigen anderen Sprachen wie Russisch oder Polnisch komplexer. Im Fall von Äpfeln würden Sie beispielsweise "1 яблоко", "2 яблока", "9000 яблок" sagen. Glücklicherweise hat Phoenix ein Gettext.Plural-Verhalten (Sie können das Verhalten in einem meiner vorherigen Artikel in Aktion sehen), das viele verschiedene Sprachen unterstützt. Daher müssen wir nur die ngettext-Funktion nutzen.

Diese Funktion akzeptiert drei erforderliche Argumente: eine Zeichenfolge in Singularform, eine Zeichenfolge in Pluralform und count. Das vierte Argument ist optional und kann Bindungen enthalten, die in die Übersetzung interpoliert werden sollen.

Lassen Sie uns ngettext in Aktion sehen, indem Sie sagen, wie viel Geld der Benutzer hat, indem Sie die Datei demo/lib/demo_web/templates/page/index.html.eex ändern:

1	<p>
2	<%= ngettext "You have one buck. Ow :(", "You have %{count} bucks", 540 %>
3	</p>

%{count} ist eine Interpolation, die durch eine Zahl ersetzt wird (in diesem Fall 540). Vergessen Sie nicht, die Vorlage und alle PO-Dateien nach dem Hinzufügen der obigen Zeichenfolge zu aktualisieren:

1	mix gettext.extract --merge

Sie werden sehen, dass beiden default.po-Dateien ein neuer Block hinzugefügt wurde:

1	msgid "You have one buck. Ow :("
2	msgid_plural "You have %{count} bucks"
3	msgstr[0] ""
4	msgstr[1] ""

Wir haben hier nicht nur einen, sondern zwei Schlüssel gleichzeitig: im Singular und im Plural. msgstr[0] enthält Text, der angezeigt werden soll, wenn nur eine Nachricht vorhanden ist. msgstr[1] enthält natürlich den Text, der angezeigt werden soll, wenn mehrere Nachrichten vorhanden sind. Dies ist in Ordnung für Englisch, aber nicht genug für Russisch, wo wir einen dritten Fall einführen müssen:

1	msgid "You have one buck. Ow :("
2	msgid_plural "You have %{count} bucks"
3	msgstr[0] "У 1 доллар. Маловато будет!"
4	msgstr[1] "У вас %{count} доллара"
5	msgstr[2] "У вас %{count} долларов"

Fall 0 wird für 1 Dollar und Fall 1 für null oder wenige Dollar verwendet. Fall 2 wird anders verwendet.

Scoping von Übersetzungen mit Domains

Ein weiteres Thema, das ich in diesem Artikel diskutieren wollte, ist Domains gewidmet. Wie wir bereits wissen, werden Domänen verwendet, um Übersetzungen zu erfassen, hauptsächlich in großen Anwendungen. Grundsätzlich verhalten sie sich wie Namespaces.

Schließlich können Sie in eine Situation geraten, in der derselbe Schlüssel an mehreren Stellen verwendet wird, die jedoch etwas anders übersetzt werden sollte. Oder wenn Sie viel zu viele Übersetzungen in einer einzigen default.po-Datei haben und diese irgendwie aufteilen möchten. Dann können Domains sehr nützlich sein.

Gettext unterstützt sofort mehrere Domains. Sie müssen lediglich die dgettext-Funktion verwenden, die fast genauso funktioniert wie gettext. Der einzige Unterschied besteht darin, dass der Domänenname als erstes Argument akzeptiert wird. Lassen Sie uns beispielsweise eine Benachrichtigungsdomäne einführen, um Benachrichtigungen anzuzeigen. Fügen Sie der Datei demo/lib/demo_web/templates/page/index.html.eex drei weitere Codezeilen hinzu:

1	<p>
2	<%= dgettext "notifications", "Heads up: %{msg}", msg: "something has happened!" %>
3	</p>

Jetzt müssen wir neue POT- und PO-Dateien erstellen:

1	mix gettext.extract --merge

Nachdem das Skript seine Arbeit beendet hat, werden notifications.pot sowie zwei notifications.po-Dateien erstellt. Beachten Sie noch einmal, dass sie nach der Domain benannt sind. Jetzt müssen Sie nur noch eine Übersetzung für die russische Sprache hinzufügen, indem Sie die Datei priv/ru/LC_MESSAGES/notifications.po ändern:

1	msgid "Heads up: %{msg}}"
2	msgstr "Внимание: %{msg}"

Was ist, wenn Sie eine unter einer bestimmten Domain gespeicherte Nachricht pluralisieren möchten? Dies ist so einfach wie die Verwendung einer dngettext-Funktion. Es funktioniert genau wie ngettext, akzeptiert aber auch den Namen einer Domain als erstes Argument:

1	dgettext "domain", "Singular string %{msg}", "Plural string %{msg}", 10, msg: "demo"

Abschluss

In diesem Artikel haben wir gesehen, wie Sie mit Hilfe von Gettext die Internationalisierung in einer Phoenix-Anwendung einführen können. Sie haben gelernt, was Gettext ist und mit welcher Art von Dateien es funktioniert. Wir haben diese Lösung in Aktion, haben mit PO- und POT-Dateien gearbeitet und verschiedene Gettext-Funktionen verwendet.

Außerdem haben wir eine Möglichkeit gesehen, Unterstützung für mehrere Gebietsschemas hinzuzufügen und eine Möglichkeit hinzuzufügen, einfach zwischen ihnen zu wechseln. Zuletzt haben wir gesehen, wie man Pluralisierungsregeln anwendet und wie man Übersetzungen mit Hilfe von Domänen umsetzt.

Hoffentlich war dieser Artikel für Sie nützlich! Wenn Sie mehr über Gettext im Phoenix-Framework erfahren möchten, lesen Sie möglicherweise das offizielle Handbuch, das nützliche Beispiele und API-Referenzen für alle verfügbaren Funktionen enthält.

Ich danke Ihnen, dass Sie bei mir bleiben und bis bald!