Help:Extension:Translate/File format support/de

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:


 * : Setter für den Dateinamen.
 * : Getter für den Dateinamen.
 * : Liest die Nachrichten aus der Datei und analysiert sie.
 * : 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.
 * : Schreibt die Nachrichten in die Datei.
 * : Schreibt die Nachrichten in eine Zeichenketten-Variable, die das gleiche Format wie die Datei hat. Hier wird die ausgegebene Nachrichtendatei erstellt.

MediaWiki translations
Classes for storing MediaWiki translations are not currently handled by FFS interface derivatives, but by autonomous classes: there are configuration instructions. New FFS-like classes are being developed.

class SimpleFFS
The class SimpleFFS is the ancestor of all the other FFS classes, and it is also a simple example of how an FFS class should be written. It implements a simplistic key-based format:


 * each file has two sections, separated by "\0\0\0\0";
 * one section has the translators' names separated by "\0";
 * the other has the translations in "key=value" format, also separated by "\0".

Since SimpleFFS is intentionally simplistic, it demonstrates possible bugs and complications. For example, the "=" character is not escaped, so the key and the value may not contain them. Obviously, this is not something that is suitable for real-world programs. SimpleFFS also implements useful utility methods:


 * : Tests whether the file exists.
 * : Implements internals of file format writing, apart from the more generic writeIntoVariable.
 * : Filter some defined authors from the file according to a custom blacklist. This is useful for filtering usernames of bots, developers and translation administrators, for example.
 * : Fix all line endings to Unix-style.

Writing new FFS classes
All the above SimpleFFS methods can be overridden. Most implementations, however, only need to implement  and.

General tips when writing new classes:


 * Avoid executing executable file formats. Parse them.
 * Remember to mangle and unmangle message keys.
 * Do not assume message keys don't include problematic characters. They will.
 * The output is usually expected to be pretty and readable. Some people like to poke in them manually.
 * Most formats don't support fuzzy markers, some add them as comments on export only and ignore them on import.

Supported file formats
The existing FFS classes are:


 * AndroidXml – for use in Android apps
 * AppleFFS – for iOS/Mac OS X Localizable.strings
 * Dtd – for DTD-based projects, like Okawix and Mozilla.
 * FlatPhpFFS – for future use in MediaWiki
 * Gettext – for Gettext-based projects
 * Ini – for INI-based projects
 * JavaScript – for all JavaScript formatted files
 * Java properties – for *.properties files, used in some Java and JavaScript projects, often along with Dtd
 * Json – used in jquery.i18n based projects, such as the portable Universal Language Selector library
 * Yaml – used in Waymarked Trails
 * Ruby (Yaml) – used in OpenStreetMap and Shapado
 * AMD i18n bundle

Examples of Translate exports in those formats are available at translatewiki.net.



Mangling the message keys to ensure correct title handling
The Translate extension is MediaWiki-based and every message is stored as a MediaWiki page, so the key must be a valid MediaWiki page title. Mangling takes care of this by escaping the key names a manner similar to the quoted-printable encoding, but with some modifications before storing the message as a wiki page. Before the message is written back to the file, the message is unmangled.

When an FFS class overrides the functions that call the mangling routines, it must make sure the roundtrip is done correctly – that is, that the key is mangled before writing to MediaWiki and unmangled before writing the translation back to the file.

Mangling is done in the  class.

Testing FFS classes
If you create a new FFS class, create a corresponding testing file in the tests directory. The important things to test are:


 * Parsing of the format: Essentially testing that the  function returns the right keys and values for AUTHORS and MESSAGES.
 * Roundtrip: Test that the keys and the messages are written and read correctly.

You can use existing test routines, such as JavaFFSTest, as examples.