Localization of the Block

Block localization defines translations for the interface labels a user sees in the site editor: the block name, and the names of nodes, cards, attribute fields, and menu items. Translations are described in the manifest file through the lang_original and lang keys.

Localization is intended for custom blocks that an application adds to the repository using the landing.repo.register method. A typical case is a Market application with its own blocks, installed in Bitrix24 accounts with different interface languages. System blocks of Bitrix24 are translated through the product language files and do not use the lang_original and lang keys.

Two clarifications about the scope:

• localization does not translate block content. The text, links, and images a user has entered in a block on a page are stored in the content and remain in the original language
• the lang_original and lang keys with the same names also exist for custom site templates, but that is a separate mechanism with a different set of translatable fields. It is described in the Template Localization article

How to Add LocalizationHow to Add Localization

1. Build the block manifest in one language.
2. Pass the code of that language in lang_original.
3. Build the lang array: for each language, list the original manifest phrases and their translations.
4. Register the block using the landing.repo.register method, passing lang_original and lang in the manifest parameter.
5. Add the block to a page and call landing.block.getmanifest. In the response, the name values must arrive in the Bitrix24 language, the lang key must be absent, and lang_original must be retained as it was.

Localization Keys in the ManifestLocalization Keys in the Manifest

• lang_original — the original language of the phrases in the manifest, for example en
• lang — the set of translations by language

The language code matches the Bitrix24 language code. The current language is returned by the app.info method in the LANGUAGE_ID field.

In the lang array, the keys are the original phrases from the manifest, and the values are the translations of those phrases.

Example:

'lang_original' => 'en',
        'lang' => [
            'de' => [
                'Title with a separator on a light background' => 'Titel mit Trennlinie auf hellem Hintergrund',
                'Button' => 'Schaltflache',
            ],
            'fr' => [
                'Title with a separator on a light background' => 'Titre avec separateur sur fond clair',
                'Button' => 'Bouton',
            ],
        ],
        

Which Labels Are TranslatedWhich Labels Are Translated

The system iterates through the entire manifest and substitutes values only for name keys at any nesting level. Other keys are not translated, even if lang contains a matching phrase.

The name keys that occur in a manifest:

The table lists the places where the name key occurs in a typical manifest. The rule is broader than the table: any name key at any nesting level is translated, so review your own manifest in full.

Not translated:

• block.description — the block description
• style.nodes.<selector>.title — the element label in the style panel, set through the title key
• attribute service fields: placeholder, title, stubText
• the value entries in items lists
• selectors, section codes, node types, and style types

An example of a manifest with labels that will be translated:

$manifest = [
            'block' => [
                'name' => 'Title with a separator',
                'section' => ['text'],
            ],
            'nodes' => [
                '.landing-block-node-title' => [
                    'name' => 'Title',
                    'type' => 'text',
                ],
            ],
            'lang_original' => 'en',
            'lang' => [
                'de' => [
                    'Title with a separator' => 'Titel mit Trennlinie',
                    'Title' => 'Uberschrift',
                ],
            ],
        ];
        

How the System Selects a TranslationHow the System Selects a Translation

The system selects a single language branch from the lang array and applies it to the entire manifest:

1. It determines the Bitrix24 language. For the ru, kz, by, and uz languages, the ru branch is used.
2. If a branch with that code exists in lang, it takes the translations from it.
3. If there is no such branch and lang_original differs from the Bitrix24 language, it takes the translations from the en branch.
4. If no suitable branch exists, it retains the original phrases of the manifest.

Within the selected branch, a translation is substituted only for the phrases present in it as keys. Phrases without a translation remain in the lang_original language.

Which Methods Return a Translated ManifestWhich Methods Return a Translated Manifest

To see the translations, call landing.block.getmanifest for a block that has already been added to a page. The substitution language is set by the Bitrix24 language, not by a method parameter.

In the response of this method, check the following:

• the name values in block, nodes, cards, attrs, and menu — they must be in the Bitrix24 language
• the lang key — it is absent from the response, the system removes it after substituting the translations
• the lang_original key — it is retained exactly as it was passed during registration

If the name values arrive in the original language, compare the phrase keys in lang with the manifest strings, and check whether lang contains a branch for the Bitrix24 language or an en branch.

Permissions and LimitationsPermissions and Limitations

Scope: landing

Who can execute the methods: depending on the method

Localization itself has no dedicated access permissions. Permissions are checked at the level of the methods that register a block and read a manifest, and they are listed on the pages of those methods.

Limitations of localization:

• only the value of the name key is translated
• the translation key is the exact string from the manifest, including case, spaces, and punctuation
• a single phrase is translated the same way everywhere in the manifest, and a separate translation for a specific selector cannot be set
• branch codes in lang are limited to the codes of languages available in Bitrix24. A branch with a code that is not among the interface languages will not be selected

What to ConsiderWhat to Consider

• Set lang_original to the language the phrases are actually written in. If the value does not match the actual language, the fallback en branch will not work.
• Provide the same set of keys in all language branches so that the interface does not mix languages.
• Distinguish labels with different meanings already in the original language. For example, instead of two labels reading "Name", use "Block name" and "Button name".
• Create a separate en branch even if the main language of the block is different. It is used as a fallback for languages without their own translation.

Continue LearningContinue Learning

• Manifest File
• Node Types
• Attributes
• Extended Description of Cards
• Add a Custom Block to the Repository landing.repo.register
• Get the Manifest of the landing.block.getmanifest Method
• Template Localization