Up to date

This page is up to date for Godot 4.1. If you still find outdated information, please open an issue.

Internationalizing games

Introduction

Sería excelente que el mundo hablara solo un idioma (It would be great if the world spoke only one language). Unfortunately for us developers, that is not the case. While indie or niche games usually do not need localization, games targeting a more massive market often require localization. Godot offers many tools to make this process more straightforward, so this tutorial is more like a collection of tips and tricks.

Localization is usually done by specific studios hired for the job. Despite the huge amount of software and file formats available for this, the most common way to do localization to this day is still with spreadsheets. The process of creating the spreadsheets and importing them is already covered in the Importing translations tutorial. If you haven't read the Importing translations page before, we recommend you give it a read before reading this page.

Note

We will be using the official demo as an example; you can download it from the Asset Library.

Configuring the imported translation

Translations can get updated and re-imported when they change, but they still have to be added to the project. This is done in Project → Project Settings → Localization:

../../_images/localization_dialog.png

The above dialog is used to add or remove translations project-wide.

Localizing resources

It is also possible to instruct Godot to use alternate versions of assets (resources) depending on the current language. This can be used for localized images such as in-game billboards or localized voices.

The Remaps tab can be used for this:

../../_images/localization_remaps.png

Select the resource to be remapped then add some alternatives for each locale.

Note

The resource remapping system isn't supported for DynamicFonts. To use different fonts depending on the language's script, use the DynamicFont fallback system instead, which lets you define as many fallback fonts as you want.

The upside of the DynamicFont fallback system is that it works regardless of the current language, making it ideal for things like multiplayer chat where the text language may not match the client's language.

Converting keys to text

Some controls, such as Button and Label, will automatically fetch a translation if their text matches a translation key. For example, if a label's text is "MAIN_SCREEN_GREETING1" and that key exists in the current translation, then the text will automatically be translated.

This automatic translation behavior may be undesirable in certain cases. For instance, when using a Label to display a player's name, you most likely don't want the player's name to be translated if it matches a translation key. To disable automatic translation on a specific node, disable Localization > Auto Translate in the inspector.

In code, the Object.tr() function can be used. This will just look up the text in the translations and convert it if found:

level.text = tr("LEVEL_5_NAME")
status.text = tr("GAME_STATUS_%d" % status_index)

Note

If no text is displayed after changing the language, try to use a different font. The default project font only supports a subset of the Latin-1 character set, which cannot be used to display languages like Russian or Chinese.

A good resource for multilingual fonts is Noto Fonts. Make sure to download the correct variation if you're using a less common language.

Once you've downloaded the font, load the TTF file into a DynamicFont resource and use it as a custom font of your Control node. For better reusability, associate a new a Theme resource to your root Control node and define the DynamicFont as the Default Font in the theme.

Placeholders

To feature placeholders in your translated strings, use GDScript format strings or the equivalent feature in C#. This lets translators move the location of the placeholder in the string freely, which allows translations to sound more natural. Named placeholders with the String.format() function should be used whenever possible, as they also allow translators to choose the order in which placeholders appear: