Internationalizing GUI Files

TODO

Internationalizing JavaScript Files

Internationalizing Strings in JavaScript

To internationalize a string in a 0 A.D. JavaScript file, simply use the following global functions:

translate(message);
translatePlural(singularMessage, pluralMessage, number);
translateWithContext(context, message);
translatePluralWithContext(context, singularMessage, pluralMessage, number);

These functions return the specified message translated into the current language. If that language is the source language or if there is no translation for the specified message, these functions return the specified message.

Using Plural Functions

Plural functions require that you pass them two versions of the same message: a message in singular form (number = 1) and a message in plural form (number != 1). This is because those are the English plural forms. However, other languages may have more plural forms or no plural forms at all. That is why you must specify an integer, number, that is the number of items represented in your message.

Using Context Functions

Context functions are used to handle cases where an English string may have a different meaning depending on the context. When that happens, chances are other languages use different words for each one of those meanings. If you use a context-free internationalization function (translate or translatePlural) to translate two messages that contain the same text, when you generate a translation template (POT file) from the sources, both messages are treated as a single message, and translators can only translate the message one way or another. If instead you use a context function (translateWithContext or translatePluralWithContext) and specify a different context for each message, translators will be able to translate each message differently.

The context string can be any short English string. The following is a real-life example, extracted from the game sources:

translateWithContext("map size", "Any");
translateWithContext("player number", "Any")

Usually, you do not need to worry about whether or not a string needs a context. You can always use a context-free internationalization function, and if a context is necessary for one or more languages to properly translate the message, translators will let you know, and you can then switch to a context function.

However, you might want to be alert for the following cases that might need a context:

• Single words. When you translate a single word, you are likely to need a context.
• Unclear verb tenses or nouns. More often than not, the same English word may represent two or more different tenses of a verb, and also work as a noun or other type of word. If the message string is not clear enough as to which of those tenses is being used or whether the word is working as a verb or as a different type of word, you need a context.

Using Format Strings Instead of Concatenating Strings in JavaScript

TODO: sprintf.

Internationalizing Data Files (JSON, TXT, XML)

Internationalizing strings from data files that are loaded by JavaScript files is a two-step process. You must:

1. Configure the message extraction system to extract the translatable strings from the data file.
2. Use an internationalization function on the JavaScript side after you load the data file.

Configuring the Message Extraction System for Data Files

Our message extraction system currently supports extracting data strings from:

• Plain text files (.txt). The content of plain text files can be extracted line by line. Paragraphs in these plain text files should not contain line breaks, otherwise each line is extracted as a separate message, which is not translator-friendly.
• JSON files. You can extract strings associated with a specific key or keys of any object in a given JSON file.
• XML files, where you can extract:
  • The content of specific elements (start and end tags). Currently, however, you cannot extract the value of an attribute of an XML element. For example, in <PropertyName AttributeName="AttributeValue>PropertyValue</PropertyName> you can extract "PropertyValue" but you cannot extract "AttributeValue".
  • Strings from JSON data defined within an XML element.

To configure the message extraction system to extract strings from a new data file, you must edit the l10n/messages.json file of the mod folder. In the messages.json file of the main mod, public, you can find examples of all the supported types of data extraction. For more information, see the message extraction system documentation.

Internationalizing Content that JavaScript Files Load from Data Files

Once the message extraction system is properly configured to extract the translatable strings from a data file, translators will be able to translate those strings. But for those translations to be actually used, you must internationalize the JavaScript that loads or uses the data to translate the loaded data at run time.

If the JavaScript file obtains the data as a string, you can simply pass a variable that contains the translatable string to a global internationalization function such as translate() or translateWithContext(). If the JavaScript file obtains the data as an object, you can use the translateObjectKeys() global function instead, which expects the object with the data and an array with the names of the object properties that must be translated. For example, from the game code:

translateObjectKeys(settings.ais, ["name", "description"]);