Help:Extension:Translate/File format support/ja

略語 FFS は file format support を指します. 翻訳拡張機能を使い、さまざまなファイル形式の翻訳済メッセージを読み書きするクラスの群を、一般に FFS と呼びます.

地域化技術の輪はソフトウェア開発者の手で何度も革新され、結果として翻訳対象のソフトウェアのメッセージにいくつもの保存形式が存在します. 主に2グループに分類できます.


 * キーベース形式. メッセージ単位でキーを与え、だいたいは意味のある文字列を当ててあります. 多言語への翻訳は値とキーのマッピングで示します.   DTD、JSON、MediaWiki 独自の形式 (根本的には PHP 配列array) など、大多数の形式はこのグループに分類されます.
 * Gettext 型. プログラムの翻訳元は通常は英語で、英語自体が他言語の翻訳結果へのキーとなります. その実現には異なる形式でメッセージを保存するため、変動型の固有の偽キーを生成する必要があります.

Introduction to the FFS classes
With some exceptions, most FFS class derive from the FFS interface, which defines the basic methods every class must implement:


 * : Setter for the file name.
 * : Getter for the file name.
 * : Read the messages from the file and parse it.
 * : Read the messages from a string variable that has the same format as the file and return them as an array of AUTHORS and MESSAGES. This is where the actual parsing of the file's text is supposed to happen.
 * : Write the messages to the file.
 * : Write the messages to a string variable that has the same format as the file. This is where the careful construction of the resulting messages file is supposed to happen.

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.

FFS クラスをテストする
新しい FFS クラスを作成するたび、テスト用ディレクトリ内に対応するテスト用ファイルを作成してください. 重要なテストの要素は次の通りです.


 * 形式のパーシング. 基本的に 関数から AUTHORS と MESSAGES に対する正しいキーと値が返ってくるか、テストします.
 * Roundtrip: キーとメッセージの記述が正しく読み書きできるかどうかテストします.

例えば既存のテスト用ルーチンとして JavaFFSTest を使ってください.