Singleton for internationalization and localization. More...

#include <L10n.h>

Inheritance diagram for L10n:

Collaboration diagram for L10n:

Public Types
enum	DateTimeType { DateTime , Date , Time }
	Types of dates. More...

Public Member Functions
	L10n ()
	Creates an instance of L10n. More...

	~L10n ()
	Handles the destruction of L10n. More...

const icu::Locale &	GetCurrentLocale () const
	Returns the current locale. More...

std::string	GetCurrentLocaleString () const
	Returns the code of the current locale. More...

std::vector< std::string >	GetAllLocales () const
	Returns a vector of locale codes supported by ICU. More...

bool	SaveLocale (const std::string &localeCode) const
	Saves the specified locale in the game configuration file. More...

bool	SaveLocale (const icu::Locale &locale) const

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

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

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

std::string	GetLocaleBaseName (const std::string &locale) const
	Returns the programmatic code of the entire locale without keywords. More...

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

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

bool	UseLongStrings () const
	Returns `true` if the current locale is the special "Long Strings" locale. More...

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

std::wstring	GetFallbackToAvailableDictLocale (const icu::Locale &locale) const

std::wstring	GetFallbackToAvailableDictLocale (const std::string &locale) const

std::string	GetDictionaryLocale (const std::string &configLocaleString) const
	Returns the code of the recommended locale for the current user that the game supports. More...

void	GetDictionaryLocale (const std::string &configLocaleString, icu::Locale &outLocale) const
	Saves an instance of the recommended locale for the current user that the game supports in the specified variable. More...

void	ReevaluateCurrentLocaleAndReload ()
	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...

bool	ValidateLocale (const icu::Locale &locale) const
	Returns `true` if the locale is supported by both ICU and the game. More...

bool	ValidateLocale (const std::string &localeCode) const

std::string	Translate (const std::string &sourceString) const
	Returns the translation of the specified string to the current locale. More...

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

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

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

std::string	TranslateLines (const std::string &sourceString) const
	Translates a text line by line to the current locale. More...

UDate	ParseDateTime (const std::string &dateTimeString, const std::string &dateTimeFormat, const icu::Locale &locale) const
	Parses the date in the input string using the specified date format, and returns the parsed date as a UNIX timestamp in milliseconds (not seconds). More...

std::string	LocalizeDateTime (const UDate dateTime, const DateTimeType &type, const icu::DateFormat::EStyle &style) const
	Returns the specified date using the specified date format. More...

std::string	FormatMillisecondsIntoDateString (const UDate milliseconds, const std::string &formatString, bool useLocalTimezone) const
	Returns the specified date using the specified date format. More...

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

VfsPath	LocalizePath (const VfsPath &sourcePath) const
	Returns the localized version of the specified path if there is one for the current locale. More...

Status	ReloadChangedFile (const VfsPath &path)
	Loads `path` into the dictionary if it is a translation file of the current locale. More...

Public Member Functions inherited from Singleton< L10n >
	Singleton ()

	~Singleton ()

Private Member Functions
void	LoadDictionaryForCurrentLocale ()
	Loads the translation files for the current locale. More...

Private Attributes
std::unique_ptr< tinygettext::Dictionary >	m_Dictionary
	Dictionary that contains the translations for the current locale and the matching English strings, including contexts and plural forms. More...

icu::Locale	m_CurrentLocale
	Locale that the game is currently using. More...

std::vector< icu::Locale >	m_AvailableLocales
	Vector with the locales that the game supports. More...

bool	m_CurrentLocaleIsOriginalGameLocale {false}
	Whether the game is using the default game locale (`true`), 'en_US', or not (`false`). More...

bool	m_UseLongStrings {false}
	Whether the game is using the special game locale with the longest strings of each translation (`true`) or not (`false`). More...

Additional Inherited Members
Static Public Member Functions inherited from Singleton< L10n >
static L10n &	GetSingleton ()

static L10n *	GetSingletonPtr ()

