Texte gehören zu den Teilen einer Anwendung, die häufig geändert werden. Wenn dann noch externe Übersetzer im Spiel sind, kann es leicht zu fehlenden Übersetzungen kommen

Wir möchten deshalb automatisch testen, dass es zu allen Texten in Sprache A auch Übersetzungen in Sprache B vorhanden sind. Ein solcher Test allein hilft schon sehr, und sollte ja nicht so schwierig sein.

Leider gibt es dabei eine Überraschung: in der Internationalisierung-API findet sich zur Zeit (Rails 2.3.5) keine Möglichkeit, alle Schlüssel aufzuzählen (sprich iterieren). Man muss also offenbar die Yaml-Dateien selbst einlesen, um an die Menge aller definierten Schlüssel zu kommen. Unserer Test wird dabei leider abhängig von der konkreten Art der Datenhaltung.

texts_hash = YAML::load(IO.read('config/locales/de.yml'))

Wie haben nun einen rekursiven Hash. Um alle Schlüssel zu überprüfen, extrahieren wie sie mit einer gesonderten Funktion. Diese Funktion ist einfach rekursiv aufgebaut.

def deep_hash_key(hash, prefix)
  hash.keys.sort.collect{|key2|
    val = hash[key2]
    newprefix = prefix.nil? ? key2 : "#{prefix}.#{key2}"
    if val.is_a? Hash
     deep_hash_key(val, newprefix)
    else
      newprefix
    end
  }
end

Wollen wir jetzt die Übersetzungen für alle Schlüssel prüfen lauert die Zweite Falle: Wenn die Übersetzung eine Variableninterpolation enthält, erhalten wir einen Fehler beim Aufrufen der translate() Methode ohne den passenden Hash. Offenbar liefert uns die API auch keinen Zugriff auf den String ohne Interpolierung. Da uns in diesen Test nur die Existenz einer Übersetzung interessiert, und nicht ihr konkreter Wert, fangen wir die Exception “MissingInterpolationArgument” einfach auf.

Für eine deutsche Anwendung mit Übersetzungen in Englisch und Französisch sieht dann der Test so aus:

def test_all_texts_should_exists
  texts_hash = YAML::load(IO.read('config/locales/de.yml'))
  de_keys = deep_hash_key(texts_hash['de'], nil).flatten
  for lang in ['de', 'fr', 'en']
    I18n::locale = lang
    for key in de_keys
      begin
        val = I18n.translate(key, :default => nil, :raise => true)
      rescue I18n::MissingTranslationData
        val = nil
      rescue I18n::MissingInterpolationArgument
        val = true  # there was a value, only an argument is missing
      end
      assert_not_nil(val, "key missing for locale #{lang}: #{key}")
    end
  end
end

Wenn jetzt eine Übersetzung fehlt, liefert der Test eine Fehlermeldung der Art:

test_all_texts_should_exists(LocalisationTest): key missing for locale en: users.edit.title

Die fehlende Übersetzung können wir dann ergänzen, bevor wir eine neue Version der Anwendung veröffentlichen.

[Zu Teil 1]

Oft enthalten Webseiten Sätze, in denen sich ein einzelnes Wort sich dynamisch ändert. Beispielsweise “Sie sind als xxxx eingeloggt.” Zur Übersetzung können wir natürlich den Satz aus seinen Bestandteilen zusammenzubauen. Oft gibt es ein Problem: in verschiedenen Sprachen ist der Satzbau anders.

Besser ist deshalb die sogenannte Interpolation, wie man sie in Ruby ja kennt. Im Satz steht ein markierter Platzhalter, der zur Laufzeit ersetzt wird. Die yaml-Datei zur Spezifikation nutzt hierbei nicht die Ruby Syntax, sondern markiert die zu ersetzenden durch doppelte geschweifte Klammern. Achtung: In Rails 3 hat sich die Syntax leicht geändert.

# Definition
  logmsg: "Sie sind als {{name}} eingeloggt."
# Definition in Rails 3
  logmsg: "Sie sind als %{name} eingeloggt."
 
# Aufruf
I18n.translate(:logmsg, :name => 'Administrator')
# oder in kurz
t :logmsg, :name => 'Administrator'

Wir müssen dabei sicherstellen, das die Parameter von Definition und Aufruf übereinstimmen. Die translate()-Methode dabei relativ tolerant: Überflüssige Parameter werden ignoriert, fehlende Parameter werden mit einem “(???)” ersetzt.

Achtung: die übersetzende Person muss wissen, dass sie die Variablennamen in den Klammern nicht mit übersetzen soll!
Eine weitere kleine Falle lauert bei den Variablennamen: Sie dürfen nicht wie eine der anderen Parameter der translate()-Methode heißen. Verboten sind deshalb “default” und “scope”.

Texte der Validierungen

Selbst wenn wir unsere Applikation nur einsprachig auf deutsch erstellen, gibt es an einer Stelle eine Überraschung: bei den automatisch generierten Fehlermeldungen der Validierungen in den Model-Klassen. Sehr praktisch, aber dummerweise in Englisch. Außerdem setzen sie die Klassennamen und Attributnamen direkt ein. Die Namen der Klassen und Attribute wählen wir normalerweise nach den Bedürfnissen der Programmierer, für die Benutzer sind gelegentlich andere Vokabeln angebrachter.

Der Aufbau einer Fehlermeldung bei einer fehlgeschlagenen Validierung ist im Bild zu sehen:

Zur Anzeige auf Deutsch müssen wir die Texte nur mit den richtigen Schlüsseln in unsere yaml-Übersetzungdatei eintragen. Die Rumpfsätze sind im Bereich (scope) activerecord.messages definiert. Da diese Sätze für alle Anwendungen gleich sind, gibt es schon für viele Sprachen und auch für Deutsch schon Standardübersetzungen.

