carb::l10n::IL10n

Defined in carb/l10n/IL10n.h

struct IL10n

The localization interface.

Public Members

StringIdentifier (*getHashFromKeyString)(const char *keyString) noexcept

Calculates the lookup hash for a US English key string.

Remark

This calculates the hash value for a string. This is useful for scripts to be able to pre-hash and cache their string identifiers for quicker lookups later.

Note

This is not intended to be directly used in most situations. Typical C++ code should use CARB_LOCALIZE() and typical python code should use carb_localize() or carb_localize_hashed().

Param keyString

[in] The string to calculate the hash identifier for. This may not be nullptr or an empty string.

Return

The calculated hash of the string. This will be the same algorithm that is used by the String Table Conversion Tool to generate the table and mapping structure.

Return

0 if the input string is nullptr or empty.

const char *(*getLocalizedStringFromHash)(const LanguageTable *table, StringIdentifier id, const LanguageIdentifier *language) noexcept

Looks up a string’s translation in the localization system.

Note

This is not intended to be directly used in most situations. Typical C++ code should use CARB_LOCALIZE() and typical python code should use carb_localize() or carb_localize_hashed().

Param table

[in] The optional local language table to search first for the requested key string. If this is non-nullptr and the key string is not found in this table or the requested language is not supported by this table, the framework’s registered main table will be checked as well. This may be nullptr to only search the framework’s main table.

Param id

[in] The hashed string identifier of the string to look up.

Param language

[in] The language to retrieve the translated string in. This may be set to kLanguageCurrent to use the current language for the localization system (this is the default behavior). This can also be any specific language identifier to retrieve the string in another supported language. This may also be kLanguageDefault to retrieve the string in the system’s default language if a translation is available.

Return

The translated string is a supported language is requested and the string with the requested hash is found in the table.

Return

nullptr if no translation is found in the table, if an unsupported language is requested, or if the key string has no mapping in the table.

Return

An error message if the config setting to return noticeable failure strings is enabled.

const LanguageIdentifier *(*getSystemLanguage)() noexcept

Retrieves the current system locale information.

Return

A language identifier for the current system language if it matches one or more of the supported translation tables.

Return

The language identifier for US English if no matching translation tables are found.

const LanguageIdentifier *(*enumLanguageIdentifiers)(const LanguageTable *table, size_t index) noexcept

Enumerates available/supported language identifiers in the localization system.

Param table

[in] The optional local table to also search for unique language identifiers to return. If this is non-nullptr, the supported language identifiers in this table will be enumerated first, followed by any new unique language identifiers in the framework’s registered main table. This may be nullptr to only enumerate identifiers in the main table.

Param index

[in] The index of the language identifier number to be returned. Set this to 0 to retrieve the first supported language (this will always return the language identifier corresponding to US English as the first supported language identifier). Set this to increasing consecutive indices to retrieve following supported language codes.

Retval kLanguageUnknown

if the given index is out of range of the supported languages.

Return

The language identifier corresponding to the supported language at index index.

const LanguageIdentifier *(*getLanguageIdentifier)(const LanguageTable *table, const char *language) noexcept

Retrieves the language identifier for a given locale name.

Param table

[in] The optional local table to also search for a matching language identifier in. This may be nullptr to only search the framework’s ‘main’ table.

Param language

[in] The standard Unix locale name in the format “<language>_<territory>” where “<language>” is a two character ISO-639-1 language code and “<territory>” is a two-character ISO-3166-1 Alpha-2 territory code. An optional encoding string may follow this but will be ignored. This must not be nullptr or an empty string.

Retval kLanguageUnknown

if the requested language does not have a translation table for it in the localization system, or if the config setting to only allow exact matches is enabled and no exact language/territory match could be found.

Return

The language identifier corresponding to the selected Unix locale name if a table for the requested language and territory is found. If multiple matching supported tables are found for the requested language (ie: Canadian French, France French, Swiss French, etc), the one for the matching territory will be returned instead. If no table exists for the requested territory in the given language, the language identifier for an arbitrary table for the requested language will be returned instead. This behavior may be modified by a runtime config setting that instead causes kLanguageUnknown to be returned if no exact language/territory match exists.

const char *(*getLanguageName)(const LanguageTable *table, const LanguageIdentifier *language, LocalizedName retrieveIn) noexcept

Retrieves a language’s or territory’s name as a friendly string.

Note

This will simply return the strings in the second and third, or fourth and fifth rows of the CSV table (which should have become properties of the table once loaded).

Param table

[in] The optional local language table to check for the requested name first. If this is nullptr or the requested language identifier is not supported by the given table, the framework’s main registered table will be checked.

Param language

