Namespace for the functions of the JavaScript interface for internationalization and localization. More...

Functions
void	RegisterScriptFunctions (ScriptInterface &ScriptInterface)
	Registers the functions of the JavaScript interface for internationalization and localization into the specified JavaScript context. More...

std::wstring	Translate (ScriptInterface::CxPrivate *pCxPrivate, const std::wstring &sourceString)
	Returns the translation of the specified string to the current locale. More...

std::wstring	TranslateWithContext (ScriptInterface::CxPrivate *pCxPrivate, const std::string &context, const std::wstring &sourceString)
	Returns the translation of the specified string to the current locale in the specified context. More...

std::wstring	TranslatePlural (ScriptInterface::CxPrivate *pCxPrivate, const std::wstring &singularSourceString, const std::wstring &pluralSourceString, int number)
	Returns the translation of the specified string to the current locale based on the specified number. More...

std::wstring	TranslatePluralWithContext (ScriptInterface::CxPrivate *pCxPrivate, const std::string &context, const std::wstring &singularSourceString, const std::wstring &pluralSourceString, int number)
	Returns the translation of the specified string to the current locale in the specified context, based on the specified number. More...

std::wstring	TranslateLines (ScriptInterface::CxPrivate *pCxPrivate, const std::wstring &sourceString)
	Translates a text line by line to the current locale. More...

std::vector< std::wstring >	TranslateArray (ScriptInterface::CxPrivate *pCxPrivate, const std::vector< std::wstring > &sourceArray)
	Translate each of the strings of a JavaScript array to the current locale. More...

std::wstring	FormatMillisecondsIntoDateStringLocal (ScriptInterface::CxPrivate *pCxPrivate, UDate milliseconds, const std::wstring &formatString)
	Returns the specified date converted to the local timezone using the specified date format. More...

std::wstring	FormatMillisecondsIntoDateStringGMT (ScriptInterface::CxPrivate *pCxPrivate, UDate milliseconds, const std::wstring &formatString)
	Returns the specified date in GMT using the specified date format. More...

std::wstring	FormatDecimalNumberIntoString (ScriptInterface::CxPrivate *pCxPrivate, double number)
	Returns the specified floating-point number as a string, with the number formatted as a decimal number using the current locale. More...

std::vector< std::string >	GetSupportedLocaleBaseNames (ScriptInterface::CxPrivate *pCxPrivate)
	Returns an array of supported locale codes sorted alphabetically. More...

std::vector< std::wstring >	GetSupportedLocaleDisplayNames (ScriptInterface::CxPrivate *pCxPrivate)
	Returns an array of supported locale names sorted alphabetically by locale code. More...

std::string	GetCurrentLocale (ScriptInterface::CxPrivate *pCxPrivate)
	Returns the code of the current locale. More...

std::vector< std::string >	GetAllLocales (ScriptInterface::CxPrivate *pCxPrivate)
	Returns an array of locale codes supported by ICU. More...

std::string	GetDictionaryLocale (ScriptInterface::CxPrivate *pCxPrivate, const std::string &configLocale)
	Returns the code of the recommended locale for the current user that the game supports. More...

std::vector< std::wstring >	GetDictionariesForLocale (ScriptInterface::CxPrivate *pCxPrivate, const std::string &locale)
	Returns an array of paths to files in the virtual filesystem that provide translations for the specified locale code. More...

std::string	GetLocaleLanguage (ScriptInterface::CxPrivate *pCxPrivate, const std::string &locale)
	Returns the ISO-639 language code of the specified locale code. More...

std::string	GetLocaleBaseName (ScriptInterface::CxPrivate *pCxPrivate, const std::string &locale)
	Returns the programmatic code of the entire locale without keywords. More...

std::string	GetLocaleCountry (ScriptInterface::CxPrivate *pCxPrivate, const std::string &locale)
	Returns the ISO-3166 country code of the specified locale code. More...

std::string	GetLocaleScript (ScriptInterface::CxPrivate *pCxPrivate, const std::string &locale)
	Returns the ISO-15924 abbreviation script code of the specified locale code. More...

