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:
languageCodeToString
- Converts an entry in the language code enum to a stringstringToLanguageCode
- 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:
init
- Initialises the translation engine and returns a resultget
- Fetches and computes a translated stringpushVariable
- Adds a variable to the engine for long-term storagesetCurrentLocale
- Changes the current languagegetExistingLocales
- 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:
UI18N_INIT_RESULT_SUCCESS
- Success, no issues foundUI18N_INIT_RESULT_INVALID_CONFIG
- Couldn't open the<directory>/ui18n-config.yaml
file. This is considered a fatal error.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:
TranslationEngine
handle- Translation ID as a C string
char** pargv
andint pargc
- An array of strings for positional arguments and its size. Set both to 0 to not set them.UI18N_Pair* argv
andsize_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;
};