[in] The language identifier of the language or territory name to retrieve. This may not be kLanguageUnknown. This may be kLanguageCurrent to retrieve the name for the currently selected language.

Param retrieveIn

[in] The language to return the string in. This can be used to force the language’s or territory’s name to be returned in US English or the name of language in language.

Return

The name of the language or territory in the specified localization.

Return

An empty string if the no translation table exists for the requested language or an invalid language identifier is given.

Return

An error message if the config setting to return noticeable failure strings is enabled.

const char *(*getTerritoryName)(const LanguageTable *table, const LanguageIdentifier *language, LocalizedName retrieveIn) noexcept

Retrieves a language’s or territory’s name as a friendly string.

Note

This will simply return the strings in the second and third, or fourth and fifth rows of the CSV table (which should have become properties of the table once loaded).

Param table

[in] The optional local language table to check for the requested name first. If this is nullptr or the requested language identifier is not supported by the given table, the framework’s main registered table will be checked.

Param language

[in] The language identifier of the language or territory name to retrieve. This may not be kLanguageUnknown. This may be kLanguageCurrent to retrieve the name for the currently selected language.

Param retrieveIn

[in] The language to return the string in. This can be used to force the language’s or territory’s name to be returned in US English or the name of language in language.

Return

The name of the language or territory in the specified localization.

Return

An empty string if the no translation table exists for the requested language or an invalid language identifier is given.

Return

An error message if the config setting to return noticeable failure strings is enabled.

const char *(*getLocaleIdentifierName)(const LanguageTable *table, const LanguageIdentifier *language) noexcept

Retrieves the standard Unix locale name for the requested language identifier.

Param table

[in] The optional local language table to retrieve the locale identifier from. This may be nullptr to only search the framework’s registered main language table.

Param language

[in] The language identifier to retrieve the Unix locale name for. This may not be kLanguageUnknown. This may be kLanguageCurrent to retrieve the locale name for the currently selected language.

Return

The standard Unix locale name for the requested language identifier.

Return

an empty string if the language identifier is invalid or no translation table exist for it.

Return

an error message if the config setting to return noticeable failure string is enabled.

bool (*setCurrentLanguage)(const LanguageTable *table, const LanguageIdentifier *language) noexcept

Sets the new current language from a standard Unix locale name or language identifier.

Note

the variant that takes a string locale identifier will just be a convenience helper function that first looks up the language identifier for the locale then passes it to the other variant. If the locale lookup fails, the call will fail since it would be requesting an unsupported language.

Param table

[in] The optional local language table to check to see if the requested language is supported or not. This may be nullptr to only search the framework’s registered main table. If the local table doesn’t support the requested language, the framework’s main table will still be searched.

Param language

[in] Either the locale name or identifier for the new language to set as current for the calling process. For the string version, this may be nullptr or an empty string to switch back to the system default language. For the language identifier version, this may be set to kLanguageDefault to switch back to the system default language.

Return

true if the requested language is supported and is successfully set.

Return

false if the requested language is not supported. In this case, the current language will not be modified.

bool (*setCurrentLanguageFromString)(const LanguageTable *table, const char *language) noexcept

Sets the new current language from a standard Unix locale name or language identifier.

Note

the variant that takes a string locale identifier will just be a convenience helper function that first looks up the language identifier for the locale then passes it to the other variant. If the locale lookup fails, the call will fail since it would be requesting an unsupported language.

Param table

[in] The optional local language table to check to see if the requested language is supported or not. This may be nullptr to only search the framework’s registered main table. If the local table doesn’t support the requested language, the framework’s main table will still be searched.

Param language

[in] Either the locale name or identifier for the new language to set as current for the calling process. For the string version, this may be nullptr or an empty string to switch back to the system default language. For the language identifier version, this may be set to kLanguageDefault to switch back to the system default language.

Return

true if the requested language is supported and is successfully set.

Return

false if the requested language is not supported. In this case, the current language will not be modified.

const LanguageIdentifier *(*getCurrentLanguage)() noexcept

Retrieves the language identifier for the current language.

Retval kLanguageDefault

if an error occurs.

Return

The identifier for the current language.

bool (*setMainLanguageTable)(const LanguageTable *table) noexcept

Registers the host app’s main language translation table.

Note

This is a per-process setting.

Param table

[in] The table to register as the app’s main lookup table. This may be nullptr to indicate that no language table should be used and that only US English strings will be used by the app.

Return

true if the new main language table is successfully set.

Return

false if the new main language table could not be set.

LanguageTable *(*loadLanguageTable)(const LanguageTableData *data) noexcept

Creates a new local language translation table.

Param data

[in] The language table to load. This language table must remain valid and constant until unloadLanguageTable() is called. The intended use of this function is to load a static constant data table.

