Localization of Blender add-ons – classical way

If you want your add-on to be available for all Blender users around the world, you need to make the localization – translation of its interface into different languages.

The simplest way to make your add-on multilingual is the classic way, it is used in many other programs and requires the minimal usage of the Blender Python API.

In a few words, it consists of creating a dictionary in which all translations are entered, and a function that, depending on the current locale (the language selected by the user), by code, returns the text string from the dictionary in the required language.

Let’s make the localization of the simple add-on in practice.

First, let’s create and register classes for our add-on in the Blender Python API.

We have defined two classes:

LOCALIZATION_TEST_OT_test – an operator that prints a test text string to the console.

LOCALIZATION_TEST_PT_panel – the add-on interface class. It creates a tab in the N-panel of the 3D Viewport window with a text label and a button for calling the operator.

And registered them in the Blender API, as a result, we got a simple add-on. We can install it or execute the code from the “Text Editor” window.

Now we can start to localize it.

First, let’s create a dictionary with translations of text strings that we use in our add-on into different languages.

Let’s define a dictionary, name it “langs”, and for the “Test text in Blender UI” string add translation variants into English, Spanish and Japanese.

We will store all translation variants in an inner dictionary “test_text_in_bl_ui”. Its name is the key to refer to it Usually, for convenience, keys are simplified and shortened compilations of the source text – shortcodes. This adds clarity and readability to the add-on code.

Inside the dictionary with translation variants, the locales are used as keys, and the translation into the language corresponding to the locale – as values.

Now we can get the translation of the string by simply calling the dictionary with the required keys.

Having a dictionary with translations, we can define a function that, based on two keys (shortcode and locale), will return the text in the desired language.

The “loc_str” function takes one required and one optional argument in parameters.

The required argument “str_key” gets the shortcode for searching in the “langs” dictionary we created earlier. If the specified shortcode is not found in the “langs” dictionary, the function will return the following error string: “ERR: no such string in localization”.

Having received the inner dictionary with the translations of the desired string, we can receive the translation into the required language using the locale key.

The currently used locale in Blender can be retrieved through its API:

Since we use text values of the locale as keys, we can easily get the desired translation with the current locale.

If we have no defined translation for the current locale (have not added this locale key with translation to the string dictionary), our function will return the “default” translation, specified in the second, optional, “def_locale_key” parameter. The value for this parameter, of course, must be exactly in the dictionary with string translations. To avoid specifying it every time the function is called, we can set the default value for this parameter to “en_US” in the function definition.

Now we can call this function to get the translation of the required string based on the current locale.

For example:

In the second case, when using the Italian language, the function returned the text in English, since there is no translation to Italian in the dictionary, and English is the default.

Now let’s fill the “langs” dictionary with shortcodes and translation variants to the required languages ​for each text string used in our add-on.

And replace all the text constants defined in our add-on with a call of the “loc_str” function with the necessary keys.

For example, this string value definition:

should be replaced with a function call:

Blender will now display the add-on interface according to the language selected by the user.

The final code:

The classical localization way is simple and convenient, but it has some drawbacks. For example, you can see that our add-on dynamically updates the language of interface elements, but not for operator name and panel header when switching language in Blender settings. Their translation will only change after restarting Blender. However, in most cases, this is not critical.

You can download source files for this tutorial on Patreon.