Функция LOAD_PLUGIN_TEXTDOMAIN() в WordPress 1.5.0: описание, аргументы, примеры

# Функция LOAD_PLUGIN_TEXTDOMAIN() в WordPress 1.5.0

Функция load_plugin_textdomain() загружает файл перевода .mo из указанной папки. Обратите внимание, что она не работает с многопользовательскими плагинами (MU плагины).

## Как называется файл перевода?

Файл .mo должен быть назван по следующему формату: TRANSLATION_DOMAIN-LOCALE.mo, где LOCALE — это код языка (смотрите функцию get_locale()). Например, если ваш TRANSLATION_DOMAIN — это my-plugin, а выбранный язык русский (LOCALE=ru_RU), то файлы должны называться: my-plugin-ru_RU.mo и my-plugin-ru_RU.po.

## Рекомендуемое время вызова функции

Рекомендуется вызывать эту функцию на хуке init. Если вашему плагину нужны переводы раньше, вам следует пересмотреть логику инициализации плагина или ту часть кода, где требуются переводы.

Если переводы загружаются слишком рано, например, при срабатывании события plugins_loaded, это может помешать другим плагинам, которые работают с переводами и корректно подключаются к функции load_textdomain(). Поэтому рекомендуется задержать загрузку до события init.

С версии 4.6 функция сначала пытается загрузить файл .mo из папки WP_LANG_DIR/plugins/, которая обычно находится по пути: /wp-content/language/plugins.

С версии 6.7.0 требуется вызывать её на хуке init или позже.

Если вы хотите загрузить перевод темы, используйте функцию load_theme_textdomain().

## Аргументы функции

```php
load_plugin_textdomain( $domain, $deprecated, $plugin_rel_path );

• $domain (string, обязательный) — уникальный идентификатор для получения строки перевода.
• $deprecated (string) — устаревший аргу��ент, использовавшийся до версии 2.7. Путь к файлу .mo.
  • По умолчанию: false
• $plugin_rel_path (string) — путь к директории файла .mo относительно WP_PLUGIN_DIR.

Если путь не указан, будет использована корневая директория плагинов WP_PLUGIN_DIR. Таким образом, путь к файлу будет: WP_PLUGIN_DIR/domain-ru_RU.mo.

Примеры использования

Пример 1: Регистрация файла перевода для плагина

Эта часть кода должна находиться в главном файле плагина или в файле, который находится в корневой директории плагина. Если это не так, вам нужно заменить __FILE__ на соответствующий путь.

Файл перевода должен находиться в директории плагина и называться: my-plugin-ru_RU.mo.

add_action( 'plugins_loaded', 'myplugin_init' );
function myplugin_init() {
    load_plugin_textdomain( 'my-plugin', false, dirname( plugin_basename( __FILE__ ) ) );
}

Пример 2: Помещение файла .MO в подпапку languages

add_action( 'plugins_loaded', 'myplugin_init' );
function myplugin_init() {
    load_plugin_textdomain( 'my-plugin', false, dirname( plugin_basename( __FILE__ ) ) . '/languages/' );
}

Пример 3: Регистрация файла перевода для MU плагина

WordPress имеет специальную функцию load_muplugin_textdomain().

Заметки

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

Изменения в версии

• С 1.5.0 — введена функция.
• С 4.6.0 — функция теперь пытается сначала загрузить файл .mo из языковой директории.
• С 6.7.0 — переводы больше не загружаются немедленно, но передаются в механизм загрузки по требованию.

Код функции LOAD_PLUGIN_TEXTDOMAIN()

function load_plugin_textdomain( $domain, $deprecated = false, $plugin_rel_path = false ) {
    global $wp_textdomain_registry, $l10n;

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

    if ( false !== $plugin_rel_path ) {
        $path = WP_PLUGIN_DIR . '/' . trim( $plugin_rel_path, '/' );
    } elseif ( false !== $deprecated ) {
        _deprecated_argument( __FUNCTION__, '2.7.0' );
        $path = ABSPATH . trim( $deprecated, '/' );
    } else {
        $path = WP_PLUGIN_DIR;
    }

    $wp_textdomain_registry->set_custom_path( $domain, $path );

    if ( isset( $l10n[ $domain ] ) && $l10n[ $domain ] instanceof NOOP_Translations ) {
        unset( $l10n[ $domain ] );
    }

    return true;
}

Связанные функции

• get_translations_for_domain()
• is_textdomain_loaded()
• load_child_theme_textdomain()
• load_muplugin_textdomain()
• load_textdomain()
• load_theme_textdomain()
• unload_textdomain()
• wp_set_script_translations()