Return

The newly loaded and created language table if the data file exists and was successfully loaded. This must be destroyed with unloadLanguageTable() when it is no longer needed.

Return

nullptr if an unrecoverable error occurred.

LanguageTable *(*loadLanguageTableFromFile)(const char *fileName) noexcept

Creates a new local language translation table from a data file.

Note

The format of the localization file is as follows: byte count | segment description [0-13] | File signature. The exact UTF-8 text: “nvlocalization”. [14-15] | File format version. Current version is 00. | This version number is 2 hex characters. [16-19] | Number of languages. | This corresponds to LanguageTableData::languagesLength. [20-23] | Number of keys. | This corresponds to LanguageTableData::keysLength. [24-..] | Table of LanguageTableData::keysLength 64 bit keys. | This is LanguageTableData::keysLength * 8 bytes long. | This corresponds to LanguageTableData::keys. [..-..] | Block of LanguageTableData::languagesLength null | terminated language names. | This will contain exactly LanguageTableData::languagesLength | 0x00 bytes; each of those bytes indicates the end of a string. | The length of this segment depends on the data within it; | the full segment must be read to find the start of the | next section. | This corresponds to LanguageTableData::languages. [..-..] | Block of LanguageTableData::languagesLength * | LanguageTableData::keysLength | null terminated translations. | This will contain exactly LanguageTableData::languagesLength * | LanguageTableData::keysLength 0x00 bytes; each of those bytes | indicates the end of a string. | The last byte of the file should be the null terminator of the last | string in the file. | The length of this section also depends on the length of | the data contained within these strings. | If the end of the file is past the final 0x00 byte in this | segment, the reader will assume the file is corrupt. | This corresponds to LanguageTableData::languageTable.

Param filename

[in] The name of the data file to load as a language translation table. This may not be nullptr or an empty string. If this does not have an extension, both the given filename and one ending in “.lang” will be tried.

Return

The newly loaded and created language table if the data file exists and was successfully loaded. This must be destroyed with unloadLanguageTable() when it is no longer needed.

Return

nullptr if the data file was not found with or without the “.lang” extension, or the file was detected as corrupt while loading.

void (*unloadLanguageTable)(LanguageTable *table) noexcept

The language table to be destroyed.

Param table

[in] The language table to be destroyed. This must not be nullptr. This should be a table that was previously returned from loadLanguageTable(). It is the caller’s responsibility to ensure this table will no longer be needed or accessed.

bool (*addLanguageSearchPath)(const char *searchPath) noexcept

Sets the current search path for finding localization files for a module.

Remark

This sets the search path to use for finding localization files when modules load. By default, only the same directory as the loaded module or script will be searched. This can be used to specify additional directories to search for localization files in. For example, the localization files may be stored in the ‘lang/’ folder for the app instead of in the ‘bin/’ folder.

Param searchPath

[in] The search path for where to look for localization data files. This can be an absolute or relative path.

Return

true if the new search path is successfully set.

Return

false if the new search path could not be set.

bool (*removeLanguageSearchPath)(const char *searchPath) noexcept

Sets the current search path for finding localization files for a module.

Remark

This removes a search path added by addLanguageSearchPath(). If the same path was added multiple times, it will have to be removed multiple times.

Note

The executable directory can be removed from the search path list, if that is desired.

Param searchPath

[in] The search path to remove from the search path list.

Return

true if the search path was successfully removed.

Return

false if the search path was not found.

const char *(*enumLanguageSearchPaths)(size_t index) noexcept

Enumerate the search paths that are currently set.

Remark

The example usage of this function would be to call this in a loop where index starts at 0 and increments until a call to enumLanguageSearchPaths(index) returns nullptr. This would enumerate all search paths that are currently set. The index is no longer valid if the search path list has been modified.

Param index

[in] The index of the search path to retrieve. The first search path index will always be 0. The valid search paths are a contiguous range of indices, so the caller can pass incrementing values beginning at 0 for index to enumerate all of the search paths.

Return

The search path corresponding to index if one exists at index.

Return

nullptr if there is no search path corresponding to index.

Public Static Functions

static inline constexpr carb::InterfaceDesc getInterfaceDesc() noexcept

Returns information about this interface.

Auto-generated by CARB_PLUGIN_INTERFACE() or CARB_PLUGIN_INTERFACE_EX.

Returns

The carb::InterfaceDesc struct with information about this interface.

static inline constexpr carb::InterfaceDesc getLatestInterfaceDesc() noexcept

Returns information about the latest version of this interface.

Auto-generated by CARB_PLUGIN_INTERFACE() or CARB_PLUGIN_INTERFACE_EX.

Returns

The carb::InterfaceDesc struct with information about the latest version of this interface.