Hilfe:Erweiterung:Übersetzen/Dateiformatunterstützung

This page is a translated version of the page Help:Extension:Translate/File format support and the translation is 100% complete.
Other languages:

FFS steht für Dateiformatunterstützung (englisch file format support). Dies ist der allgemeine Name für eine Gruppe von Klassen für das Lesen und Bearbeiten übersetzter Nachrichten in verschiedenen Dateiformaten in der Übersetzungserweiterung.

Softwareentwickler haben mit Lokalisierungstechnologien das Rad viele Male neu erfunden, sodass es viele unterschiedliche Formate zum Speichern übersetzbarer Softwarenachrichten gibt. Es gibt zwei Hauptgruppen dieser Formate.

  • Schlüsselbasierte Formate: jede Nachricht hat einen Schlüssel, bei dem es sich um eine mehr oder weniger bedeutungsvolle Zeichenkette handelt. Die Übersetzung in jede Sprache ist ein Plan von Schlüsseln, die auf Werte verweisen. Die meisten Formate fallen in diese Gruppe, darunter DTD, JSON und das bis 2014 verwendete alte MediaWiki-Format (im Wesentlichen ein PHP-Array).
  • Gettextähnlich: Die Nachricht in der Originalsprache des Programms, normalerweise Englisch, wird selbst als Schlüssel genutzt, der auf Übersetzungen in andere Sprachen verweist. Dies erfordert die Erstellung inhärenter nicht-stabiler Pseudoschlüssel für das Speichern der Nachrichten in einem anderen Format.

Einführung in die FFS-Klassen

Bis auf einige Ausnahmen leiten sich die meisten FFS-Klassen von der FFS-Oberfläche ab, die die grundlegenden Methoden definiert, die jede Klasse implementieren muss:

setWritePath( $target )
Setter für den Dateinamen.
getWritePath()
Getter für den Dateinamen.
read( $code )
Liest die Nachrichten aus der Datei und analysiert sie.
readFromVariable( $data )
Liest die Nachrichten aus einer Zeichenketten-Variable, die das gleiche Format wie die Datei hat und sie als Array aus AUTHORS (Autoren) und MESSAGES (Nachrichten) ausgibt.
write( MessageCollection $collection )
Schreibt die Nachrichten in die Datei.
writeIntoVariable( MessageCollection $collection )
Schreibt die Nachrichten in eine Zeichenketten-Variable, die das gleiche Format wie die Datei hat. Hier wird die ausgegebene Nachrichtendatei erstellt.

MediaWiki-Übersetzungen

Klassen zum Speichern von MediaWiki-Übersetzungen werden derzeit nicht von Varianten der FFS-Oberfläche verwaltet, sondern über unabhängige Klassen: es gibt Konfigurationsanweisungen. Neue FFS-ähnliche Klassen werden entwickelt.

SimpleFFS-Klasse

Die Klasse SimpleFFS ist der Ursprung aller FFS-Klassen und ein einfaches Beispiel dafür, wie eine FFS-Klasse geschrieben werden sollte. Sie implementiert ein vereinfachtes schlüsselbasiertes Format:

  • jede Datei besteht aus zwei Abschnitten, getrennt durch "\0\0\0\0";
  • ein Abschnitt enthält die Namen der Übersetzer, getrennt durch "\0";
  • der andere enthält die Übersetzungen im Format "key=value", ebenfalls getrennt durch "\0".

Da SimpleFFS bewusst einfach gehalten ist, ist es für Fehler und Komplikationen anfällig. So wird das Zeichen "=" nicht maskiert, sodass der Schlüssel und der Wert es nicht enthalten dürfen. Das eignet sich für Programme der realen Welt offensichtlich nicht. SimpleFFS implementiert auch einige nützliche Werkzeuge:

exists( $code )
Überprüft, ob die Datei existiert.
writeReal( $collection )
Implementiert abgesehen von der generischen writeIntoVariable Einsetzelemente für das Schreiben in dem Dateiformat.
filterAuthors
Filtert nach einer benutzerdefinierten Blacklist bestimmte Autoren aus der Datei. Dies ist nützlich, um beispielsweise die Benutzernamen von Bots, Entwicklern und Übersetzungsadministratoren herauszufiltern.
fixNewLines( $data )
Repariert alle Zeilenenden im Unix-Stil.

