Changes between Version 7 and Version 8 of Implementation_of_Internationalization_and_Localization


Ignore:
Timestamp:
Apr 16, 2014, 1:42:08 PM (10 years ago)
Author:
leper
Comment:

Exported Engine functions are PascalCase.

Legend:

Unmodified
Added
Removed
Modified

  • Implementation_of_Internationalization_and_Localization

    v7 v8  
    1717The heart of the internationalization and localization implementation is at `source/i18n/L10n.cpp`.
    1818
    19 The `L10n` class implemented in this file works as a [http://en.wikipedia.org/wiki/Singleton_pattern singleton], and provides many functions that can be used from anywhere in the engine C++ codebase. You can get an instance of the singleton including the `i18n/L10n.h` header file and calling `L10n::instance()`.
     19The `L10n` class implemented in this file works as a [http://en.wikipedia.org/wiki/Singleton_pattern singleton], and provides many functions that can be used from anywhere in the engine C++ codebase. You can get an instance of the singleton including the `i18n/L10n.h` header file and calling `L10n::Instance()`.
    2020
    2121This class holds the current locale and the translations for the current locale at any given time, and its methods are used all over the C++ implementation (and published to JavaScript as well).
    … …  
    2929        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`.
    3030
    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).
     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).
    3232
    3333    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()].
    … …  
    3535        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).
    3636
    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.
     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.
    3838
    3939=== Localization Functions ===
    … …  
    4343Translation functions ([wiki:Internationalization] explains how to use them):
    4444{{{
    45 std::string translate(const std::string& sourceString);
    46 std::string translateWithContext(const std::string& context, const std::string& sourceString);
    47 std::string translatePlural(const std::string& singularSourceString, const std::string& pluralSourceString, int number);
    48 std::string translatePluralWithContext(const std::string& context, const std::string& singularSourceString, const std::string& pluralSourceString, int number);
    49 std::string translateLines(const std::string& sourceString);
     45std::string Translate(const std::string& sourceString);
     46std::string TranslateWithContext(const std::string& context, const std::string& sourceString);
     47std::string TranslatePlural(const std::string& singularSourceString, const std::string& pluralSourceString, int number);
     48std::string TranslatePluralWithContext(const std::string& context, const std::string& singularSourceString, const std::string& pluralSourceString, int number);
     49std::string TranslateLines(const std::string& sourceString);
    5050}}}
    5151
    … …  
    5555// into icu::UDate and the other way around. These are used in
    5656// “gui/scripting/ScriptFunctions.cpp”.
    57 UDate parseDateTime(const std::string& dateTimeString, const std::string& dateTimeFormat, const Locale& locale);
    58 std::string localizeDateTime(const UDate& dateTime, DateTimeType type, DateFormat::EStyle style);
     57UDate ParseDateTime(const std::string& dateTimeString, const std::string& dateTimeFormat, const Locale& locale);
     58std::string LocalizeDateTime(const UDate& dateTime, DateTimeType type, DateFormat::EStyle style);
    5959
    6060// Converts a string from UNIX timestamp (in milliseconds, not seconds) into a
    6161// string with the specified format. See the ‘Internationalization’ page in the
    6262// documentation for more information.
    63 std::string formatMillisecondsIntoDateString(int milliseconds, const std::string& formatString);
     63std::string FormatMillisecondsIntoDateString(int milliseconds, const std::string& formatString);
    6464}}}
    6565
    … …  
    6868// Returns the specified floating-point number as a string using the current
    6969// locale.
    70 std::string formatDecimalNumberIntoString(double number);
     70std::string FormatDecimalNumberIntoString(double number);
    7171}}}
    7272
    … …  
    7676// Otherwise, it returns sourcePath.
    7777// This is used for image localization (see below).
    78 VfsPath localizePath(VfsPath sourcePath);
     78VfsPath LocalizePath(VfsPath sourcePath);
    7979}}}
    8080
    … …  
    9191=== Images ===
    9292
    93 The `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.
     93The `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.
    9494
    9595See [wiki:Localization#LocalizingImages Localizing Images] for more information.
    … …  
    9797== Functions Published for JavaScript ==
    9898
    99 The `source/gui/scripting/ScriptFunctions.cpp` file publishes some of the functions that the `L10n` singleton offers, as well as some custom internationalization functions based on the `L10n` functionality.
     99'''TODO''': Link to svn.wildfiregames.com/docs when #67 gets committed.
     100
     101The `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.
    100102
    101103The following functions from `L10n` are published:
    102104{{{
    103 scriptInterface.RegisterFunction<std::string, &getCurrentLocale>("getCurrentLocale");
     105scriptInterface.RegisterFunction<std::string, &GetCurrentLocale>("GetCurrentLocale");
    104106scriptInterface.RegisterFunction<void, std::string, &SetLocale>("SetLocale");
    105107
    … …  
    108110scriptInterface.RegisterFunction<int, &GetCurrentLocaleIndex>("GetCurrentLocaleIndex");
    109111
    110 scriptInterface.RegisterFunction<std::wstring, std::wstring, &translate>("translate");
    111 scriptInterface.RegisterFunction<std::wstring, std::string, std::wstring, &translateWithContext>("translateWithContext");
    112 scriptInterface.RegisterFunction<std::wstring, std::wstring, std::wstring, int, &translatePlural>("translatePlural");
    113 scriptInterface.RegisterFunction<std::wstring, std::string, std::wstring, std::wstring, int, &translatePluralWithContext>("translatePluralWithContext");
    114 scriptInterface.RegisterFunction<std::wstring, std::wstring, &translateLines>("translateLines");
    115 
    116 scriptInterface.RegisterFunction<std::wstring, int, std::wstring, &formatMillisecondsIntoDateString>("formatMillisecondsIntoDateString");
    117 
    118 scriptInterface.RegisterFunction<std::wstring, double, &formatDecimalNumberIntoString>("formatDecimalNumberIntoString");
     112scriptInterface.RegisterFunction<std::wstring, std::wstring, &Translate>("Translate");
     113scriptInterface.RegisterFunction<std::wstring, std::string, std::wstring, &TranslateWithContext>("TranslateWithContext");
     114scriptInterface.RegisterFunction<std::wstring, std::wstring, std::wstring, int, &TranslatePlural>("TranslatePlural");
     115scriptInterface.RegisterFunction<std::wstring, std::string, std::wstring, std::wstring, int, &TranslatePluralWithContext>("TranslatePluralWithContext");
     116scriptInterface.RegisterFunction<std::wstring, std::wstring, &TranslateLines>("TranslateLines");
     117
     118scriptInterface.RegisterFunction<std::wstring, int, std::wstring, &FormatMillisecondsIntoDateString>("FormatMillisecondsIntoDateString");
     119
     120scriptInterface.RegisterFunction<std::wstring, double, &FormatDecimalNumberIntoString>("FormatDecimalNumberIntoString");
    119121}}}
    120122
    … …  
    122124{{{
    123125// Returns the build time of the game formatted for the current locale.
    124 scriptInterface.RegisterFunction<std::wstring, int, &GetBuildTimestamp>("GetBuildTimestamp");
     126scriptInterface.RegisterFunction<std::wstring, int, &GetBuildTimestamp>("GetBuildTimestamp"); // in source/gui/scripting/ScriptFunctions.cpp
    125127
    126128// Translates an array of strings, avoiding what would otherwise be many calls
    127129// to the C++ engine from JavaScript.
    128 scriptInterface.RegisterFunction<std::vector<std::wstring>, std::vector<std::wstring>, &translateArray>("translateArray");
     130scriptInterface.RegisterFunction<std::vector<std::wstring>, std::vector<std::wstring>, &TranslateArray>("TranslateArray");
    129131
    130132// Simply returns the string that it receives. This function is required to mark
    … …  
    134136// below). For more information, see:
    135137// http://www.gnu.org/software/gettext/manual/html_node/Special-cases.html
    136 scriptInterface.RegisterFunction<std::wstring, std::wstring, &markToTranslate>("markToTranslate");
     138scriptInterface.RegisterFunction<std::wstring, std::wstring, &MarkToTranslate>("MarkToTranslate");
    137139}}}
    138140
    … …  
    143145=== JavaScript Translation Cache System ===
    144146
    145 Although 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:
     147Although 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:
    146148
    147149{{{