mcpField
B
bitrix-localization

bitrix-localization

github.com/bxmaximumDevelopment47267 installsUpdated 2w ago
Repository

About bitrix-localization

A Bitrix development skill for translating PHP and JavaScript strings, organizing language files, and diagnosing phrase lookup. It also documents locale formatting and transliteration behavior.

Key features

  1. 01Organizing PHP language files
  2. 02Looking up and overriding phrases
  3. 03Diagnosing missing phrase lookups
  4. 04Publishing strings to JavaScript
  5. 05Using culture formats and transliteration

Use cases

  1. 01Adding translated strings to a module
  2. 02Overriding a kernel phrase
  3. 03Tracing a missing translation
  4. 04Formatting locale-specific values

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/bxmaximum/bitrix-framework-skills --skill bitrix-localization

After installing, type/bitrix-localizationin Claude Code to confirm it loaded.

Details

From the project README

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:

<?php
$MESS['/bitrix/components/bitrix/news.list/templates/.default/lang/ru/template.php']['CT_BNL_ELEMENT_DELETE_CONFIRM'] = 'Удалить?';

Diagnostics (Since main 26.800)

if (\Bitrix\Main\Config\Configuration::getValue('exception_handling')['debug'] ?? false)
{
    Loc::setMessageDecorator(static fn ($code, $raw, $s, $sourceFile, $language) => $s ?? "[$code]");
}
$file = Loc::getMessageSourceFile('VENDOR_MODULE_POST_PUBLISHED');   // files loaded after the decorator was set

The decorator runs on every getMessage() before #REPLACE# substitution; set it early (init.php), dev only. With BX_MESS_CODE defined, phrases are replaced by their codes at load time (26.800+), so never-loaded phrases return null.

Culture formats

$culture = \Bitrix\Main\Context::getCurrent()->getCulture();
$culture->getDateFormat();             // site mask 'DD.MM.YYYY', not a PHP format
$culture->getShortTimeFormat();        // PHP format ('H:i', 'g:i a')
$culture->getNameFormat();             // '#NAME# #LAST_NAME#'
$culture->getNumberDecimals();
$culture->getNumberDecimalSeparator();
$culture->getNumberThousandsSeparator();

echo $dateTime->toString($culture);    // culture date-time, user TZ
echo \FormatDate('SHORT', $dateTime);  // 'SHORT' | 'FULL' | PHP format with localized month names ('j F Y')

Never pass getDateFormat() / getDateTimeFormat() to format(): convert masks first (bitrix-datetime).

JavaScript

\Bitrix\Main\Page\Asset::getInstance()->addString(
    '<script>BX.message(' . \Bitrix\Main\Web\Json::encode([
        'VENDOR_POST_SAVE' => Loc::getMessage('VENDOR_POST_SAVE'),
    ]) . ');</script>'
);
  • Extensions: phrases in the extension's lang/<lang>/config.php are published automatically; lang_additional in config.php must be code => phrase (bitrix-extensions).
  • ES modules: import { Loc } from 'main.core'; Loc.getMessage('VENDOR_POST_SAVE', { '#N#': 5 }). BitrixVue: $Bitrix.Loc.getMessage() (bitrix-vue).

Transliteration

$code = rtrim(\CUtil::translit($name, 'ru', ['replace_space' => '-', 'replace_other' => '-']), '-');

Since main 26.800 a trailing untranslatable char is kept ('Скидка 10%' → skidka_10_); trim with your replace_other.

Tools

php bitrix/bitrix.php translate:index (module translate, not available on PostgreSQL) indexes lang files for Settings → Localization.

Comments

Markdown supported