std::wstring	GetFallbackToAvailableDictLocale (ScriptInterface::CxPrivate *pCxPrivate, const std::string &locale)

bool	UseLongStrings (ScriptInterface::CxPrivate *pCxPrivate)
	Returns `true` if the current locale is the special “Long Strings” locale. More...

bool	ValidateLocale (ScriptInterface::CxPrivate *pCxPrivate, const std::string &locale)
	Returns `true` if the locale is supported by both ICU and the game. More...

bool	SaveLocale (ScriptInterface::CxPrivate *pCxPrivate, const std::string &locale)
	Saves the specified locale in the game configuration file. More...

void	ReevaluateCurrentLocaleAndReload (ScriptInterface::CxPrivate *pCxPrivate)
	Determines the best, supported locale for the current user, makes it the current game locale and reloads the translations dictionary with translations for that locale. More...

Detailed Description

Namespace for the functions of the JavaScript interface for internationalization and localization.

This namespace defines JavaScript interfaces to functions defined in L10n and related helper functions.

See also: http://trac.wildfiregames.com/wiki/Internationalization_and_Localization

Function Documentation

std::wstring JSI_L10n::FormatDecimalNumberIntoString	(	ScriptInterface::CxPrivate *	pCxPrivate,
		double	number
	)

Returns the specified floating-point number as a string, with the number formatted as a decimal number using the current locale.

This is a JavaScript interface to L10n::FormatDecimalNumberIntoString().

Parameters

pCxPrivate	JavaScript context.
number	Number to format.

Returns: Decimal number formatted using the current locale.

std::wstring JSI_L10n::FormatMillisecondsIntoDateStringGMT	(	ScriptInterface::CxPrivate *	pCxPrivate,
		UDate	milliseconds,
		const std::wstring &	formatString
	)

Returns the specified date in GMT using the specified date format.

This is a JavaScript interface to L10n::FormatMillisecondsIntoDateString().

Parameters

pCxPrivate	JavaScript context.
milliseconds	Date specified as a UNIX timestamp in milliseconds (not seconds). If you have a JavaScript `Date` object, you can use `Date.getTime()` to obtain the UNIX time in milliseconds.
formatString	Date format string defined using ICU date formatting symbols. Usually, you internationalize the format string and get it translated before you pass it to FormatMillisecondsIntoDateString().

Returns: String containing the specified date with the specified date format.

See also: http://en.wikipedia.org/wiki/Unix_time; https://sites.google.com/site/icuprojectuserguide/formatparse/datetime?pli=1#TOC-Date-Field-Symbol-Table

std::wstring JSI_L10n::FormatMillisecondsIntoDateStringLocal	(	ScriptInterface::CxPrivate *	pCxPrivate,
		UDate	milliseconds,
		const std::wstring &	formatString
	)

Returns the specified date converted to the local timezone using the specified date format.

This is a JavaScript interface to L10n::FormatMillisecondsIntoDateString().

Parameters

pCxPrivate	JavaScript context.
milliseconds	Date specified as a UNIX timestamp in milliseconds (not seconds). If you have a JavaScript `Date` object, you can use `Date.getTime()` to obtain the UNIX time in milliseconds.
formatString	Date format string defined using ICU date formatting symbols. Usually, you internationalize the format string and get it translated before you pass it to FormatMillisecondsIntoDateString().

Returns: String containing the specified date with the specified date format.

See also: http://en.wikipedia.org/wiki/Unix_time; https://sites.google.com/site/icuprojectuserguide/formatparse/datetime?pli=1#TOC-Date-Field-Symbol-Table

std::vector< std::string > JSI_L10n::GetAllLocales ( ScriptInterface::CxPrivate * pCxPrivate )

Returns an array of locale codes supported by ICU.

A locale code is a string such as "de" or "pt_BR".

This is a JavaScript interface to L10n::GetAllLocales().

Parameters

pCxPrivate JavaScript context.

Returns: Array of supported locale codes.

See also: GetSupportedLocaleBaseNames(); GetCurrentLocale(); http://www.icu-project.org/apiref/icu4c/classicu_1_1Locale.html#a073d70df8c9c8d119c0d42d70de24137

