mcpField
B
bitrix-localization

bitrix-localization

github.com/bxmaximum开发47267 次安装2 周前更新
代码仓库

关于 bitrix-localization

面向 Bitrix 的开发技能，介绍 PHP 和 JavaScript 字符串翻译、语言文件组织及短语查找诊断，也涵盖区域格式和转写行为。

主要功能

  1. 01组织 PHP 语言文件
  2. 02查找和覆盖短语
  3. 03诊断短语查找缺失
  4. 04向 JavaScript 发布字符串
  5. 05使用区域格式和转写

适用场景

  1. 01为模块添加翻译字符串
  2. 02覆盖内核短语
  3. 03追踪缺失的翻译
  4. 04格式化区域相关值

安装

复制下面的命令，在终端中运行。

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

安装后在 Claude Code 中输入/bitrix-localization确认已加载。

详细介绍

本地化

基准：main 23.0+ · 已验证：main 26.800.0

语言文件

/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';
  • 使用不带 BOM 的 UTF-8。自 main 26.800 起，内核不再转换语言文件的编码（包括来自 translation_repository 的文件）：非 UTF-8 文件会显示为乱码。
  • 键格式为 <VENDOR>_<MODULE>_<CONTEXT>_<CODE>；未加前缀的键会与其他模块冲突。
  • 找不到短语时，会回退到 Loc::getDefaultLang($lang) 对应的文件：ua、de → en；kz、by、uz → ru；其他语言 → .settings.php 中的 default_language 映射（['value' => ['fr' => 'en']]），否则为 en。至少提供 en（和 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() 会加载调用文件对应的语言文件；Loc::loadMessages(__FILE__) 只会为延迟搜索注册额外文件。请在 lang/ 目录存放短语的文件中直接调用它：包装辅助函数会使内核在辅助函数所在目录中查找。
  • 仅通过扫描其他已注册文件找到的短语会产生额外的文件加载开销。在 init.php 中使用 define('BX_MESS_LOG', '/abs/path/mess.log') 记录未找到的短语（[ru]CODE: not found for /file.php）和此类查找（CTranslateUtils::CopyMessage(...)）；请通过移动或复制短语来解决。
  • 组件、模板和管理页面会自动加载其相邻的语言文件。

覆盖内核短语

/local/php_interface/user_lang/<lang>/lang.php，键使用相对于文档根目录的语言文件路径：

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

诊断（自 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

每次调用 getMessage() 时，装饰器都会在替换 #REPLACE# 之前运行；请尽早设置（init.php），且仅用于开发环境。定义 BX_MESS_CODE 后，短语会在加载时替换为其代码（26.800+），因此从未加载的短语会返回 null。

文化格式

$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')

不要将 getDateFormat() / getDateTimeFormat() 传给 format()：请先转换格式掩码（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>'
);
  • 扩展：扩展 lang/<lang>/config.php 中的短语会自动发布；config.php 中的 lang_additional 必须采用 code => phrase 格式（bitrix-extensions）。
  • ES 模块：import { Loc } from 'main.core'; Loc.getMessage('VENDOR_POST_SAVE', { '#N#': 5 })。BitrixVue：$Bitrix.Loc.getMessage()（bitrix-vue）。

转写

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

自 main 26.800 起，末尾无法转写的字符会保留（'Скидка 10%' → skidka_10_）；请使用自己的 replace_other 将其去除。

工具

php bitrix/bitrix.php translate:index（模块 translate，PostgreSQL 上不可用）会为“设置” → “本地化”建立语言文件索引。

评论

支持 Markdown