bitrix-localization

Localization

Baseline: main 23.0+ · Verified: main 26.800.0

Lang files

/local/modules/vendor.module/lib/Service/PostService.php
/local/modules/vendor.module/lib/Service/lang/ru/PostService.php     # nearest lang/ dir up the tree, same relative name
/local/modules/vendor.module/lib/Service/lang/en/PostService.php

<?php
$MESS['VENDOR_MODULE_POST_PUBLISHED'] = 'Post #NAME# published';

• UTF-8 without BOM. Since main 26.800 the kernel no longer converts lang-file encodings (not even from translation_repository): non-UTF-8 files show mojibake.
• Keys <VENDOR>_<MODULE>_<CONTEXT>_<CODE>; unprefixed keys collide with other modules.
• A missing phrase falls back to the file of Loc::getDefaultLang($lang): ua, de → en; kz, by, uz → ru; other languages → the .settings.php default_language map (['value' => ['fr' => 'en']]), else en. Ship at least en (and ru).

Loc::getMessage

use Bitrix\Main\Localization\Loc;

echo Loc::getMessage('VENDOR_MODULE_POST_PUBLISHED', ['#NAME#' => $title]);
echo Loc::getMessage('VENDOR_MODULE_POST_PUBLISHED', null, 'en');
Loc::loadLanguageFile($_SERVER['DOCUMENT_ROOT'] . '/local/php_interface/mail.php');   // phrases of another file, now

• getMessage() loads the lang file of the calling file on first use; Loc::loadMessages(__FILE__) only registers extra files for that lazy search. Call it directly in the file whose lang/ holds the phrase: a wrapper helper makes the kernel look next to the helper.
• A phrase found only by scanning other registered files costs extra includes. define('BX_MESS_LOG', '/abs/path/mess.log') in init.php logs misses ([ru]CODE: not found for /file.php) and such lookups (CTranslateUtils::CopyMessage(...)); fix by moving or copying the phrase.
• Components, templates and admin pages load their neighbouring lang files automatically.

Overriding kernel phrases

/local/php_interface/user_lang/<lang>/lang.php, keyed by the lang file path from the document root: