Application Translations (bpy.app.translations)

This object contains some data/methods regarding internationalization in Blender, and allows every py script

to feature translations for its own UI messages.

WARNING: Most of this object should only be useful if you actually manipulate i18n stuff from Python.

If you are a regular addon, you should only bother about :contexts: and :context_sep: members, and the :register:/:unregister: functions!

To add translations to your python script, you must define a dictionary formatted like that:

{locale: {msg_key: msg_translation, ...}, ...} where:

locale is either a lang iso code (e.g. ‘fr’), a lang+country code (e.g. ‘pt_BR’),

a lang+variant code (e.g. 'sr@latin‘), or a full code (e.g. 'uz_UZ@cyrilic‘).

msg_key is a tuple (context, org message) - use, as much as possible, the predefined :contexts:. msg_translation is the translated message in given language! Then, call bpy.app.translations.register(__name__, your_dict) in your register() function, and

bpy.app.translations.unregister(__name__) in your unregister() one.

bl_i18n_utils module has several functions to help you collect strings to translate, and generate the needed python code (the translation dictionary), as well as optional intermediary po files if you want some... See its documentation for more details.

bpy.app.translations.locale

The actual locale currently in use (will always return a void string when Blender is built without internationalization support).

bpy.app.translations.locales

All locales currently known by Blender (i.e. available as translations).

bpy.app.translations.contexts_C_to_py

A readonly dict mapping contexts’ C-identifiers to their py-identifiers.

bpy.app.translations.contexts

constant value bpy.app.translations.contexts(default_real=None, default=’*’, operator_default=’Operator’, plural=’Plural’, id_action=’Action’, id_armature=’Armature’, id_brush=’Brush’, id_camera=’Camera’, id_curve=’Curve’, id_fs_linestyle=’FreestyleLineStyle’, id_gpencil=’GPencil’, id_group=’Group’, id_id=’ID’, id_image=’Image’, id_shapekey=’Key’, id_lamp=’Lamp’, id_library=’Library’, id_lattice=’Lattice’, id_material=’Material’, id_metaball=’Metaball’, id_mesh=’Mesh’, id_nodetree=’NodeTree’, id_object=’Object’, ...)

bpy.app.translations.locale_explode(locale)

Return all components and their combinations of the given ISO locale string.

>>> bpy.app.translations.locale_explode("sr_RS@latin")
("sr", "RS", "latin", "sr_RS", "sr@latin")

For non-complete locales, missing elements will be None.

Parameters:locale – The ISO locale string to explode. Returns:A tuple (language, country, variant, language_country, language@variant).

bpy.app.translations.pgettext(msgid, msgctxt)

Try to translate the given msgid (with optional msgctxt). NOTE: The (msgid, msgctxt) parameter orders has been switched compared to gettext function, to allow

single-parameter calls (context then defaults to BLF_I18NCONTEXT_DEFAULT).

NOTE: You should really rarely need to use this function in regular addon code, as all translation should be

handled by Blender internal code. The only exception are string containing formatting (like “File: %r”), but you should rather use pgettext_iface/_tip in those cases!

Note: Does nothing when Blender is built without internationalization support (hence always returns msgid).

Parameters:

• msgid (string) – The string to translate.
• msgctxt (string or None) – The translation context.

Default msgctxt:  

BLF_I18NCONTEXT_DEFAULT value.

Returns:

The translated string (or msgid if no translation was found).

bpy.app.translations.pgettext_data(msgid, msgctxt)

Try to translate the given msgid (with optional msgctxt), if new data name’s translation is enabled. NOTE: See pgettext notes.

Parameters:

• msgid (string) – The string to translate.
• msgctxt (string or None) – The translation context.

Default msgctxt:  

BLF_I18NCONTEXT_DEFAULT value.

Returns:

The translated string (or msgid if no translation was found).

bpy.app.translations.pgettext_iface(msgid, msgctxt)

Try to translate the given msgid (with optional msgctxt), if labels’ translation is enabled. NOTE: See pgettext notes.

Parameters:

• msgid (string) – The string to translate.
• msgctxt (string or None) – The translation context.

Default msgctxt:  

BLF_I18NCONTEXT_DEFAULT value.

Returns:

The translated string (or msgid if no translation was found).

bpy.app.translations.pgettext_tip(msgid, msgctxt)

Try to translate the given msgid (with optional msgctxt), if tooltips’ translation is enabled. NOTE: See pgettext notes.

Parameters:

• msgid (string) – The string to translate.
• msgctxt (string or None) – The translation context.

Default msgctxt:  

BLF_I18NCONTEXT_DEFAULT value.

Returns:

The translated string (or msgid if no translation was found).

bpy.app.translations.register(module_name, translations_dict)

Registers an addon’s UI translations.

Note: Does nothing when Blender is built without internationalization support.

Parameters:

• module_name (string) – The name identifying the addon.
• translations_dict (dict) – A dictionary built like that: {locale: {msg_key: msg_translation, ...}, ...}

bpy.app.translations.unregister(module_name)

Unregisters an addon’s UI translations.

Note: Does nothing when Blender is built without internationalization support.

Parameters:module_name (string) – The name identifying the addon.