Using the translation API

This page describes both the C and C++ APIs. Read through both portions, as information may not be repeated when it maps 1:1.

C++ API

Utility functions

There are 2 utility functions as part of the translation API:

1. languageCodeToString - Converts an entry in the language code enum to a string
2. stringToLanguageCode - Converts a string representation of a language code to an enum entry

The 2 functions take a LanguageCodes enum and a C string respectively. The LanguageCodes enum defines all language codes that may be used to develop translations. They are listed in source code here.

Translation API

Translations are managed by the TranslationEngine class, part of the UI18N namespace. It has 3 member functions:

1. init - Initialises the translation engine and returns a result
2. get - Fetches and computes a translated string
3. pushVariable - Adds a variable to the engine for long-term storage
4. setCurrentLocale - Changes the current language
5. getExistingLocales - Returns a list of locales that have at least 1 translation

The init function

The init function takes a directory for the translations, as well as a language code for the default language. The language code is set as a default argument, which is equal to en_US.

The function returns an InitialisationResult enum. It looks like this:

enum UI18N_InitialisationResult
{
    UI18N_INIT_RESULT_SUCCESS,
    UI18N_INIT_RESULT_INVALID_CONFIG,
    UI18N_INIT_RESULT_INVALID_TRANSLATION,
}

You should interpret the fields like this:

1. UI18N_INIT_RESULT_SUCCESS - Success, no issues found
2. UI18N_INIT_RESULT_INVALID_CONFIG - Couldn't open the <directory>/ui18n-config.yaml file. This is considered a fatal error.
3. UI18N_INIT_RESULT_INVALID_TRANSLATION - This is returned as a warning when an invalid translation was found during the static interpolation phase

The pushVariable function

Given a string ID and a string value, pushes a variable to the translation engine for long term storage. This is not translated.

The get function

Returns a string, given a string ID.

Additionally, you can override the 1st default argument and provide an array of type std::vector<ui18nstring> for positional arguments.

You can also override the second default argument and provide a map of type ui18nmap<ui18nstring, ui18nstring>, for temporary sort-lived variables.

An empty string may be returned if a string is crafted to be empty or no translation is found.

The setCurrentLocale function

Given an argument, representing a new locale, changes the current locale to the new one.

The getExistingLocales function

Returns a list of locales that have at least 1 translation present.

C API

The C API is similar to the C++ API, except that all functions are prefixed with UI18N_ and methods of the TranslationEngine class are prefixed with UI18N_TranslationEngine.

Creating a translation engine object

To create a translation engine object, call the UI18N_TranslationEngine_Construct function. It will return a pointer to a translation engine. You can pass the handle as the first argument to run the other methods.

Since it is heap-allocated, make sure to free the pointer data using the UI18N_TranslationEngine_Free function.

UI18N_TranslationEngine_get function

Unlike the C++ API, this function takes completely different arguments:

1. TranslationEngine handle
2. Translation ID as a C string
3. char** pargv and int pargc - An array of strings for positional arguments and its size. Set both to 0 to not set them.
4. UI18N_Pair* argv and size_t argc - A map of strings for pushing short-lived temporary variables

The UI18N_Pair struct looks like this:

struct UI18N_Pair
{
    char* key;
    char* val;
};