Translation File Format

Version 1.9.11 and Later

New XMB translation files are always parsed (but not executed) by PHP using the eval() function. This means the following formatting rules are required:

• PHP tags are optional.
• No data outside the tags is tolerated because XMB will remove the tags before calling eval().
• Whitespace outside the tags is okay because it will be treated as being inside the tags.
• Everything in the file must abide by PHP syntax.

To be valid, the translation file must specify its own name using the $devname variable. For example:

$devname = 'French';

This name must not contain any special characters. It is used by developers to identify the translation inside XMB. It does not have to be any particular value. Typically it will be the name of the language written in English, plus any distinguishing information for alternates.

Translation meta data should be sorted to the top of the file. The meta data are descriptive information for the translation, not the information that has been translated. Three new keys should always be included in these meta data: 'charset', 'iso639', and 'language'.

'charset' explicitly specifies which character encoding has been used to save the translation file. This value will also determine which character encoding is used to save the forum posts submitted by members using this translation.

'iso639' is a two-letter or three-letter standard code that uniquely identifies languages. This code does not have to be unique among translations.

'language' is the untranslated name of the language as it is written natively. This value must be encoded in lower ASCII characters only. If the language name cannot be written natively using lower ASCII, then it must be encoded as standard HTML character entity references.

For example, a translation in French should include this near the top of the file:

$lang['charset'] = 'ISO-8859-1';
$lang['iso639'] = 'fr';
$lang['language'] = 'Français';

Because the files are being parsed by a custom script, the following additional rules have been set:

• Each valid statement will consist of exactly one line of text.
• Any statement that does not conform to the following rules will be ignored.
• Line endings may be Windows-style (CRLF) or Linux-style (LF)
• Each statement must begin with a single variable name, followed by a single space.
• The equal sign is the only operator allowed.
• The operator must be followed by one space, one string literal, one semi-colon, and a line ending.
• The only string escape sequences are \\, \', \", \$, and \n.
• Variables inside string literals will not be parsed.
• Associative array indexes must be single-quoted.

For example:

$lang['textnewu2ubody'] = "has sent you a new U2U.\nTo stop receiving these notifications, please login\n\n";

A value should be set for all translation keys used throughout XMB. The absence of any one $lang key can cause undefined behavior in XMB.

Version 1.9.10 and Earlier

Original XMB translation files were always executed by PHP using the require() function. This means the following formatting rules were required:

• PHP tags must be present. The file must start with <?php and end with ?>
• No data or whitespace outside the tags is tolerated because it interferes with HTTP headers.
• Everything inside the tags must abide by PHP syntax.

The character encoding of the file itself must be explicitly specified by setting a global variable called $charset. For example:

$charset = 'ISO-8859-1';

A value should be set for all translation keys used throughout XMB. For example:

$lang['avatar_too_big'] = "Your avatar is too big! The maximum allowed avatar size on this board is: ";

The absence of any one $lang key can cause undefined behavior in XMB.