std::string JSI_L10n::GetCurrentLocale ( ScriptInterface::CxPrivate * pCxPrivate )

Returns the code of the current locale.

A locale code is a string such as "de" or "pt_BR".

This is a JavaScript interface to L10n::GetCurrentLocaleString().

Parameters

pCxPrivate JavaScript context.

See also: GetSupportedLocaleBaseNames(); GetAllLocales(); ReevaluateCurrentLocaleAndReload()

std::vector< std::wstring > JSI_L10n::GetDictionariesForLocale	(	ScriptInterface::CxPrivate *	pCxPrivate,
		const std::string &	locale
	)

Returns an array of paths to files in the virtual filesystem that provide translations for the specified locale code.

This is a JavaScript interface to L10n::GetDictionariesForLocale().

Parameters

pCxPrivate	JavaScript context.
locale	Locale code.

Returns: Array of paths to files in the virtual filesystem that provide translations for locale.

std::string JSI_L10n::GetDictionaryLocale	(	ScriptInterface::CxPrivate *	pCxPrivate,
		const std::string &	configLocale
	)

Returns the code of the recommended locale for the current user that the game supports.

“That the game supports” means both that a translation file is available for that locale and that the locale code is either supported by ICU or the special “long” locale code.

The mechanism to select a recommended locale follows this logic:

First see if the game supports the specified locale,
configLocale.
Otherwise, check the system locale and see if the game supports
that locale.
Else, return the default locale, ‘en_US’.

This is a JavaScript interface to L10n::GetDictionaryLocale(std::string).

Parameters

pCxPrivate	JavaScript context.
configLocale	Locale to check for support first. Pass an empty string to check the system locale directly.

Returns: Code of a locale that the game supports.

See also: http://trac.wildfiregames.com/wiki/Implementation_of_Internationalization_and_Localization#LongStringsLocale

std::wstring JSI_L10n::GetFallbackToAvailableDictLocale	(	ScriptInterface::CxPrivate *	pCxPrivate,
		const std::string &	locale
	)

std::string JSI_L10n::GetLocaleBaseName	(	ScriptInterface::CxPrivate *	pCxPrivate,
		const std::string &	locale
	)

Returns the programmatic code of the entire locale without keywords.

This is a JavaScript interface to L10n::GetLocaleBaseName().

Parameters

pCxPrivate	JavaScript context.
locale	Locale code.

Returns: Locale code without keywords.

See also: http://www.icu-project.org/apiref/icu4c/classicu_1_1Locale.html#a4c1acbbdf95dc15599db5f322fa4c4d0

std::string JSI_L10n::GetLocaleCountry	(	ScriptInterface::CxPrivate *	pCxPrivate,
		const std::string &	locale
	)

Returns the ISO-3166 country code of the specified locale code.

For example, if you specify the ‘en_US’ locate, it returns ‘US’.

This is a JavaScript interface to L10n::GetLocaleCountry().

Parameters

pCxPrivate	JavaScript context.
locale	Locale code.

Returns: Country code.

See also: http://www.icu-project.org/apiref/icu4c/classicu_1_1Locale.html#ae3f1fc415c00d4f0ab33288ceadccbf9

std::string JSI_L10n::GetLocaleLanguage	(	ScriptInterface::CxPrivate *	pCxPrivate,
		const std::string &	locale
	)

Returns the ISO-639 language code of the specified locale code.

For example, if you specify the ‘en_US’ locate, it returns ‘en’.

This is a JavaScript interface to L10n::GetLocaleLanguage().

Parameters

pCxPrivate	JavaScript context.
locale	Locale code.

Returns: Language code.

See also: http://www.icu-project.org/apiref/icu4c/classicu_1_1Locale.html#af36d821adced72a870d921ebadd0ca93

std::string JSI_L10n::GetLocaleScript	(	ScriptInterface::CxPrivate *	pCxPrivate,
		const std::string &	locale
	)

Returns the ISO-15924 abbreviation script code of the specified locale code.

This is a JavaScript interface to L10n::GetLocaleScript().

