Changes between Version 8 and Version 9 of Implementation_of_Internationalization_and_Localization


Ignore:
Timestamp:
Apr 19, 2014, 10:31:58 AM (10 years ago)
Author:
Adrián Chaves
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • Implementation_of_Internationalization_and_Localization

    v8 v9  
    44
    55= Internationalization =
    6 
    76== Third-Party Libraries ==
    8 
    97The internationalization and localization implementation fo the game relies on two libraries:
    108
    11 * '''[http://site.icu-project.org/ ICU]''' is a common internationalization library that provides structures to handle locales, easily obtain the default system locale, handle date and number representations on each locale, or provide the localized names of locales to show them in a language combo box.
     9 * '''[http://site.icu-project.org/ ICU]''' is a common internationalization library that provides structures to handle locales, easily obtain the default system locale, handle date and number representations on each locale, or provide the localized names of locales to show them in a language combo box.
    1210
    13 * '''[http://code.google.com/p/tinygettext tinygettext]''' is a small library that we forked. This library provides the structures and methods that we use to load PO files in memory.
     11 * '''[http://code.google.com/p/tinygettext tinygettext]''' is a small library that we forked. This library provides the structures and methods that we use to load PO files in memory.
    1412
    1513== The Localization Singleton ==
    16 
    1714The heart of the internationalization and localization implementation is at `source/i18n/L10n.cpp`.
    1815
    … …  
    2219
    2320=== Initialization ===
    24 
    2521When you call the singleton for the first time, its initialization:
    2622
    27     1. Creates a list of available locales based on the filenames of the PO files in the `l10n` virtual folder.
     23 1. Creates a list of available locales based on the filenames of the PO files in the `l10n` virtual folder.
    2824
    29         The `l10n` virtual folder holds the combination of the files in the `binaries/data/l10n` folder, which contains the engine PO files, and the `l10n` folder of each enabled mod. See `source/ps/GameSetup/GameSetup.cpp`.
     25  The `l10n`  virtual folder holds the combination of the files in the `binaries/data/l10n`  folder, which contains the engine PO files, and the `l10n`  folder of each enabled mod. See `source/ps/GameSetup/GameSetup.cpp` .
    3026
    31         You can obtain the list of available locales calculated here at any later time calling `L10n::Instance().GetSupportedLocaleCodes()`. This method returns an array of strings with the locale codes found here. `L10n::Instance().GetSupportedLocaleDisplayNames()` returns a similar vector, this one with display names instead of codes, where the name of each locale is in the language of the locale itself. The special locale "Long Strings", of code "long", is only returned if yours is a development copy (if the `config/dev.cfg` file exists in the virtual filesystem).
     27  You can obtain the list of available locales calculated here at any later time calling `L10n::Instance().GetSupportedLocaleCodes()` . This method returns an array of strings with the locale codes found here. `L10n::Instance().GetSupportedLocaleDisplayNames()`  returns a similar vector, this one with display names instead of codes, where the name of each locale is in the language of the locale itself. The special locale "Long Strings", of code "long", is only returned if yours is a development copy (if the `config/dev.cfg` file exists in the virtual filesystem).
    3228
    33     2. Determines the current locale, first looking at the configuration value `locale` and, if undefined, looking at the system locale using [http://www.icu-project.org/apiref/icu4c/classicu_1_1Locale.html#a020c6966493a8f00572616b64b5527c3 icu::Locale::getDefault()].
     29 2. Determines the current locale, first looking at the configuration value `locale` and, if undefined, looking at the system locale using [http://www.icu-project.org/apiref/icu4c/classicu_1_1Locale.html#a020c6966493a8f00572616b64b5527c3 icu::Locale::getDefault()].
    3430
    35         Once the locale is defined, it loads the dictionary of the target locale if it is available. The dictionary is a structure from the tinygettext library that holds the list of English strings linked to translated strings (including context and plural considerations).
     31  Once the locale is defined, it loads the dictionary of the target locale if it is available. The dictionary is a structure from the tinygettext library that holds the list of English strings linked to translated strings (including context and plural considerations).
    3632
    37         You can change the locale later using `L10n::Instance().SetLocale()`. You can pass this method either a locale code as a string, such as "en_GB", or an instance of [http://www.icu-project.org/apiref/icu4c/classicu_1_1Locale.html icu::Locale]. The method reloads the dictionary if required.
     33  You can change the locale later using `L10n::Instance().SetLocale()` . You can pass this method either a locale code as a string, such as "en_GB", or an instance of [http://www.icu-project.org/apiref/icu4c/classicu_1_1Locale.html icu::Locale] . The method reloads the dictionary if required.
    3834
    3935=== Localization Functions ===
    40 
    4136The `L10n` singleton provides many localization functions that you can use from C++, some of which are also published to be used in JavaScript.
    4237
    4338Translation functions ([wiki:Internationalization] explains how to use them):
     39
    4440{{{
    4541std::string Translate(const std::string& sourceString);
    … …  
    4945std::string TranslateLines(const std::string& sourceString);
    5046}}}
     47Date and time functions:
    5148
    52 Date and time functions:
    5349{{{
    5450// parseDateTime() and localizeDateTime() are used to convert dates from strings
    … …  
    6359std::string FormatMillisecondsIntoDateString(int milliseconds, const std::string& formatString);
    6460}}}
     61Number functions:
    6562
    66 Number functions:
    6763{{{
    6864// Returns the specified floating-point number as a string using the current
    … …  
    7066std::string FormatDecimalNumberIntoString(double number);
    7167}}}
     68Path functions:
    7269
    73 Path functions:
    7470{{{
    7571// Returns the localized version of the specified path if there is one.
    … …  
    7874VfsPath LocalizePath(VfsPath sourcePath);
    7975}}}
     76== GUI ==
     77=== Text ===
     78The `source/gui/CGUI.cpp` file implements the parsing of the GUI XML localization elements:
    8079
    81 == GUI ==
    82 
    83 === Text ===
    84 
    85 The `source/gui/CGUI.cpp` file implements the parsing of the GUI XML localization elements:
    86 * `attribute` (along with `keep` and `translate`)
    87 * `translatableAttribute`.
     80 * `attribute` (along with `keep` and `translate`)
     81 * `translatableAttribute`.
    8882
    8983See [wiki:Internationalization#InternationalizingGUIFiles Internationalizing GUI Files] to see how to use them.
    9084
    9185=== Images ===
    92 
    9386The `source/gui/GUIRenderer.cpp` file, responsible for rendering images on the GUI, is configured to use `L10n.Instance().LocalizePath()`, which loads localized versions of images if available.
    9487
    … …  
    9689
    9790== Functions Published for JavaScript ==
    98 
    9991'''TODO''': Link to svn.wildfiregames.com/docs when #67 gets committed.
    10092
    101 The `source/i18n/scripting/JSI_L10n.cpp` file publishes some of the functions that the `L10n` singleton offers, as well as some custom internationalization functions based on the `L10n` functionality.
     93The `source/i18n/scripting/JSInterface_L10n.cpp` file publishes some of the functions that the `L10n` singleton offers, as well as some custom internationalization functions based on the `L10n` functionality.
    10294
    10395The following functions from `L10n` are published:
     96
    10497{{{
    10598scriptInterface.RegisterFunction<std::string, &GetCurrentLocale>("GetCurrentLocale");
    … …  
    120113scriptInterface.RegisterFunction<std::wstring, double, &FormatDecimalNumberIntoString>("FormatDecimalNumberIntoString");
    121114}}}
     115The following custom functions are also published:
    122116
    123 The following custom functions are also published:
    124117{{{
    125118// Returns the build time of the game formatted for the current locale.
    … …  
    138131scriptInterface.RegisterFunction<std::wstring, std::wstring, &MarkToTranslate>("MarkToTranslate");
    139132}}}
    140 
    141133== JavaScript-Side Implementation ==
    142 
    143134The following sections describe some implementation details that are specific to the JavaScript side.
    144135
    145136=== JavaScript Translation Cache System ===
    146 
    147137Although you can access the C++ functions listed above from JavaScript simply prefixing them with `Engine`, as in `Engine.Translate()`, the `binaries/data/mods/public/globalscripts/l10n.js` file defines the following equivalent global internationalization functions:
    148138
    … …  
    153143translatePluralWithContext(context, singularMessage, pluralMessage, number);
    154144}}}
    155 
    156145These global functions are basically wrappers for the engine internationalization functions, however they are not just that. These global functions use JavaScript-side caching to reduce the number of calls to the engine functions, because calls to engine functions require string conversions that are far from cheap.
    157146
    … …  
    159148
    160149=== Object Translation Helper Function ===
    161 
    162150The `binaries/data/mods/public/globalscripts/l10n.js` file defines a function, `translateObjectKeys`, which is a helper function that can translate specific properties of a !JavaScript object:
    163151
    … …  
    165153translateObjectKeys(object, keys);
    166154}}}
    167 
    168155The `keys` parameter is an array of strings with the names of the object properties to translate.
    169156
    170157=== String Formatting Function ===
    171 
    172158The `binaries/data/mods/public/globalscripts/sprintf.js` file defines a function, `sprintf`, that can be used for string formatting. To learn how to use it, see [wiki:Internationalization#UsingStringFormattingInsteadofConcatenatingStringsinJavaScript Using String Formatting Instead of Concatenating Strings in JavaScript].
    173159
    174160= Message Extraction =
    175 
    176161Message extractions is the process of parsing the source files searching for strings that need to be translated, and generating a translation template file (POT) from them that translators can use.
    177162
    … …  
    185170
    186171= Localization =
    187 
    188172== Transifex Integration ==
    189 
    190173Currently, the translation of the game happens in Transifex, at https://www.transifex.com/projects/p/0ad/
    191174
    … …  
    197180
    198181== Long Strings Locale ==
    199 
    200182The `source/tools/i18n/generateLongStringTranslations.py` is a special script that generates a PO file for an artificial language with code "long". This PO file consists of the longest strings (as in number of characters) of every available language for each message.
    201183
    … …  
    203185
    204186= Language Selection Menu =
     187The dialog box that you open when you select '''Options → Language '''in the main menu is defined in the following files:
    205188
    206 The dialog box that you open when you select '''Options → Language '''in the main menu is defined in the following files:
    207 * `gui/page_locale.xml`
    208 * `gui/locale/locale.js`
    209 * `gui/locale/locale.xml`
     189 * `gui/page_locale.xml`
     190 * `gui/locale/locale.js`
     191 * `gui/locale/locale.xml`