Bitrix Localization

When to use

• The user needs to create or place Bitrix language files and asks where they go (lang/ru, lang/en) and how the path mirrors the source file for a module or component.
• Пользователь подставляет значения в локализованное сообщение (#PARAM#) или обрабатывает множественные формы в Битрикс и спрашивает, как передать параметры в Loc::getMessage().
• The user needs to output a translatable, user-facing string in Bitrix code and asks how to use Loc::getMessage() and a message code instead of a literal.

When NOT to use

• Do not use this skill for translating stored content (iblock elements per site or language); that is modelled with multi-site/multi-language content, not Loc::getMessage lang files.
• Do not use this skill on a non-Bitrix PHP app; Loc::getMessage, the lang-file layout, and IncludeModuleLangFile are Bitrix-specific.

Core guidance

• Keep user-facing text in lang files, not inline — Move every user-facing phrase into a lang file keyed by a message code and reference it through Loc::getMessage; do not hard-code display strings in PHP, templates, or components.
• Pass dynamic values as named parameters — Put placeholders like #COUNT# in the message text and pass values as the second getMessage argument (['#COUNT#' => $n]) instead of concatenating strings around a fragment.
• Prefer Loc::getMessage over legacy GetMessage — In new code, call \Bitrix\Main\Localization\Loc::getMessage('CODE') (after Loc::loadMessages(__FILE__) where needed) instead of the legacy global GetMessage('CODE').

Quick recipe

1. At the top of the PHP file add use Bitrix\Main\Localization\Loc; Loc::loadMessages(__FILE__);, then output the text with Loc::getMessage('VENDOR_MODULE_HELLO'). (verify: The code compiles and getMessage returns a value once the lang file exists.)
2. Create lang/ru/<file>.php and lang/en/<file>.php next to the source file, each returning $MESS['VENDOR_MODULE_HELLO'] = '...'; for that language. (verify: Each language directory has a message file with the same code.)
3. For dynamic text, write $MESS['VENDOR_MODULE_FOUND'] = 'Found #COUNT# items'; and call Loc::getMessage('VENDOR_MODULE_FOUND', ['#COUNT#' => $count]);. (verify: The placeholder is replaced by the value in the rendered output.)

Best practices

• Give message codes a stable, prefixed, uppercase name tied to the module or component (e.g
• Place each message file at a path that mirrors the calling file under lang/<lang-code>/ (e.g
• In module code call Loc::loadMessages(__FILE__) once per file (or the legacy IncludeModuleLangFile(__FILE__)) before reading messages, rather than assuming another file already loaded them

Anti-patterns

See references/anti-patterns.md.

Common mistakes

1. Lang file encoding not matching the site — Saving a lang file in an encoding that differs from the site's charset (UTF-8 vs windows-1251) renders Cyrillic and other non-ASCII text as mojibake. Fix: Save every lang file in the site's charset (UTF-8 on modern installs) and keep all languages consistent with the core encoding.
2. Adding a code to one language only — Adding a message code to lang/ru but not lang/en (or vice versa) makes the code render literally for every visitor on the missing language. Fix: Add each new code to every supported language directory at the same time, even if the initial value is a placeholder pending translation.
3. Calling getMessage without loading the file's messages — Calling Loc::getMessage('CODE') without a prior Loc::loadMessages(__FILE__) (in entry points like AJAX handlers, agents, or CLI) returns the raw code string instead of the translation. Fix: Call Loc::loadMessages(__FILE__) once near the top of every file that reads messages, especially standalone entry points.
4. Lang file path not mirroring the source file — Putting the lang file at a path that does not mirror the calling file (wrong directory or wrong filename under lang/<code>/) makes Bitrix fail to find the messages, so codes render literally. Fix: Place the lang file at the exact mirrored path (same subdirectories and filename) under each lang/<lang-code>/, matching the file that calls getMessage.

Version notes

• Loc supersedes the global GetMessage on modern cores — The D7 \Bitrix\Main\Localization\Loc class (getMessage, loadMessages) is the current API; the global GetMessage() and IncludeModuleLangFile() remain as legacy helpers over the same lang files for older code.
• PHP support tracks the Bitrix core version — Modern Bitrix cores run the localization API on PHP 7.4 through 8.2; the API and lang-file format were not certified past 8.2 at the time of writing, so avoid relying on PHP 8.3+ syntax in localized code.

Security

• Not applicable — no I/O, auth, or untrusted input.

Testing

• Activation and decision behavior are verified in eval/scenarios/bitrix/localization.yaml.

Additional resources

• references/anti-patterns.md
• references/core.md
• references/examples.md
• references/pitfalls.md
• references/recipes.md
• references/version-differences.md

Knowledge graph

Prerequisites: bitrix/kernel-main-module