Parameters

pCxPrivate	JavaScript context.
locale	Locale code.

Returns: Script code.

See also: http://www.icu-project.org/apiref/icu4c/classicu_1_1Locale.html#a5e0145a339d30794178a1412dcc55abe

std::vector< std::string > JSI_L10n::GetSupportedLocaleBaseNames ( ScriptInterface::CxPrivate * pCxPrivate )

Returns an array of supported locale codes sorted alphabetically.

A locale code is a string such as "de" or "pt_BR".

If yours is a development copy (the ‘config/dev.cfg’ file is found in the virtual filesystem), the output array may include the special “long” locale code.

This is a JavaScript interface to L10n::GetSupportedLocaleBaseNames().

Parameters

pCxPrivate JavaScript context.

Returns: Array of supported locale codes.

See also: GetSupportedLocaleDisplayNames(); GetAllLocales(); GetCurrentLocale(); http://trac.wildfiregames.com/wiki/Implementation_of_Internationalization_and_Localization#LongStringsLocale

std::vector< std::wstring > JSI_L10n::GetSupportedLocaleDisplayNames ( ScriptInterface::CxPrivate * pCxPrivate )

Returns an array of supported locale names sorted alphabetically by locale code.

A locale code is a string such as "de" or "pt_BR".

If yours is a development copy (the ‘config/dev.cfg’ file is found in the virtual filesystem), the output array may include the special “Long Strings” locale name.

This is a JavaScript interface to L10n::GetSupportedLocaleDisplayNames().

Parameters

pCxPrivate JavaScript context.

Returns: Array of supported locale codes.

See also: GetSupportedLocaleBaseNames(); http://trac.wildfiregames.com/wiki/Implementation_of_Internationalization_and_Localization#LongStringsLocale

void JSI_L10n::ReevaluateCurrentLocaleAndReload ( ScriptInterface::CxPrivate * pCxPrivate )

Determines the best, supported locale for the current user, makes it the current game locale and reloads the translations dictionary with translations for that locale.

To determine the best locale, ReevaluateCurrentLocaleAndReload():

Checks the user game configuration.
If the locale is not defined there, it checks the system locale.
If none of those locales are supported by the game, the default
locale, ‘en_US’, is used.

This is a JavaScript interface to L10n::ReevaluateCurrentLocaleAndReload().

Parameters

pCxPrivate JavaScript context.

See also: GetCurrentLocale()

void JSI_L10n::RegisterScriptFunctions ( ScriptInterface & ScriptInterface )

Registers the functions of the JavaScript interface for internationalization and localization into the specified JavaScript context.

Parameters

ScriptInterface JavaScript context where RegisterScriptFunctions() registers the functions.

See also: GuiScriptingInit()

bool JSI_L10n::SaveLocale	(	ScriptInterface::CxPrivate *	pCxPrivate,
		const std::string &	locale
	)

Saves the specified locale in the game configuration file.

The next time that the game starts, the game uses the locale in the configuration file if there are translation files available for it.

SaveLocale() checks the validity of the specified locale with ValidateLocale(). If the specified locale is not valid, SaveLocale() returns false and does not save the locale to the configuration file.

This is a JavaScript interface to L10n::SaveLocale().

Parameters

pCxPrivate	JavaScript context.
locale	Locale to save to the configuration file.

Returns: Whether the specified locale is valid (true) or not (false).

std::wstring JSI_L10n::Translate	(	ScriptInterface::CxPrivate *	pCxPrivate,
		const std::wstring &	sourceString
	)

Returns the translation of the specified string to the current locale.

This is a JavaScript interface to L10n::Translate().

Parameters

pCxPrivate	JavaScript context.
sourceString	String to translate to the current locale.

Returns: Translation of sourceString to the current locale, or sourceString if there is no translation available.

std::vector< std::wstring > JSI_L10n::TranslateArray	(	ScriptInterface::CxPrivate *	pCxPrivate,
		const std::vector< std::wstring > &	sourceArray
	)

Translate each of the strings of a JavaScript array to the current locale.

This is a helper function that loops through the items of the input array and calls L10n::Translate() on each of them.

