= Language =

== Description ==

Language is a [wiki:Singleton] that handles strings in different languages. It replaces hardcoded strings by labeled strings, where the coder only uses the label and the Language searches for the localised string in the [wiki:ConfigValueContainer configured] language-file. Every string has a fallback-value that is used if there is no localised version or no language was configured. The language can be configured by changing the ''language_'' entry in the [wiki:ConfigValueContainer config-file].

A new language-entry can be added with the !AddLanguageEntry(label, fallbackstring) macro and the localisation can be retrieved with !GetLocalisation(label).

All labels and the corresponding fallback strings are written to ''translation_default.lang''. If the fallback-string gets changed in the code, ''translation_default.lang'' changes too. If a new label gets added in the code, it gets added to ''translation_default.lang''. You can't change labels or fallback-strings in this file, it will be set back to the default. You can use ''translation_default.lang'' as a sample for a new language file. See [wiki:Language#Addinganewlanguage the chapter at the end] for more information about this.

== Macros ==

 * '''!AddLanguageEntry('''''label''''', '''''fallbackstring''''')''': Adds a new entry to the Language by defining a unique label and a fallback string that gets used in case there is no localisation.
 * '''!GetLocalisation('''''label''''')''': Returns the localisation of the given label.

== Functions ==

 * '''getLanguage()''': Returns a reference to the only existing instance of the Language class.
 * '''addEntry('''''label''''', '''''fallbackstring''''')''': Adds a new entry to the Language by defining a unique label and a fallback string that gets used in case there is no localisation.
 * '''getLocalisation('''''label''''')''': Returns the localisation of the given label.

== Example ==

Piece of code:
{{{
#!cpp
// Displays the users age
int age = 20;
AddLanguageEntry("user_age", "Age");
std::cout << GetLocalisation("user_age") << ": " << age << std::endl;
}}}

Extract of translation_default.lang:
{{{
user_age=Age
}}}

Extract of translation_german.lang:
{{{
user_age=Alter
}}}

Extract of orxonox.ini:
{{{
language_="german"
}}}

Resulting output:
{{{
Alter: 20
}}}

== Adding a new language ==

Simply copy ''translation_default.lang'' and rename it to ''translation_'''''xxxxx'''''.lang'' where ''xxxxx'' is the name of your new language. Then translate all entries in the file.

An entry has the following form:
{{{
label=fallback string
}}}

Change it to:
{{{
label=translated string
}}}

Now you can change the config-value ''language_'' to "''xxxxx''" in orxonox.ini. The translated entries should now be used in the game.

'''Attention''': Language entries are only added to the file if they are at least once executed. Otherwise you wont find them in the file. If you need a complete translation, you have to search the code for all entries. If you know a better solution, just tell me. ;)