Localization of Blender add-ons – with API

The classic way of localizing a Blender add-on (translating it into different languages) is convenient because requires just a single Blender Python API call – to get the currently used locale. This way is maximum universal, but Blender would not be Blender if it did not provide users an ability to localize add-ons through its own API.

The principle of creating multilingual add-ons using the Blender Python API is not much different from the classical one – we need to create a dictionary with all the variants of translations for all text strings from our add-on and use this dictionary in the localization.

Let’s take the same code of the simple add-on and localize it with the Blender Python API usage.

First, let’s define a dictionary with the translation variants for text strings used in our add-on.

Unlike the classical method, where we can define the dictionary as we like, the dictionary that we will use with the Blender API must have a certain structure.

Locales must be used as first keys. And there is no need to specify a separate translation into the default language used in our add-on (English).

The internal dictionary for each locale must use a tuple with two items as keys.

The first item is the “context” of the current translation. It needs to be specified if the same string has different translations depending on where it is used. For example, the same string, if it is used as an operator name, can have one translation, and completely different if it is used in shader nodes. If the translation is independent of the context – “*” must be specified as the value.

The second element is the original text string in the default language (usually English). This string and exactly in this language you will have to use in the add-on code.

The value of the dictionary item (with this complex key) should be the translation of the text string into the language of the locale specified in the first key.

For example, the translation dictionary “langs” for the single text string “Test text in Blender UI” into Spanish and Japanese will look like this:

If we want to access this translation directly, as in the classical localization method, we would write something like this:

However, the Blender API doesn’t need to access the translation dictionary directly.

To allow Blender Python API to access our dictionary and use it for translations, we need to register it in the API.

To do this, in the “register” function, where we register all classes of our add-on, we need to add the registration of our dictionary with the following command:

where “langs” is the name of the translation dictionary we created.

For proper work the dictionary must also be unregistered in the “unregister” function:

Now, when the user switches the language, all text strings in our add-on that have a translation into the selected language will be automatically translated. And in most cases, you don’t need to change the add-on source code!

You do not need to call a function, as in the classical method, to translate the interface, the original strings must be left in their original form of simple assignment.

But in some expressions, for example, in the “print” function, or for translating the formatted strings, we need to replace the text assignment with a call of a special API function – “pgettext”.

For example, the text string in the “print” function:

should be replaced with a function call:

Let’s add translations for each text string of our add-on to the dictionary made earlier with the API requirements:

Let’s also replace text strings assignment to a function call, only if necessary.

And now Blender displays the interface of our add-on in accordance with the current user’s language.

The final code:

Unlike the classical localization way, this method has stricter requirements for defining the translation dictionary and more API calls, but in some cases, it is more convenient because it is not always necessary to replace strings with a function call, and the entire interface is now translated “on the fly”, including operator names and panel headers.

You can download source files for this tutorial on Patreon.

5 1 vote
Article Rating
Notify of

0 Comment
Inline Feedbacks
View all comments