Функция LOAD_TEXTDOMAIN() в WordPress

Функция LOAD_TEXTDOMAIN() используется для загрузки файла переводов с расширением .mo в указанную текстовую область ($domain). Если текстовая область уже существует, новые переводы будут объединены с уже загруженными. Если в обоих наборах есть одинаковая строка, будет использоваться перевод из оригинального значения.

При успешной загрузке файл .mo будет помещён в глобальную переменную $l10n под уникальным идентификатором $domain и станет объектом MO.

Использование

Синтаксис

load_textdomain( $domain, $mofile, $locale );

• $domain (string, обязательный) — Текстовая область. Уникальный идентификатор для получения переведённых строк.
• $mofile (string, обязательный) — Путь к файлу .mo.
• $locale (string) — Локаль. По умолчанию: текущая локаль.

Пример 1: Перевод строки

В этом примере мы переводим строку __('book', 'mydomain'). Предполагается, что файл .mo уже создан и содержит данные для перевода этой строки.

// файл .mo должен находиться в папке "lang" рядом с файлом,
// в котором вызывается этот код.

// Подключаем существующий файл .mo (например, ru_RU.mo в зависимости от локали)
add_action( 'plugins_loaded', 'load_my_textdomain' );

function load_my_textdomain(){
    $mo_file_path = dirname(__FILE__) . '/lang/' . determine_locale() . '.mo';

    load_textdomain( 'mydomain', $mo_file_path );
}

// Теперь в теме используем:

В результате для греческой локали будет выведено слово "βιβλίο".

Пример 2: Загрузка перевода другой локали

Есть ситуации, когда нужно загрузить перевод плагина, который отличается от текущей локали пользователя. Например, на многоязычных сайтах может потребоваться загрузить переводы для определённой локали.

if ( is_textdomain_loaded( $plugin ) ) {
    unload_textdomain( $plugin );
}

$mofile = sprintf( '%s-%s.mo', $plugin, $locale );

// Сначала проверяем путь установки языка.
$domain_path = path_join( WP_LANG_DIR, 'plugins' );
$loaded = load_textdomain( $plugin, path_join( $domain_path, $mofile ) );

// Если не удалось загрузить, проверяем папку языка плагина.
if ( ! $loaded ) { 
    $domain_path = path_join( WP_PLUGIN_DIR, "{$plugin}/languages" );
    load_textdomain( $plugin, path_join( $domain_path, $mofile ) );
}

Возвращаемое значение

Функция load_textdomain() возвращает true в случае успеха и false в случае ошибки.

Примечания

• Глобальная переменная $l10n содержит массив всех загруженных текстовых областей на данный момент.
• Глобальная переменная $l10n_unloaded содержит массив всех текстовых областей, которые были выгружены.

Изменения

Функция была введена в версии 1.5.0. С версии 6.1.0 был добавлен параметр $locale.

Код функции

Ниже приведён код функции load_textdomain() для понимания её работы:

function load_textdomain( $domain, $mofile, $locale = null ) {
global $l10n, $l10n_unloaded, $wp_textdomain_registry;

$l10n_unloaded = (array) $l10n_unloaded;

if ( ! is_string( $domain ) ) {
    return false;
}

$loaded = apply_filters( 'pre_load_textdomain', null, $domain, $mofile, $locale );
if ( null !== $loaded ) {
    if ( true === $loaded ) {
        unset( $l10n_unloaded[ $domain ] );
    }
    return $loaded;
}

$plugin_override = apply_filters( 'override_load_textdomain', false, $domain, $mofile, $locale );
if ( true === (bool) $plugin_override ) {
    unset( $l10n_unloaded[ $domain ] );
    return true;
}

do_action( 'load_textdomain', $domain, $mofile );
$mofile = apply_filters( 'load_textdomain_mofile', $mofile, $domain );

if ( ! $locale ) {
    $locale = determine_locale();
}

$i18n_controller = WP_Translation_Controller::get_instance();
$i18n_controller->set_locale( $locale );

$success = $i18n_controller->load_file( $mofile, $domain, $locale );
if ( $success ) {
    unset( $l10n[ $domain ] );
    $l10n[ $domain ] = new WP_Translations( $i18n_controller, $domain );
    $wp_textdomain_registry->set( $domain, $locale, dirname( $mofile ) );

    return true;
}

return false;

}

Теперь вы знаете, как использовать функцию LOAD_TEXTDOMAIN() для загрузки перевода в WordPress!