Localization

Localization Requirements

Before you begin work localizing X-Plane, please understand these requirements! We do not want you to spend a lot of time localizing and then realize there is a problem.

• LR may not use your translations. We will try to use any translation we get, or notify you early on if we cannot, but we cannot guarantee that your translation will go into X-Plane.
• We cannot delay releases for translations; if a string changes and we must cut an RC and you cannot translate the string, the string may go un-translated.
• LR must own the IP of all translations (which are derived works of X-Plane itself). We cannot accept translations with “strings attached”.
• If more than one person is working on a language, you must cooperate with the other team members!

Overall Localization Strategy

The 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/<language>.txt, where language is the localized language name, e.g. French or German.

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 <language>.txt will be in the folder Contents/Resources. On Linux and Windows, developer tools are needed to embed or replace the dictionary file, so we 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<space><english>====<localized>

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:

%<number>:<comment>%

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.

Back to Knowledge Base