The i18n module provides tools for implementing i18n and m17n features.
Enabling the i18n module
To enable the i18n module, you can either hard-code the USE_I18N_MODULE
option in your CMakeLists.txt
file by finding the following line:
option(USE_I18N_MODULE "Use the i18n module" OFF)
and modifying the line to look like this:
option(USE_I18N_MODULE "Use the i18n module" ON)
Alternatively, you can also generate your project files using CMake options by running the following CMake command:
cmake .. -DCMAKE_BUILD_TYPE=RELEASE -DUSE_I18N_MODULE=ON
Finally, update your uvproj.yaml
so that the locale
key under enabled-modules
is set to true like this:
name: "MyProject"
version: "1.0.0.0"
engine-version: "1.0.0.0"
enabled-modules:
i18n: true
Next, in your source file, include the Modules.hpp
header in your components like this:
#include <Modules/Modules.hpp>
Event safety
The entire module is flagged as event safe at post-begin
Using the module
Defining your strings for translation
First we need to define what strings we want to translate, to do this modify your Config/Translations/translation-base.yaml
file. It should look like this:
origin-locale: "en_US"
strings:
- "Add strings as members of the array here!"
under the strings array, put any string you want to translate
Adding translations
To add a translation simply add a file under the Config/Translations/
folder with the standard locale naming scheme, i.e. bg_BG.yaml
for Bulgarian, de_DE.yaml
for German, etc
The file should have the following scheme:
strings:
- string: "The quick brown fox jumps over the lazy dog"
translation: "Бързата кафява лисица прескача над мързеливото куче"
Where every translation is an element of the strings
array and starts with the key
being the original string in the translation base, and the value being the new key. If a string from the translation base does not exist, the module automatically uses the base string.
Interacting with the module interface
The i18n module is under the I18N
class. It looks like this:
class I18N
{static constexpr const char* getLocaleName(LocaleTypes types, bool bShort = true) noexcept;
static LocaleTypes getLocaleID(const FString& str) noexcept;
static const FString& getLocaleString(const FString& original, LocaleTypes locale) noexcept;
static LocaleTypes& getCurrentLayout() noexcept;
static LocaleTypes& getFallbackLayout() noexcept;
};
String/LocaleType conversion
The getLocaleName
function returns the string representation of a LocaleTypes
enum. The second argument, bShort
defaults to true
and if enabled returns a short locale name, while if false returns a long locale name that you can use for UI.
The getLocaleID
function converts a locale string in short form to a LocaleTypes
enum
Layouts
The getCurrentLayout
function returns a reference to the currently selected translation locale, modifying the value changes the current translation locale. The getFallbackLayout
function returns a reference to the currently selected fallback translation locale, when a translation isn't found in the current layout, we search the fallback layout for it.
Getting localized strings
To get localized strings, simply call the getLocaleString
function. There are 2 definitions, both return a constant reference to a string and both receive an initial string. The first defaults to the current layout, while in the second you can also provide an override locale.
Additional locale operations
This interface is only used for dealing with translations of your application, however the C++ standard library provides a lot of utility functions and classes under the locale
library. When you enable the i18n module, we already include it for you. Check out the reference here.
Converting between layout schemes and definitions
Coming soon!
Checking for the module
To check for the module at compile time, use the UIMGUI_I18N_MODULE_ENABLED
macro.
Runtime checking can be done using the i18n
member of the ModuleSettings
struct. More info can be found here.
- Home
- Beginner content
- Install guide
- Creating and using the UI components
- The Instance
- The Init Info struct
- Additional features
- Custom type definitions
- C API development
- Config files and Folders
- Interfaces
- Internal Event safety
- Modules system
- I18N
- Plotting
- Knobs
- Spinners
- Toggles
- Text Utils
- Undo/Redo
- CLI Parser
- Theming
- OS
- Opening URLs and using file pickers
- Exec integration
- Fonts
- Unix
- DBus utilities
- XDG integration
- Collaborating with others
- Advanced content
- Loading dynamic libraries at runtime
- Understanding the library layout
- Compilation mode modifiers
- Adding plugin support to your application
- Production export and deployment
- Developer and contributor resources
- Misc