Utility class to translate strings for display in GUI. More...

#include <gui_localizer.hpp>

Public Member Functions
	localizer ()
	Default constructor. More...

	localizer (const localizer &)=delete

	localizer (localizer &&)=delete

localizer &	operator= (const localizer &)=delete

localizer &	operator= (localizer &&)=delete

void	set_locale (const std::locale &locale)
	Changes the current locale (used to format numbers). More...

void	set_preferred_languages (const std::vector< std::string > &languages)
	Changes the current language (used to translate messages and strings). More...

void	auto_detect_preferred_languages ()
	Attempts to automatically detect the current language (used to translate messages and. More...

const std::locale &	get_locale () const
	Returns the current locale (used to format numbers). More...

const std::vector< std::string > &	get_preferred_languages () const
	Returns the list of code names of the preferred languages (used to translate messages and. More...

void	clear_allowed_code_points ()
	Removes all allowed code points. More...

void	add_allowed_code_points (const code_point_range &range)
	Adds a new range to the set of allowed code points. More...

void	add_allowed_code_points_for_group (const std::string &unicode_group)
	Adds a new range to the set of allowed code points from a Unicode group. More...

void	add_allowed_code_points_for_language (const std::string &language_code)
	Adds a new range to the set of allowed code points for a given language. More...

void	auto_detect_allowed_code_points ()
	Attempts to automatically detect the set of allowed code points based on preferred. More...

const std::vector< code_point_range > &	get_allowed_code_points () const
	Returns the list of allowed code points (Unicode characters), for text rendering. More...

void	set_fallback_code_point (char32_t code_point)
	Sets the default character to display if a character is missing from a font. More...

char32_t	get_fallback_code_point () const
	Returns the default character to display if a character is missing from a font. More...

void	load_translations (const std::string &folder_path)
	Loads new translations from a folder, selecting the language automatically. More...

void	load_translation_file (const std::string &file_name)
	Loads new translations from a file. More...

void	clear_translations ()
	Removes all previously loaded translations. More...

std::string	format_string (std::string_view message, sol::variadic_args args) const
	Translates a string with a certain number of arguments from Lua (zero or many). More...

template<typename... Args>
std::string	format_string (std::string_view message, Args &&... args) const
	Translates a string with a certain number of arguments from C++ (zero or many). More...

std::string	localize (std::string_view key, sol::variadic_args args) const
	Translates a string with a certain number of arguments from Lua (zero or many). More...

template<typename... Args>
std::string	localize (std::string_view key, Args &&... args) const
	Translates a string with a certain number of arguments from C++ (zero or many). More...

void	register_on_lua (sol::state &lua)
	Registers this localizer on a Lua state. More...

Detailed Description

Utility class to translate strings for display in GUI.

Definition at line 20 of file gui_localizer.hpp.

Constructor & Destructor Documentation

◆ localizer() [1/3]

lxgui::gui::localizer::localizer ( )

Default constructor.

Definition at line 79 of file gui_localizer.cpp.

◆ localizer() [2/3]

lxgui::gui::localizer::localizer ( const localizer & )

delete

◆ localizer() [3/3]

lxgui::gui::localizer::localizer ( localizer && )

delete

Member Function Documentation

◆ add_allowed_code_points()

void lxgui::gui::localizer::add_allowed_code_points ( const code_point_range & range )

Adds a new range to the set of allowed code points.

Parameters

range The new range to allow

See also: get_allowed_code_points()

Definition at line 149 of file gui_localizer.cpp.

◆ add_allowed_code_points_for_group()

void lxgui::gui::localizer::add_allowed_code_points_for_group ( const std::string & unicode_group )

Adds a new range to the set of allowed code points from a Unicode group.

Parameters

unicode_group The name of the Unicode code group to allow

Note: The Unicode standard defines a set of code groups, which are contiguous ranges of Unicode code points that are typically associated to a language or a group of languages. This function knows about such groups and the ranges of code point they correspond to, and is therefore more user-friendly.

See also: get_allowed_code_points()

Definition at line 184 of file gui_localizer.cpp.

◆ add_allowed_code_points_for_language()

void lxgui::gui::localizer::add_allowed_code_points_for_language ( const std::string & language_code )

Adds a new range to the set of allowed code points for a given language.

Parameters

language_code The language code (e.g., "en", "ru", etc.)

Note: Language codes are based on the ISO-639-1 standard, or later standards for those languages which were not listed in ISO-639-1. They are always in lower case, and typically composed of just two letters, but sometimes more.

See also: get_allowed_code_points()

Definition at line 464 of file gui_localizer.cpp.

◆ auto_detect_allowed_code_points()

void lxgui::gui::localizer::auto_detect_allowed_code_points ( )

Attempts to automatically detect the set of allowed code points based on preferred.

languages.

Note: This is called in the constructor, only use it if you need to reset the allowed code points to the default after changing the preferred languages.

Definition at line 670 of file gui_localizer.cpp.

◆ auto_detect_preferred_languages()

void lxgui::gui::localizer::auto_detect_preferred_languages ( )

Attempts to automatically detect the current language (used to translate messages and.

strings).

Note: This is called in the constructor, only use it if you need to reset the languages to the default after calling set_preferred_languages().

Definition at line 133 of file gui_localizer.cpp.

◆ clear_allowed_code_points()

void lxgui::gui::localizer::clear_allowed_code_points ( )

Removes all allowed code points.

See also: get_allowed_code_points()

Definition at line 145 of file gui_localizer.cpp.

◆ clear_translations()

void lxgui::gui::localizer::clear_translations ( )

Removes all previously loaded translations.

Note: After calling this function, it is highly recommended to always include at least the Unicode groups "basic latin" (to render basic ASCII characters) and "geometric shapes" (to render the "missing character" glyph).

Definition at line 769 of file gui_localizer.cpp.

◆ format_string() [1/2]

template<typename... Args>

std::string lxgui::gui::localizer::format_string	(	std::string_view	message,
		Args &&...	args
	)		const

inline

Translates a string with a certain number of arguments from C++ (zero or many).

Parameters

message	The string to format (e.g., "Player {0} has {1} HP.").
args	A variadic list of formatting input arguments.

Returns: The formatted string.

The string to format must follow the rules of libfmt format strings.

Definition at line 197 of file gui_localizer.hpp.

◆ format_string() [2/2]

std::string lxgui::gui::localizer::format_string	(	std::string_view	message,
		sol::variadic_args	args
	)		const

Translates a string with a certain number of arguments from Lua (zero or many).

Parameters

message	The string to format (e.g., "Player {0} has {1} HP.").
args	A variadic list of formatting input arguments from a Sol Lua state.

Returns: The formatted string.

The string to format must follow the rules of libfmt format strings.

Definition at line 782 of file gui_localizer.cpp.

◆ get_allowed_code_points()

const std::vector< code_point_range > & lxgui::gui::localizer::get_allowed_code_points ( ) const

Returns the list of allowed code points (Unicode characters), for text rendering.

Returns: The list of allowed code points.

Note: The list contains no duplicate or overlapping ranges. The ranges are sorted by increasing code point value. This list is used by the font system to pre-render all the characters that are allowed on the GUI, to allow for more efficient rendering and batching. Code points or characters not on this list will not be rendered, or will be replaced by a placeholder character.

Definition at line 691 of file gui_localizer.cpp.

◆ get_fallback_code_point()

char32_t lxgui::gui::localizer::get_fallback_code_point ( ) const

Returns the default character to display if a character is missing from a font.

Returns: The default character to display if a character is missing from a font

Definition at line 699 of file gui_localizer.cpp.

◆ get_locale()

const std::locale & lxgui::gui::localizer::get_locale ( ) const

Returns the current locale (used to format numbers).

Returns: The current locale.

Definition at line 137 of file gui_localizer.cpp.

◆ get_preferred_languages()

const std::vector< std::string > & lxgui::gui::localizer::get_preferred_languages ( ) const

Returns the list of code names of the preferred languages (used to translate messages and.

strings).

Returns: The list of code name of the preferred languages.

Definition at line 141 of file gui_localizer.cpp.

◆ load_translation_file()

void lxgui::gui::localizer::load_translation_file ( const std::string & file_name )

Loads new translations from a file.

Parameters

file_name The path to the file to load translations from

Note: The file must be a Lua script. It will be loaded in a sandboxed Lua state (independent of the Lua state of the GUI). The script must define a table called "localize", which will be scanned to add new translations for the current locale (each file must only contain translations for one language; separate different languages into different files). Each item of the table must have a string key identifying the localized content, e.g., "player_health". This key must be the same for all languages, and serves to uniquely identify the translatable sentence / text. The format of this string is arbitrary. The value of each element must be either a string, of a function. If the value is a string, it must be a fmtlib format string. For example: "{0:L} HP" expects one input argument (here a number representing the player's health). If the value of this argument is 5000 and the locale is enUS, this will result in "5,000 HP". If the value is a Lua function, it must take the same number of input values in all languages, and must return a translated string. See localize() for more information on translation arguments.

Definition at line 736 of file gui_localizer.cpp.

◆ load_translations()

void lxgui::gui::localizer::load_translations ( const std::string & folder_path )

Loads new translations from a folder, selecting the language automatically.

Parameters

folder_path The path to the folder to load translations from

Note: Based on the current language (see get_language()), this function will scan files in the supplied folder with name "{language}{REGION}.lua", and pick the combination of "language" and "REGION" closest to the currently configured language. It then loads translations from this file using load_translation_file() (see the documentation of this function for more information).

Definition at line 703 of file gui_localizer.cpp.

◆ localize() [1/2]

template<typename... Args>

std::string lxgui::gui::localizer::localize	(	std::string_view	key,
		Args &&...	args
	)		const

inline

Translates a string with a certain number of arguments from C++ (zero or many).

Parameters

key	The key identifying the sentence / text to translate (e.g., "{player_health}"). Must start with '{' and end with '}'.
args	A variadic list of translation input arguments.

Returns: The translated string, or key if not found or an error occurred.

This function will search the translation database (created from loading translations with load_translations() or load_translation_file()) for a string matching key. If one is found, it will forward the supplied arguments to the translated formatting function, which will insert the arguments at the proper place for the selected language.

Definition at line 224 of file gui_localizer.hpp.

◆ localize() [2/2]

std::string lxgui::gui::localizer::localize	(	std::string_view	key,
		sol::variadic_args	args
	)		const

Translates a string with a certain number of arguments from Lua (zero or many).

Parameters

key	The key identifying the sentence / text to translate (e.g., "{player_health}"). Must start with '{' and end with '}'.
args	A variadic list of translation input arguments from a Sol Lua state.

Returns: The translated string, or key if not found or an error occurred.

Note: See the other overload for more information.

Definition at line 803 of file gui_localizer.cpp.

◆ operator=() [1/2]

localizer& lxgui::gui::localizer::operator= ( const localizer & )

delete

◆ operator=() [2/2]

localizer& lxgui::gui::localizer::operator= ( localizer && )

delete

◆ register_on_lua()

void lxgui::gui::localizer::register_on_lua ( sol::state & lua )

Registers this localizer on a Lua state.

Parameters

lua	The Lua lua to register on

Note: Only one localizer object can be registered on any Lua state. Registering enables Lua functions such as "get_locale()".

◆ set_fallback_code_point()

void lxgui::gui::localizer::set_fallback_code_point ( char32_t code_point )

Sets the default character to display if a character is missing from a font.

Parameters

code_point The Unicode UTF-32 code point of the character to display

Definition at line 695 of file gui_localizer.cpp.

◆ set_locale()

void lxgui::gui::localizer::set_locale ( const std::locale & locale )

Changes the current locale (used to format numbers).

Parameters

locale The new locale

Note: This function should only be called before the UI is loaded. If you need to change the locale after the UI has been loaded: close the UI, set the locale, and load the UI again.

Definition at line 110 of file gui_localizer.cpp.

◆ set_preferred_languages()

void lxgui::gui::localizer::set_preferred_languages ( const std::vector< std::string > & languages )

Changes the current language (used to translate messages and strings).

Parameters

languages A list of languages

This function specifies which languages to use for translating messages. The languages listed in the supplied array will be tried one after the other, until a translation is found. Each language in the list must be formatted as "{language}{REGION}" with "{language}" a two-letter lower case word, and "{REGION}" a two-letter upper case word. For example: "enUS" for United State English, and "enGB" for British English, "frFR" for mainland French, etc. The default value is {"enUS"}.

Note: This function should only be called before the UI is loaded. If you need to change the language after the UI has been loaded: close the UI, set the language, and load the UI again.

Definition at line 118 of file gui_localizer.cpp.

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

/home/runner/work/lxgui/lxgui/include/lxgui/gui_localizer.hpp
/home/runner/work/lxgui/lxgui/src/gui_localizer.cpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ localizer() [1/3]

◆ localizer() [2/3]

◆ localizer() [3/3]

Member Function Documentation

◆ add_allowed_code_points()

◆ add_allowed_code_points_for_group()

◆ add_allowed_code_points_for_language()

◆ auto_detect_allowed_code_points()

◆ auto_detect_preferred_languages()

◆ clear_allowed_code_points()

◆ clear_translations()

◆ format_string() [1/2]

◆ format_string() [2/2]

◆ get_allowed_code_points()

◆ get_fallback_code_point()

◆ get_locale()

◆ get_preferred_languages()

◆ load_translation_file()

◆ load_translations()

◆ localize() [1/2]

◆ localize() [2/2]

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ register_on_lua()

◆ set_fallback_code_point()

◆ set_locale()

◆ set_preferred_languages()