static bool	IsInitialised ()

Detailed Description

Singleton for internationalization and localization.

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

Member Enumeration Documentation

◆ DateTimeType

enum L10n::DateTimeType

Types of dates.

See also: LocalizeDateTime()

Enumerator
DateTime	Both date and time.
Date	Only date.
Time	Only time.

Constructor & Destructor Documentation

◆ L10n()

L10n::L10n ( )

Creates an instance of L10n.

L10n is a singleton. Use Instance() instead of creating you own instances of L10n.

◆ ~L10n()

L10n::~L10n ( )

Handles the destruction of L10n.

Never destroy the L10n singleton manually. It must run as long as the game runs, and it is destroyed automatically when you quit the game.

Member Function Documentation

◆ FormatDecimalNumberIntoString()

std::string L10n::FormatDecimalNumberIntoString ( double number ) const

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

Parameters

number Number to format.

Returns: Decimal number formatted using the current locale.

◆ FormatMillisecondsIntoDateString()

std::string L10n::FormatMillisecondsIntoDateString	(	const UDate	milliseconds,
		const std::string &	formatString,
		bool	useLocalTimezone
	)		const

Returns the specified date using the specified date format.

Parameters

milliseconds	Date specified as a UNIX timestamp in milliseconds (not seconds).
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().
useLocalTimezone	Boolean useful for durations

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

◆ GetAllLocales()

std::vector< std::string > L10n::GetAllLocales ( ) const

Returns a vector of locale codes supported by ICU.

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

Returns: Vector of supported locale codes.

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

◆ GetCurrentLocale()

const icu::Locale & L10n::GetCurrentLocale ( ) const

Returns the current locale.

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

◆ GetCurrentLocaleString()

std::string L10n::GetCurrentLocaleString ( ) const

Returns the code of the current locale.

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

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

◆ GetDictionariesForLocale()

std::vector< std::wstring > L10n::GetDictionariesForLocale ( const std::string & locale ) const

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

Parameters

locale Locale code.

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

◆ GetDictionaryLocale() [1/2]

std::string L10n::GetDictionaryLocale ( const std::string & configLocaleString ) const

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'.

Parameters

configLocaleString 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

◆ GetDictionaryLocale() [2/2]

void L10n::GetDictionaryLocale	(	const std::string &	configLocaleString,
		icu::Locale &	outLocale
	)		const

Saves an instance of the recommended locale for the current user that the game supports in the specified variable.

"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'.

Parameters

configLocaleString	Locale to check for support first. Pass an empty string to check the system locale directly.
outLocale	The recommended locale.

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

◆ GetFallbackToAvailableDictLocale() [1/2]

std::wstring L10n::GetFallbackToAvailableDictLocale ( const icu::Locale & locale ) const

◆ GetFallbackToAvailableDictLocale() [2/2]

std::wstring L10n::GetFallbackToAvailableDictLocale ( const std::string & locale ) const

◆ GetLocaleBaseName()

std::string L10n::GetLocaleBaseName ( const std::string & locale ) const

Returns the programmatic code of the entire locale without keywords.

Parameters

locale Locale code.

Returns: Locale code without keywords.

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

◆ GetLocaleCountry()

std::string L10n::GetLocaleCountry ( const std::string & locale ) const

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

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

Parameters

locale Locale code.

Returns: Country code.

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

◆ GetLocaleLanguage()

std::string L10n::GetLocaleLanguage ( const std::string & locale ) const

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

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

Parameters

locale Locale code.

Returns: Language code.

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

◆ GetLocaleScript()

std::string L10n::GetLocaleScript ( const std::string & locale ) const

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

Parameters

locale Locale code.

Returns: Script code.

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

◆ GetSupportedLocaleBaseNames()

std::vector< std::string > L10n::GetSupportedLocaleBaseNames ( ) const

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.

Returns: Array of supported locale codes.

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

◆ GetSupportedLocaleDisplayNames()

