Localizing X-Plane

This document explains the new next-generation localization scheme for X-Plane. This system is not yet available; it is expected to be available in:
 * The installer, version 2.04.
 * X-Plane, version 9.20.

X-Plane 9.0 ships with a localization scheme similar to X-Plane 8. The installer version 2.03 and older cannot be localized.

= Overall Localization Strategy =

The new localization system uses key-string matching; for each language, a dictionary text file maps English phrases to phrases in a localized language.

(This differs from the old localization system used for all of v8, which maps numbers to strings in either English or a localized language; in the old system to know what string 511 was supposed to be, you had to check the English.)

There is one dictionary file per language per file.

= Dictionary File Format =

File Location
Dictionary files are stored in Resources/text/ / 2.txt, where language is the localized language name, e.g. French or German, and the application is one of X-Plane, Plane-Maker, Briefer, or Airfoil-Maker.

Installer Special Handling
Because the installer does not use a Resources folder, the localization files are embedded in the application. You can view and replace the string file for the Macintosh installer by picking "show package contents" - a dictionary of the name .txt will be in the folder Contents/Resources. On Linux and Windows, developer tools are needed to embed or replace the dictionary file, so I recommend working on the Mac when localizing the installer.

Character Sets and File Encoding
Dictionary files should be encoded in UTF8 with no byte order marker (BOM). Use any unicode character from the following standard unicode ranges (excluding unprintable/control characters):
 * Basic Latin (0x00-0x7F)
 * Latin-1 Supplement (0x80-0xFF)
 * Latin Extended-A (0x100-0x17F)
 * Latin Extended-B (0x180-0x1FF)
 * Cyrillic (0x400-0x4FF)

Text files should use Unix line endings.

= Dictionary Syntax =

Header
The header for a dictionary file is: A 900 TRANSLATION

Records
Following the header are a series of records, one per line.

A line starting with a # file is a comment.

A line starting with the token STRING followed by at least one space defines a string key pair. The format of the key pair is:

STRING ====

For example:

STRING Check Disk Space====Festplattenplatz prüfen

Warning: spacing is very important when making string macros. One space after the word STRING is consumed in parsing; all other spaces are part of the strings. Examples of consistent spacing:

STRING Check Disk Space====Festplattenplatz prüfen STRING Check Disk Space==== Festplattenplatz prüfen STRING Check Disk Space ====Festplattenplatz prüfen STRING Check Disk Space ==== Festplattenplatz prüfen

Note that in the last two options there is a trailing space after the word prüfen but before the newline. These examples have inconsistent spacing:

STRING Check Disk Space====Festplattenplatz prüfen STRING Check Disk Space==== Festplattenplatz prüfen

Substitution System
When X-Plane must substitute a word into a string, it does so using a parameter. Parameters take the form of: % : % where number is a positive integer. The number dictates which parameter will be substituted. There can be more than one parameter per phrase.

The comment is a word describing roughly what will go into the parameter; it is not used by X-Plane (in either the English or translated string) but is simply designed to provide context when translating. For example:

STRING There was a problem with %1%====...

could be almost impossible to translate. But

STRING There was a problem with %1:file name%====....

provides a hint. You can change the order of parameters, and you can change the comment in the translated version, but you cannot change the name of the comment in the English side or X-Plane will not locate the string. Example:

STRING There was an error opening %1:filename% - %2:message%====The operating system said "%2:msg%" when we tried to open %1:file%.

Note in this example that the comments have been slightly renamed and the parameter order switched, but the message still goes into parameter 2, and the file name into parameter 1.

Substitution and Plurals
When X-Plane has a phrase that might vary with plural (e.g. one error vs. two errors) there will be two strings in the translation file:

STRING There was %1:count% error while installing.==== STRING There were %2:count% errors while installing.====

These plurals will almost always be adjacent (see extracts below). The sim will correctly pick the right plural taking into account language-specific rules about singular-plural. (Note that X-Plane cannot yet handle languages where there are more than two cases for singular/plural.

= String Extracts =

If you want to localize X-Plane, your best bet is to get a string extract from Laminar Research. This is a dictionary containing all of the English phrases in the sim and it related applications.

Extracts follow the standard dictionary format and come in two basic flavors:

Unsorted Extracts
Unsorted extracts contain each string once, in the order they appear in the code, with plurals always immediately following singulars, and translation comments in place. (These are comments from programmers to translators indicating the use of a string). By being in code-order, unsorted extracts tend to mostly put related strings in one place, e.g. all of the web updater strings will be in a cluster.

An unsorted extract is the best basis for translating.

Sorted Extracts
A sorted extract sorts the file in alphabetical order and removes comments; the sorted extract can easily be "diffed" against an older sorted extract to rapidly identify all changed strings. Use these extracts only to determine what has changed since a past extract.

= Command Line Options and Log =

Always check the log file when translating; errors in your translation files will be flagged!

You can use the command-line option: --missing_strings

to cause X-Plane to output a STRING ==== line once for every missing string in your translation. This is a good way to build dictionary entries for missing strings.