Schreiben neuer FFS-Klassen

Alle oben angegebenen SimpleFFS-Methoden können überschrieben werden. Die meisten Implementierungen müssen jedoch nur writeIntoVariable und readFromVariable implementieren.

Allgemeine Hinweise zum Schreiben neuer Klassen:

  • Vermeide es, ausführbare Dateiformate auszuführen. Parse sie.
  • Denke daran, Nachrichtenschlüssel zu zerlegen und wiederherzustellen.
  • Nimm nicht an, dass Nachrichtenschlüssel keine problematischen Zeichen enthalten. Sie werden es.
  • Die Ausgabe sollte schön und lesbar sein. Manche Menschen geben sie gerne manuell ein.
  • Die meisten Formate unterstützen keine Fuzzy-Markierungen, einige fügen sie nur als Kommentare beim Export hinzu und ignorieren sie beim Import.

Unterstützte Dateiformate

Die existierenden FFS-Klassen sind:

  • AndroidXml – zur Nutzung in Android-Apps
  • AppleFFS – für iOS/Mac OS X Localizable.strings
  • Dtd – für DTD-basierte Projekte wie Okawix und Mozilla.
  • FlatPhpFFS – zur zukünftigen Nutzung in MediaWiki
  • Gettext – für Gettext-basierte Projekte
  • Ini – für INI-basierte Projekte
  • JavaScript – für alle nach dem JavaScript formatierten Dateien
  • Java properties – für *.properties-Dateien, genutzt in einigen Java- und JavaScript-Projekten, häufig zusammen mit Dtd
  • Json – genutzt in jquery.i18n-basierten Projekten wie der portablen Universal-Language-Selector-Bibliothek
  • Yaml – genutzt in Waymarked Trails
  • Ruby (Yaml) – genutzt in OpenStreetMap und Shapado
  • AMD i18n-Bundle

Beispiele von Übersetzungsexporten in diese Formate sind verfügbar auf translatewiki.net.

 
Hierarchie der FFS-Klassen

Zerlegen der Nachrichtenschlüssel, um die korrekte Verarbeitung des Titels sicherzustellen

Die Übersetzungserweiterung basiert auf MediaWiki, weshalb jede Nachricht als MediaWiki-Seite gespeichert wird, wofür wiederum der Schlüssel ein gültiger MediaWiki-Seitentitel sein muss. Das Zerlegen stellt dies sicher, indem der Schlüsselname in etwa wie bei der Quoted-Printable-Kodierung maskiert wird, wobei vor der Speicherung der Nachricht als Wiki-Seite einige Veränderungen vorgenommen werden. Bevor die Nachricht wieder zurück in die Datei geschrieben wird, wird die Nachricht wieder zusammengesetzt.

Wenn eine FFS-Klasse die Funktion für diesen Mechanismus überschreibt, muss sichergestellt werden, dass die Umwandlungen korrekt erfolgen – das bedeutet, dass der Schlüssel zerlegt wird, bevor er in MediaWiki gespeichert wird und wieder zusammengesetzt wird, bevor die Übersetzung zurück in die Datei geschrieben wird.

Das Zerlegen erfolgt über die Klasse StringMatcher.

Testen von FFS-Klassen

Erstelle eine entsprechende Testdatei im Testverzeichnis, wenn du eine neue FFS-Klasse erstellt hast. Wichtige Dinge, die zu testen sind, sind:

  • Parsen des Formats: Insbesondere testen, dass die Funktion readFromVariable die richtigen Schlüssel und Werte für AUTHORS (Autoren) und MESSAGES (Nachrichten) ausgibt.
  • Umwandlung: Testen, ob die Schlüssel und die Nachrichten korrekt geschrieben und gelesen werden.

Du kannst vorhandene Test-Routinen wie beispielsweise JavaFFSTest nutzen.