Translate GDevelop extension

Translate GDevelop extension

This extension allows you to easily manage translations of your game within external JSON files, separating translation functionality from your game logic with pre-built functions and behaviors.

Features

The extension can load language based on the player's preferred system/browser language, and also fall back to default language if no translations exist for any of user's preferred languages.

The extension supports different locales for the same language, for example you can have different translations for US English (en-US) and British English (en-GB) and even a default fallback (en) for any other variant of English which you don't directly support. If user's preffered language is "en-US", that translation set will be loaded. If it's "en-GB" - that one will be loaded. And if their preferred language is for example "en-NZ", the extension will fail to load "en-NZ" translations so it will fall back to default "en".

If user's system/browser has multiple languages listed as preferred, the extension will try to load each of them, trying the locale, then language without locale for each language, finally loading default locale if none of the preferred ones are found. For example, if user's preferred locales are: "sr-RS,en-US" - it will try to load languages in this order:

1. sr-RS
2. sr
3. en-US
4. en
5. default (fall back that your provide)

Translations are loaded in a global variable, so they are available in all of your scenes. However, if you want to track which language is currently selected/loaded, you'll have to track that yourself. This extension only provides translation functionality, nothing more than that (everything else is up to you).

Translation files

Translation files should be stored in your project folder root as [locale].json (en-US.json) or [language].json (en.json). The translation file structure is a simple key/value map of translation keys (which are often source phrases in English) and translation values (translated phrases in the target language). An example German translation (de-DE.json or just de.json) would be:

{
   "Choose your language:": "Wählen Sie Ihre Sprache:",
   "My name is {1}, {0} {1}.": "Mein Name ist {1}, {0} {1}.",
   "Chosen: {0}": "Ausgewählt: {0}",
   "English": "Englisch",
   "Serbian": "Serbisch",
   "German": "Deutsch",
   "French": "Französisch",
   "Italian": "Italienisch",
   "Chinese": "Chinesisch",
   "Russian": "Russisch",
   "Greek": "Griechisch",
   "Play": "Spielen",
   "Go back": "Zurück"
}

⚠️ Your translation files must be loaded to your game Resources as well in order for them to be exported with your game when you export a game build. Use the option "Scan in the project folder for..." > "Json" in your game Resources tab after you've created your translation file.

Extension Actions

• Load translations for preferred language - Load translations from user's preferred system/browser language, with an option to fall back to default language.
• Load translations for language - Load translations for a language you specify. The translation must exist so don't let users enter this value, let them select it!
• Load translations from resource - Load translations from a resource JSON file. This is beginner friendly action and can be used if you have like only 2-3 languages.
• Set translations repository URL - Set remote URL from which language files should be loaded. Experimental.

Extension Expressions

• Translate::text(String key) - Returns translation for a provided key.
• Translate::translate(String key, String parameters) - Returns translation for a provided key and replaces placeholders in the resulting string with provided parameters. More info below.
• Translate::getPreferredLanguages() - Returns a comma separated list of user's browser/system preferred languages.
• Translate::getPreferredLanguage() - Returns the first entry from the list of user's browser/system preferred languages.

Parameters

This extension supports parameters in translations, which means you can have a key (default text) like this: "Hello {0}!". Then if you call Translate::translate("Hello {0}!", PlayerAuthentication::Username()) it will translate the string and replace {0} in the resulting (translated) text with authenticated user's user name. So if the player is logged in as "John Wick", in English it will show as "Hello John Wick!", but in your German translation you can have "Hallo {0}!" so it will show as "Hallo John Wick!".

You can have multiple parameters. For example you can have a key like this: Are you {0}? I'm {1}.. If you call Translate::translate("Are you {0}? I'm {1}.", "Jim,Peter") for English it will result in "Are you Jim? I'm Peter." If your German translation is Bist du {0}? Ich bin {1}., the resulting translation will be "Bist du Jim? Ich bin Peter." Now, let's say in Serbian language you never ask for one's name before telling your own (not true, but imagine). I can set my Serbian translation to be Ja sam {1}. Da li si ti {0}? resulting in "Ja sam Peter. Da li si ti Jim?" - This way you can change the order of parameters in the translation, as often you need to change the order of the words in a sentence to keep the spirit (or satisfy grammar rules) of the language.

Behaviors

Use built-in behaviors to easily and automatically translate objects like:

• Text
• Text Input (value* and placeholder)
• BB Text
• Bitmap Text
• Panel Button

When an appropriate behavior is added to an object, it will store its initial value (set in object's properties), save it internally and use it as a key for translations. Each behavior provides two actions:

• Translate OBJECT_TYPE with parameters - it will call Translate::translate() using object text value as a translation key and provided parameters as parameters to be replaced.
• Translate OBJECT_TYPE object - it will call Translate::text() below the hood and use object text value as a translation key.

Text Input Objects *

With Text Input objects, values will be translated only as long as they are the same as their initial value (what is entered in object properties editor in GDevelop). This is because players can change the value of the input and we don't want to change what they entered. Since Text Input value changes when it's translated, it means you can translate it only once. Keep this in mind and avoid having Text Inputs (with translatable value) on the language selection screen.

Placeholders, on the other side, will also be translated, and can be translated multiple times, same like other (Text) objects' values.