| 4 | | = Internationalization = |
| 5 | | … |
| 6 | | |
| 7 | | == Internationalizing Strings in !JavaScript == |
| 8 | | To internationalize a string in a 0 A.D. !JavaScript file, simply use the following global functions: |
| 9 | | |
| 10 | | {{{ |
| 11 | | translate(message); |
| 12 | | translatePlural(singularMessage, pluralMessage, number); |
| 13 | | translateWithContext(context, message); |
| 14 | | translatePluralWithContext(context, singularMessage, pluralMessage, number); |
| 15 | | }}} |
| 16 | | 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. |
| 17 | | |
| 18 | | === Using Plural Functions === |
| 19 | | 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. |
| 20 | | |
| 21 | | === Using Context Functions === |
| 22 | | 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. |
| 23 | | |
| 24 | | The context string can be any short English string. The following is a real-life example, extracted from the game sources: |
| 25 | | |
| 26 | | {{{ |
| 27 | | translateWithContext("map size", "Any"); |
| 28 | | translateWithContext("player number", "Any") |
| 29 | | |
| 30 | | }}} |
| 31 | | 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. |
| 32 | | |
| 33 | | However, you might want to be alert for the following cases that might need a context: |
| 34 | | |
| 35 | | * '''Single words'''. When you translate a single word, you are likely to need a context. |
| 36 | | * '''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. |
| 37 | | |
| 38 | | === Using Format Strings Instead of Concatenating Strings in !JavaScript === |
| 39 | | TODO: sprintf. |
| 40 | | |
| 41 | | == Internationalizing Objects == |
| 42 | | TODO: translateObjectKeys |
| 43 | | |
| 44 | | = Implementation Details = |
| 45 | | In the `globalscripts` folder of the `public` mod folder you can find the following two scripts: `l10n.js` and `sprintf.js`. |
| 46 | | |
| 47 | | `l10n.js` implements the following global internationalization functions: |
| 48 | | |
| 49 | | {{{ |
| 50 | | translate(message); |
| 51 | | translatePlural(singularMessage, pluralMessage, number); |
| 52 | | translateWithContext(context, message); |
| 53 | | translatePluralWithContext(context, singularMessage, pluralMessage, number); |
| 54 | | translateObjectKeys(object, keys); |
| 55 | | |
| 56 | | }}} |
| 57 | | The first four functions are simply wrappers for the engine internationalization functions (such as `Engine.translate`). These global functions use caching to reduce the number of calls to the engine functions, because calls to engine functions require string conversions that are far from cheap. |
| 58 | | |
| 59 | | `translateObjectKeys` is a helper function that can translate specific properties (`keys` array) of a !JavaScript object. |
| | 3 | = Topics = |
| | 4 | * [wiki:Localization], for translators. How to localize the game: translate texts, localize images, etc. |
| | 5 | * [wiki:Internationalization], for developers. How to make it possible to localize game content. |
| | 6 | * [wiki:Implementation_of_Internationalization_and_Localization Implementation of Internationalization and Localization], for internationalization developers. Implementation details to help you find your way around our internationalization and localization implementation, to fix bugs, implement new features on top of our existing functionality, or simply understand it better. |