std::vector< std::wstring > L10n::GetSupportedLocaleDisplayNames ( ) const

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.

Returns: Array of supported locale codes.

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

◆ LoadDictionaryForCurrentLocale()

void L10n::LoadDictionaryForCurrentLocale ( )

private

Loads the translation files for the current locale.

This method loads every file in the 'l10n' folder of the game virtual filesystem that is prefixed with the code of the current locale followed by a dot.

For example, if the code of the current locale code is 'de', LoadDictionaryForCurrentLocale() loads the 'l10n/de.engine.po' and 'l10n/de.public.po' translation files.

See also: dictionary; ReadPoIntoDictionary()

◆ LocalizeDateTime()

std::string L10n::LocalizeDateTime	(	const UDate	dateTime,
		const DateTimeType &	type,
		const icu::DateFormat::EStyle &	style
	)		const

Returns the specified date using the specified date format.

Parameters

dateTime	Date specified as a UNIX timestamp in milliseconds (not seconds).
type	Whether the formatted date must show both the date and the time, only the date or only the time.
style	ICU style for the formatted date.

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

See also: http://en.wikipedia.org/wiki/Unix_time; http://icu-project.org/apiref/icu4c521/classicu_1_1DateFormat.html

◆ LocalizePath()

VfsPath L10n::LocalizePath ( const VfsPath & sourcePath ) const

Returns the localized version of the specified path if there is one for the current locale.

If there is no localized version of the specified path, it returns the specified path.

For example, if the code of the current locale is 'de_DE', LocalizePath() splits the input path into folder path and file name, and checks whether the '<folder>/l10n/de/<file>' file exists. If it does, it returns that path. Otherwise, it returns the input path, verbatim.

This function is used for file localization (for example, image localization).

Parameters

sourcePath Path to localize.

Returns: Localized path if it exists, sourcePath otherwise.

See also: http://trac.wildfiregames.com/wiki/Localization#LocalizingImages

◆ ParseDateTime()

UDate L10n::ParseDateTime	(	const std::string &	dateTimeString,
		const std::string &	dateTimeFormat,
		const icu::Locale &	locale
	)		const

Parses the date in the input string using the specified date format, and returns the parsed date as a UNIX timestamp in milliseconds (not seconds).

Parameters

dateTimeString	String containing the date to parse.
dateTimeFormat	Date format string to parse the input date, defined using ICU date formatting symbols.
locale	Locale to use when parsing the input date.

Returns: Specified date as a UNIX timestamp in milliseconds (not seconds).

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

◆ ReevaluateCurrentLocaleAndReload()

void L10n::ReevaluateCurrentLocaleAndReload ( )

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.

See also: GetCurrentLocale()

◆ ReloadChangedFile()

Status L10n::ReloadChangedFile ( const VfsPath & path )

Loads path into the dictionary if it is a translation file of the current locale.

◆ SaveLocale() [1/2]

bool L10n::SaveLocale ( const icu::Locale & locale ) const

◆ SaveLocale() [2/2]

bool L10n::SaveLocale ( const std::string & localeCode ) const

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.

Parameters

localeCode Locale to save to the configuration file.

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

◆ Translate()

std::string L10n::Translate ( const std::string & sourceString ) const

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

Parameters

sourceString String to translate to the current locale.

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

◆ TranslateLines()

std::string L10n::TranslateLines ( const std::string & sourceString ) const

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.

Parameters

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.

◆ TranslatePlural()

std::string L10n::TranslatePlural	(	const std::string &	singularSourceString,
		const std::string &	pluralSourceString,
		int	number
	)		const

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

Parameters

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.

◆ TranslatePluralWithContext()

std::string L10n::TranslatePluralWithContext	(	const std::string &	context,
		const std::string &	singularSourceString,
		const std::string &	pluralSourceString,
		int	number
	)		const

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

Parameters

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.

◆ TranslateWithContext()

std::string L10n::TranslateWithContext	(	const std::string &	context,
		const std::string &	sourceString
	)		const

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

