Translations, Internationalization (I18N)

POEditor

The online translation service poeditor.com has been integrated with UltraStar Play to help contributors translate the project.

It provides a clean web UI, quality checks, and semi-automatic translation. When using POEditor, you do not need to care about translation file formats because POEditor hides these implementation details.

Use POEditor to

• translate the UltraStar Play game
• translate the UltraStar Play website

Of course, using poeditor.com to translate UltraStar Play is free for you.

In case you do not want to use POEditor and instead want to edit the raw translation files, then read on.

Translate UltraStar Play website

Internationalization for the UltraStar website has been prepared using .yml files.

The files are located in ultrastar-play.github.io/public/locales/

Behind the scenes, next-i18next uses these files to generate static HTML pages for every language.

To add a new language, the file next-i18next.config.js needs to be edited, more specifically the locales array.

Translate UltraStar Play game and Companion App

Internationalization for the UltraStar Play game and Companion App has been prepared using .properties files, which are well known in Java projects.

The files are located in UltraStar Play/Packages/playshared/Runtime/Resources/Translations

Note that the main game and Companion App use the same files.

Properties file format

Properties files contain key-value pairs (e.g. mainScene_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.

Add a language

Add a properties file with the translations. Name the file using the corresponding two letter country code as suffix.

The game will load the new file after restart such that the new language will be available.

Using translations from code

Handling strings can be a tricky task because the compiler cannot check for typos etc. Furthermore refactoring, find references, and similar coding tools do not work well with strings. This is why the R.String class holds the name of all translation properties in handy C# fields. The approach has been inspired by Android's R class.

The R class is generated via the menu item R class > Create all C# constants. Note that only the translation 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

mainScene_button_hello = "Hello world!"

will result in

public static partial class R {
    public static class String {
        public static readonly string mainScene_button_hello = "mainScene_button_hello";
    }
}

that can be used as follows

public class MyCoolScript : MonoBehaviour, INeedInjection
{
    void Start()
    {
        string translatedText = I18NManager.GetTranslation(R.String.mainScene_button_hello);
        Debug.Log(translatedText);
    }
}

Using translations in the UI

• The I18NManager (one of the CommonSceneObjects) has a button in the Inspector to reload all translations 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).

UIToolkit

• Implement the ITranslator interface.
  • The I18NManager will call this method to update translations
• For an example see MainSceneUiControl

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 R class by using the corresponding menu item in the Unity Editor.