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.