Translations, Internationalization (I18N)

Internationalization has been prepared using '.properties' files, which are often used in Java projects.

Properties files

Properties files contain key-value pairs (e.g. main_scene.button.hello = Hello world!)

Properties files are named by convention without additional suffix for the default properties file (typically with English translation). For other languages, a suffix with a two letter country code is added to the file name. For example, there is messages.properties for the (default) English texts and messages_de.properties for the German texts.

If a translation for a key is missing or there is no properties file for the current language, then the default from the properties file without two letter language code suffix is used. Thus, the fallback will be the English text.

Using I18NKeys from code

Handling strings can be a tricky task because the compiler cannot check that there is no typo in the I18N property you want to query. Furthermore refactoring, find references, and similar coding tools do not work well with strings. This is why the MenuItem I18N > Create C# constants for I18N properties creates the class I18NKeys. This class simply holds the string name of all I18N properties in handy C# fields. The approach has been inspired by Android's R class.

You should use the fields in I18NKeys when querying a translation. Note that only the I18N keys from the default properties file are available. This is on purpose to force everyone to provide a fallback translation in English.

Example:

In messages.properties

say_hello = "Hello world!"

will result in

public static class I18NKeys {
    public static readonly string say_hello = "say_hello";
}

that can be used as follows

public class MyCoolScript : MonoBehaviour, INeedInjection
{
    [Inject]
    private I18NManager i18nManager;

    void Start()
    {
        string translatedText = i18nManager.GetTranslation(I18NKeys.say_hello);
        Debug.Log(translatedText);
    }
}

Using translations in the UI

Using translations is demonstrated in the I18NDemoScene.

• Add the I18NText script to a GameObject with a Text component and specify the key for the text that should be displayed.
  • Note that the dropdown for the key in the inspector shows the fields of the I18NKeys class
• If the string has parameters, then create a script that extends I18NText and overwrite GetTranslationArguments.
• An I18NText has a button in the Inspector to reload its translation.
• The I18NManager has a button in the Inspector to reload all translations of I18NText instances in the current scene.
• For debugging, the I18NManager has a checkbox in the Inspector to use a different langauge than the system language (this option is only respected when running the game inside the Unity Editor).

Contributing translations

Take a look at the I18N-README.txt file in the repository if you want to edit or contribute translations.

If you add new translations to the original properties file, then do not forget to update the I18NKeys class by using the corresponding menu item in the Unity Editor.