# Language

Interface to handle translations inside C++ code.
This library handles translations created with the innovaphone translator (application type App C++).

## File information

File | common/lib/language.h
Classes | Language
Data types | LanguageTableEntry language_param_type_t
Examples | Example

# Classes

## Language

    class Language {
    public:
        static int GetLanguageId(const char * lang, LanguageTableEntry languages[], int numLangs, int defaultLang);;
        static size_t ReplaceArgs(const char * translatedString, char * buffer, size_t bufferLen, ...);;
    };

### Public functions

GetLanguageId (static function)

  This functions returns the array index (language id) of the lang parameter inside the languages array.

  #### Parameters

  const char * lang | A `const char` pointer to the currently used language, e.g. 'en' or 'eng'.
  LanguageTableEntry languages[] | An array which holds all available language table entries.
  int numLangs | The number of array elements inside languages[].
  int defaultLang | defaultLang is returned, if lang can't be found.

  #### Return value

  The language array index if found or otherwise defaultLang.

ReplaceArgs (static function)

  This function replaces dynamic arguments inside a translated string. A dynamic argument is a string like $1, $2, ... (starting with 1). The arguments are handed by specifying their type and their value always as two function parameters. You can hand as many parameters as you want.

  #### Parameters

  const char * translatedString | The already translated string with dynamic arguments, e.g. 'This argument has a size of $1.'
  char * buffer | The output buffer, which will be null terminated.
  size_t bufferLen | The length of the output buffer.
  language_param_type_t type | The parameter type of the following function parameter.
  ? param | The parameter with a type which must be one of language_param_type_t.
  More duos of language_param_type_t + param, in case of LANGUAGE_PARAM_TYPE_DOUBLE four parameters (1. LANGUAGE_PARAM_TYPE_DOUBLE, 2. the precision as 32bit integer, 3. char delimiter, 4. the double value)

  #### Return value

  The length of the string inside the buffer.

# Data types

## LanguageTableEntry

    typedef struct {
        const char * lang;              // two char language identifier, e.g. 'en' or 'de'
        const char * utf8;              // the language name in utf8
        const char * langIso639_2;      // three char language identifier after ISO 639-2, e.g. 'eng' or 'deu'
    } LanguageTableEntry;

### Overview

The `struct LanguageTableEntry` holds information about one language.

## language_param_type_t

    typedef enum {
        LANGUAGE_PARAM_TYPE_STRING = 0,
        LANGUAGE_PARAM_TYPE_UINT32,
        LANGUAGE_PARAM_TYPE_INT32,
        LANGUAGE_PARAM_TYPE_UINT64,
        LANGUAGE_PARAM_TYPE_INT64,
        LANGUAGE_PARAM_TYPE_DOUBLE
    } language_param_type_t;

### Overview

The `enum language_param_type_t` specifies all possible parameter types for the function ReplaceArgs.

# Code Example

### Example cpp file app_languages.cpp created by the innovaphone translator

    #include "platform/platform.h"
    #include "common/lib/language.h"
    #include "app_languages.h"

    LanguageTableEntry myLanguageTable[] =  {
    	{ "en", "English", "eng" },
    	{ "de", "Deutsch", "deu" },
    };

    myStringTableEntry myStringTable[] =  {
    	{{	/*   1 - APP_TXT_TEST */
    		/* 1-en */ "This is a test.",
    		/* 2-de */ "Das ist ein Test.",
    	}},
    	{{	/*   1 - APP_TXT_TEST2 */
    		/* 1-en */ "This is a test with $1 arguments inside $2 und einem Double-Wert $3.",
    		/* 2-de */ "Das ist ein Test mit $1 Argumenten in $2 and a double value $3.",
    	}},
    };

### Example h file app_languages.h created by the innovaphone translator

    #define APP_LANGUAGE_EN 0
    #define APP_LANGUAGE_DE 1
    #define APP_NUM_LANGUAGES 2

    typedef struct { const char * lang[APP_NUM_LANGUAGES]; } appStringTableEntry;

    extern LanguageTableEntry appLanguageTable[APP_NUM_LANGUAGES];
    extern appStringTableEntry appStringTable[];

    #define APP_TXT_TEST    0
    #define APP_TXT_TEST2   1

    #define APP_COUNT_TXT_ITEMS 2

    #define APP_LANG_STRING(stringId, langId)     appStringTable[stringId].lang[langId]

### Usage

    int langId = Language::GetLanguageId("de", appLanguageTable, APP_NUM_LANGUAGES, APP_LANGUAGE_EN);
    const char * str = APP_LANG_STRING(APP_TXT_TEST, langId);
    size_t bufferLen = strlen(str) + strlen("R2D2") + 20; // +20 => unsigned int + terminating zero
    char * buffer = (char *)alloca(bufferLen);
    Language::ReplaceArgs(str, buffer, bufferLen,
    LANGUAGE_PARAM_TYPE_UINT32, 2,
    LANGUAGE_PARAM_TYPE_STRING, "R2D2",
    LANGUAGE_PARAM_TYPE_DOUBLE, (dword)2, ',', 25.55555);    // take care to hand the wished precision too!
    debug->printf("%s", str);           // will print "Das ist ein Test mit $1 Argumenten in $2 und einem Double-Wert $3."
    debug->printf("%s", buffer);        // will print "Das ist ein Test mit 2 Argumenten in R2D2 und einem Double-Wert 22,55."