__FORCETOC__
[[SourceMod]], like its AMX Mod X predecessor, contains a built-in Multi-Lingual Translation layer ("ML"). The ML system is one of the secondary SourceMod systems designed to make the platform as flexible as possible. It fully supports UTF-8.

=Introduction=
The SourceMod ML System is based off the following terms:
*'''Languages''': Preset languages defined in <tt>configs\languages.cfg</tt>. If a language is not in this file, it <b>cannot be translated</b> until it is added and the in-memory translation cache rebuilt.
*'''Phrases'''/'''Translation Keys''': Short, generic key phrases used to identify a set of translations. These reside in configuration files in the <tt>translations</tt> folder. These are called <tt>translation files</tt>.
*'''Translations''': A given text translation of a phrase for a given language. These reside in a <tt>translation file</tt>.

'''Note''': Languages and Phrases are both case sensitive.

==File Format==
The ML Translation File format is in standard Valve configuration form. It is comprised of one master section, <tt>"Phrases</tt>,<tt>"</tt> which contains any number of named sub-sections. Each sub-section defines one named <tt>Phrase</tt>, which cannot itself have sub-sections. It allows the following properties:
*'''Key''': "#format"
**'''Value''': Comma-delimited, ordered pairs of indexes and format strings.
*'''Key''': Two-letter language code.
**'''Value''': Language translation string.

Example:
<pre>"Phrases"
{
"Welcome"
{
"en" "Welcome to SourceMod"
"es" "Bienvenidos a SourceMod"
}
}</pre>

In the above example, two translations are defined for the "Welcome" phrase - one for English, and one for Spanish. However, consider a phrase which needs certain words inserted, as in this contrived example:
<pre>"Phrases"
{
"Pants"
{
"en" "pants"
"es" "pantalones"
}
//INVALID EXAMPLE: "Bail's pants are on fire"
"OnFire_plural"
{
"en" "%s's %s are on fire!"
"es" "¡Los %s de %s están en llamas!"
}
}</pre>

In the above example, the word orders have changed. English inserts the subject first, and the direct object second. Spanish associates ownership differently -- literally, ''the pants of Bail are on fire.'' This poses a problem for scripters, who always pass format parameters in one order. To solve this, the <tt>#format</tt> property was introduced. This pre-defines the order of format parameters. Example:
<pre>"Phrases"
{
//Example: "Bail's pants are on fire"
"OnFire_plural"
{
"#format" "{1:s},{2:s}"
"en" "{1}'s {2} are on fire!"
"es" "¡Los {2} de {1} están en llamas"
}
//Example: "Hello, Bail!"
"Hello"
{
"#format" "{1:s}"
"en" "Hello, {1}"
"es" "Hola, {1}"
}
}</pre>

The format string is comprised of comma delimited sections, each section enclosed in brackets. Each section has an ''index'' and a ''format specifier'', which are separated with a colon. Format specifiers follow the general rules of [[Format Class Functions (SourceMod Scripting)|formatting]], however, only the following types are currently allowed:
*'''d'''/'''i''': Digits/Integer display
*'''x''': Hexadecimal display
*'''f''': Floating point display
*'''s''': String display
*'''c''': Character display (UTF-8 compatible)

Note that currently, the special "%T" format type is not allowed inside a language translation string. but you still can use %t inside the format string

=Usage in a Plugin=
Plugins must call <tt>LoadTranslations</tt> on each translation file they wish to use. Failure to do so will cause any translations to fail, even if another plugin loads the same file. This is to help prevent phrase-clashes between plugins.

'''Note''': Language files are reloaded every mapchange. Even if the plugin gets reloaded, the translation file stays cached until next map.

Inline translation works in any [[Format Class Functions (SourceMod Scripting)|format-class]] of functions. A new format specifier, '%T', is introduced, which instructs the format routine to insert a translated phrase. Unlike all other format specifiers, this requires a minimum of two parameters:
*'''1st Parameter''': A string containing the phrase to be translated.
*'''2nd Parameter''': One of the following:
**The <tt>LANG_SERVER</tt> constant, which specifies a translation to the default language.
**A player ID constant, which specifies a translation to the player's set language.
*'''3rd Parameter and higher''': Inputs into the phrase's format specifiers, if necessary.

Examples of this are:
<pawn>new String:name[32], String:buffer[128];
GetClientName(client, name, sizeof(name));
PrintToChat(client, "[SourceMod] %T", "Hello", client, name);
Format(buffer, sizeof(buffer), "[SourceMod] %T", "Hello", LANG_SERVER, name);</pawn>

A breakdown of the format parameters:
*<tt>"Hello"</tt>: The phrase to translate.
*<tt>client/LANG_SERVER</tt>: Who to translate the phrase to.
*<tt>name</tt>: The "Hello" phrase requires one string, so this will appear in the translated phrase.

Lastly, there is a second form of inline translation, using '%t'. This is only allowed in functions which act directly on one or more clients. It eliminates the second parameter, and uses the original client specified. Example:
<pawn>PrintToChat(client, "[SourceMod] %t", "Hello", name);</pawn>

As you can see from this example, we did not have to specify the client index more than once. Thus, it is usually more convenient to use the limited '%t' version in functions such as <tt>PrintToChat</tt>. However, in functions which are not "player directed," such as <tt>Format</tt> or <tt>PrintToServer</tt>, only '%T' can be used.

=Distributing Language Files=
As of SourceMod 1.1, there is a new preferred method of shipping translations. By default, the main translation file should only contain English phrases. Additional translations are made in separate files, under a folder named after the ISO language code in <tt>languages.cfg</tt>.

For example, <tt>translations/stuff.phrases.txt</tt> might contain this:
<pre>"Phrases"
{
//Example: "Hello, Bail!"
"Hello"
{
"#format" "{1:s}"
"en" "Hello, {1}"
}
}</pre>

A user who translates this to Spanish would create <tt>translations/es/stuff.phrases.txt</tt>:
<pre>"Phrases"
{
//Example: "Hello, Bail!"
"Hello"
{
"es" "Hola, {1}"
}
}</pre>

This system makes maintaining and checking the validity of files much easier.

[[Category:SourceMod Scripting]]

{{LanguageSwitch}}