Функция LOAD_THEME_TEXTDOMAIN() | WP 1.5.0: использование и примеры

# Функция LOAD_THEME_TEXTDOMAIN() | WP 1.5.0

Эта функция загружает переведённые строки для темы.

Если текущий локаль существует как .mo файл в корневой директории темы, он будет включён в переведённые строки по указанному домену.

Файлы .mo должны именоваться в соответствии с локалью точно.

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

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

Функция возвращает true при успешной загрузке текстового домена, иначе — false.

### Сигнатура функции

```php
load_theme_textdomain( $domain, $path );

• $domain (строка, обязательный): Текстовый домен. Уникальный идентификатор для получения переведённых строк.
• $path (строка|false): Путь к директории, содержащей .mo файл. Значение по умолчанию: false.

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

Пример 1: Смена языка перевода

Этот пример полезен, если вы хотите переключить язык. Переменная, переданная в URL, будет использоваться для смены языка. Например, чтобы переключиться на русский, URL будет выглядеть так: www.example.com/?lang=ru_RU. Это найдёт файл ru_RU.mo в директории languages вашей темы.

// Изменяем язык локализации
// Должен быть вызван до load_theme_textdomain()
add_filter( 'locale', 'my_theme_localized' );

function my_theme_localized( $locale ) {
    if ( ! isset( $_GET['lang'] ) ) {
        return preg_replace( '/[^a-z_]/i', '', $_GET['lang'] );
    }
    return $locale;
}

// Устанавливаем директорию перевода для темы
add_action( 'after_setup_theme', 'my_theme_setup' );

function my_theme_setup() {
    load_theme_textdomain( 'my_theme', get_template_directory() . '/languages' );
}

Пример 2: Как вызвать функцию

Функцию обычно вызывают во время события after_setup_theme, или вы можете вставить её непосредственно в файл functions.php вашей темы:

add_action( 'after_setup_theme', 'my_theme_setup' );

function my_theme_setup() {
    load_theme_textdomain( 'my_theme', get_template_directory() . '/languages' );
}

Сначала WordPress попытается загрузить файл перевода из папки /wp-content/languages/themes/my_theme-ru_RU.mo. Если подходящий файл .mo не найден, он попытается загрузить его из папки вашей темы /wp-content/themes/my_theme/languages/ru_RU.mo.

Здесь my_theme — это указанный текстовый домен, а ru_RU — текущая локаль.

Примечания

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

Изменения

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

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

function load_theme_textdomain( $domain, $path = false ) {
    /** @var WP_Textdomain_Registry $wp_textdomain_registry */
    /** @var array $l10n */
    global $wp_textdomain_registry, $l10n;

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

    if ( ! $path ) {
        $path = get_template_directory();
    }

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

    // Если загрузка по необходимости была вызвана ранее, сбрасываем запись, чтобы попробовать снова.
    if ( isset( $l10n[$domain] ) && $l10n[$domain] instanceof NOOP_Translations ) {
        unset( $l10n[$domain] );
    }

    return true;
}