Parameters

pCxPrivate	JavaScript context.
sourceArray	JavaScript array of strings to translate to the current locale.

Returns: Item by item translation of sourceArray to the current locale. Some of the items in the returned array may be in English because there was not translation available for them.

std::wstring JSI_L10n::TranslateLines	(	ScriptInterface::CxPrivate *	pCxPrivate,
		const std::wstring &	sourceString
	)

Translates a text line by line to the current locale.

TranslateLines() is helpful when you need to translate a plain text file after you load it.

This is a JavaScript interface to L10n::TranslateLines().

Parameters

pCxPrivate	JavaScript context.
sourceString	Text to translate to the current locale.

Returns: Line by line translation of sourceString to the current locale. Some of the lines in the returned text may be in English because there was not translation available for them.

std::wstring JSI_L10n::TranslatePlural	(	ScriptInterface::CxPrivate *	pCxPrivate,
		const std::wstring &	singularSourceString,
		const std::wstring &	pluralSourceString,
		int	number
	)

Returns the translation of the specified string to the current locale based on the specified number.

This is a JavaScript interface to L10n::TranslatePlural().

Parameters

pCxPrivate	JavaScript context.
singularSourceString	String to translate to the current locale, in English’ singular form.
pluralSourceString	String to translate to the current locale, in English’ plural form.
number	Number that determines the required form of the translation (or the English string if no translation is available).

Returns: Translation of the source string to the current locale for the specified number, or either singularSourceString (if number is 1) or pluralSourceString (if number is not 1) if there is no translation available.

std::wstring JSI_L10n::TranslatePluralWithContext	(	ScriptInterface::CxPrivate *	pCxPrivate,
		const std::string &	context,
		const std::wstring &	singularSourceString,
		const std::wstring &	pluralSourceString,
		int	number
	)

Returns the translation of the specified string to the current locale in the specified context, based on the specified number.

This is a JavaScript interface to L10n::TranslatePluralWithContext().

Parameters

pCxPrivate	JavaScript context.
context	Context where the string is used. See http://www.gnu.org/software/gettext/manual/html_node/Contexts.html
singularSourceString	String to translate to the current locale, in English’ singular form.
pluralSourceString	String to translate to the current locale, in English’ plural form.
number	Number that determines the required form of the translation (or the English string if no translation is available). *

Returns: Translation of the source string to the current locale in the specified context and for the specified number, or either singularSourceString (if number is 1) or pluralSourceString (if number is not 1) if there is no translation available.

std::wstring JSI_L10n::TranslateWithContext	(	ScriptInterface::CxPrivate *	pCxPrivate,
		const std::string &	context,
		const std::wstring &	sourceString
	)

Returns the translation of the specified string to the current locale in the specified context.

This is a JavaScript interface to L10n::TranslateWithContext().

Parameters

pCxPrivate	JavaScript context.
context	Context where the string is used. See http://www.gnu.org/software/gettext/manual/html_node/Contexts.html
sourceString	String to translate to the current locale.

Returns: Translation of sourceString to the current locale in the specified context, or sourceString if there is no translation available.

bool JSI_L10n::UseLongStrings ( ScriptInterface::CxPrivate * pCxPrivate )

Returns true if the current locale is the special “Long Strings” locale.

It returns false otherwise.

This is a JavaScript interface to L10n::UseLongStrings().

Parameters

pCxPrivate JavaScript context. *

Returns: Whether the current locale is the special “Long Strings” (true) or not (false).

bool JSI_L10n::ValidateLocale	(	ScriptInterface::CxPrivate *	pCxPrivate,
		const std::string &	locale
	)

Returns true if the locale is supported by both ICU and the game.

It returns false otherwise.

It returns true if both of these conditions are true:

ICU has resources for that locale (which also ensures it’s a valid
locale string).
Either a dictionary for language_country or for language is
available.

This is a JavaScript interface to L10n::ValidateLocale(const std::string&).

Parameters

pCxPrivate	JavaScript context.
locale	Locale to check.

Returns: Whether locale is supported by both ICU and the game (true) or not (false).