Translations, Internationalization (I18N) - UltraStar-Deluxe/Play GitHub Wiki

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);
    }
}

UI Toolkit

  • Use translation key with $ prefix in UXML files.
    • These will be replaced at runtime when the VisualElement is added to the scene.
    • Example: <ui:Button text="$mainScene_button_sing" name="startButton" />