Parameters

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.

◆ UseLongStrings()

bool L10n::UseLongStrings ( ) const

Returns true if the current locale is the special "Long Strings" locale.

It returns false otherwise.

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

◆ ValidateLocale() [1/2]

bool L10n::ValidateLocale ( const icu::Locale & locale ) const

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.

Parameters

locale Locale to check.

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

◆ ValidateLocale() [2/2]

bool L10n::ValidateLocale ( const std::string & localeCode ) const

Member Data Documentation

◆ m_AvailableLocales

std::vector<icu::Locale> L10n::m_AvailableLocales

private

Vector with the locales that the game supports.

The list of available locales is calculated when the game starts. Call LoadListOfAvailableLocales() to refresh the list.

See also: GetSupportedLocaleBaseNames(); GetSupportedLocaleDisplayNames()

◆ m_CurrentLocale

icu::Locale L10n::m_CurrentLocale

private

Locale that the game is currently using.

To get the current locale, use its getter: GetCurrentLocale(). You can also use GetCurrentLocaleString() to get the locale code of the current locale.

To change the value of this variable:

Save a new locale to the game configuration file with SaveLocale().
Reload the translation dictionary with
ReevaluateCurrentLocaleAndReload().

◆ m_CurrentLocaleIsOriginalGameLocale

bool L10n::m_CurrentLocaleIsOriginalGameLocale {false}

private

Whether the game is using the default game locale (true), 'en_US', or not (false).

This variable is used in the L10n implementation for performance reasons. Many localization steps can be skipped when this variable is true.

◆ m_Dictionary

std::unique_ptr<tinygettext::Dictionary> L10n::m_Dictionary

private

Dictionary that contains the translations for the current locale and the matching English strings, including contexts and plural forms.

See also: LoadDictionaryForCurrentLocale()

◆ m_UseLongStrings

bool L10n::m_UseLongStrings {false}

private

Whether the game is using the special game locale with the longest strings of each translation (true) or not (false).

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

The documentation for this class was generated from the following files:

/home/docker/jenkins/workspace/technical-docs/source/i18n/L10n.h
/home/docker/jenkins/workspace/technical-docs/source/i18n/L10n.cpp

Public Types

Public Member Functions

Private Member Functions

Private Attributes

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ DateTimeType

Constructor & Destructor Documentation

◆ L10n()

◆ ~L10n()

Member Function Documentation

◆ FormatDecimalNumberIntoString()

◆ FormatMillisecondsIntoDateString()

◆ GetAllLocales()

◆ GetCurrentLocale()

◆ GetCurrentLocaleString()

◆ GetDictionariesForLocale()

◆ GetDictionaryLocale() [1/2]

◆ GetDictionaryLocale() [2/2]

◆ GetFallbackToAvailableDictLocale() [1/2]

◆ GetFallbackToAvailableDictLocale() [2/2]

◆ GetLocaleBaseName()

◆ GetLocaleCountry()

◆ GetLocaleLanguage()

◆ GetLocaleScript()

◆ GetSupportedLocaleBaseNames()

◆ GetSupportedLocaleDisplayNames()

◆ LoadDictionaryForCurrentLocale()

◆ LocalizeDateTime()

◆ LocalizePath()

◆ ParseDateTime()

◆ ReevaluateCurrentLocaleAndReload()

◆ ReloadChangedFile()

◆ SaveLocale() [1/2]

◆ SaveLocale() [2/2]

◆ Translate()

◆ TranslateLines()

◆ TranslatePlural()

◆ TranslatePluralWithContext()

◆ TranslateWithContext()

◆ UseLongStrings()

◆ ValidateLocale() [1/2]

◆ ValidateLocale() [2/2]

Member Data Documentation

◆ m_AvailableLocales

◆ m_CurrentLocale

◆ m_CurrentLocaleIsOriginalGameLocale

◆ m_Dictionary

◆ m_UseLongStrings