Übersetzung des Models

Die Namen der Felder und Objekte müssen wir in der yaml-Datei im Bereich activerecord.models.classname beziehungsweise activerecord.attributs.classname.attributname definieren. Dann erkennt sie Rails und setzt sie korrekt in die automatischen Validierungsmeldungen ein.
Die zentrale Übersetzung der Klassennamen und Feldernamen ist auch für die Views interessant. So brauchen wir die Labels von Eingabefeldern nicht ein zweites oder drittes mal übersetzen.

activerecord:
  models:
    term: "Begriff"
  attributes:
    term:
      name: "Name"
      topic: "Sachgebiet"

Das macht für die Views nicht immer Sinn. Die Benutzerschnittstelle sollte sich nicht zu eng an das Model halten. Wichtig ist ja schliesslich der Benutzer.

Validierungen mit eigenen Meldungen

Ein typischer Anwendungsfall für eine eigene Meldung ist die Überprüfung einer Telefonnummer. Die Methoden zur Spezifikation der Validierungen haben einen Parameter “message”. Damit sollte eine Übersetzung ja kein Problem sein: Wir sollten einfach hier die t()-Methode aufrufen können. Leider klappt es so nicht:

# funktioniert so nicht! Does not work!
validates_format_of( :fax,{
    :with => /\A[0-9 \+\-\/\(\)]+\Z/i,
    :message => t('activerecord.errors.messages.bad_phone'),
    :allow_blank => true})

Je nach Version und des verwendeten Deployments startet Rails gar nicht erst hoch oder liefert die gewünschte Übersetzung nicht. Was läuft schief?

Die Sprache ist ja immer pro Request gesetzt. Bei der Definition der deklarativen Valdierungen im Model gibt es noch gar keinen Request! Es macht deshalb keinen Sinn zu diesen Zeitpunkt die translate-Methode aufzurufen.

Aber wie lösen wir das Problem? Typisch für Rails ist die Lösung schon eingebaut. Wenn man sie nicht kennt, kann man sich allerdings lange im Kreis drehen.
Wir können dem message – Parameter nämlich auch ein Symbol statt eines Strings mitgeben: das Symbol wird erst ausgewertet, wenn die Fehlermeldung angezeigt werden soll. Das Symbol wird nacheinander in diesen speziellen Kontexten (scope) ausgewertet:

• activerecord.errors.models.[model_name].attributes.[attribute_name]
• activerecord.errors.models.[model_name]
• activerecord.errors.messages

Unsere Validierung können wir demnach einfach so schreiben:

validates_format_of( :fax,{
    :with => /\A[0-9 \+\-\/\(\)]+\Z/i,
    :message => :bad_phone,
    :allow_blank => true})

Quellen:

Beschreibung (Guide) der Internationalization API:
guides.rubyonrails.org/i18n.html

Sprachdateien für Standardübersetzungen:
github.com/svenfuchs/rails-i18n/tree/master/rails/locale

Zu Teil 3 dieses Artikels

Software in mehreren Sprachen anzubieten ist eine immer wiederkehrende Aufgabenstellung. Um so erstaunlicher ist es, dass Ruby on Rails erst sehr spät hierfür ein standardisiertes Vorgehen eingeführt hat. Seit Version 2.2. ist eine “Internationalization API” Bestandteil von Ruby on Rails.

Struktur des Frameworks

Das Framework besteht aus einen “öffentlichen” und einen “privaten” Teil. Das I18N Modul bildet den öffentlichen Teil mit den Methoden, die wir in unserem Quelltext aufrufen.

Das private Backend ist austauschbar. Die Standardversion liest die Texte aus Dateien in Yaml-Format oder aus normalen Rubydateien ein.

Aufruf

In unserem Quelltext ersetzen wir alle zu übersetzenden Texte durch Aufrufe der I18N.translate() Methode. Dank eines Alias können wir auch einfach t() schreiben. Als Parameter übergeben wir einen Schlüssel, mit dem das Backend die richtige Übersetzung nachschlägt.

Der Schlüssel kann einen String oder ein Symbol sein. Normalerweise ist ein Symbol als Hashkey ja geringfügig performanter. Da der Schlüssel bei der Verarbeitung in seine Bestandteile zerlegt wird, erwarte ich, dass dieser Vorteil verschwindet.

In einer typischen Webapplikation sind viele der zu übersetzenden Texte in den Views, also den .erb-Templates. Als Abkürzung für reinen HTML-Text gibt es folgenden Tag:

<%=t 'key' %>

Organisation

Die Symbole haben eine hierarchische Struktur. Als Organisation bietet sich an:

“controllername.viewname.key”, also zum Beispiel ‘companies.show.header’

Die Sprachdateien

Als Formate der Sprachdatei sind Ruby-Quelltext und Yaml vorgesehen. Die Übersetzung wird nun meistens von einer Person ohne Rubykenntnisse durchgeführt. Deshalb ist die Yaml-Datei zu empfehlen.

Das Format sieht so aus

de:
  users:
    show:
      header: "Unternehmensdaten"
      intro: "Für dieses Unternehmen sind die folgenden Daten gespeichert:"

Die Sprache ist der erste Key, normalerweise sind dadurch die Texte der verschiedenen Sprachen räumlich getrennt. Um die Arbeit für die Übersetzer zu erleichtern, können mit einem ‘#’ Zeichen Kommentare eingefügt werden. Und natürlich sollten die bezeichnenden Schlüsselwerte möglichst klar sein. Aber selbst dann sind die YAML-Dateien nicht optimal, wenn Entwickler und Übersetzer nicht dieselbe Person ist.

Zu Teil 2 dieses Artikels