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

デコレーターは、#REPLACE# の置換前に、すべての getMessage() 呼び出しで実行されます。早い段階（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 では利用できません）を実行すると、設定 → ローカライズ用に言語ファイルがインデックス化されます。