Как сделать Ваши плагины и темы совместимыми с WPML

Следуйте нашему пошаговому руководству, чтобы сделать Ваши плагины и темы совместимыми с WPML.

Это руководство предназначено для разработчиков тем и плагинов, которые уже присоединились к нашей программе совместимости — Go Global. Если Вы еще не присоединились, пожалуйста, подайте заявку перед тем, как следовать этому руководству.

Как обеспечить совместимость с WPML

1. Создайте файл языковой конфигурации

Файл языковой конфигурации указывает WPML, какие тексты переводить (а какие нет) в Вашем плагине или теме оформления. Сюда входят тексты в произвольных типах записей, таксономиях, полях, на экранах админ-панели, в виджетах и многом другом.

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

Тестовая настройка
1. Создайте несколько записей и таксономий
2. Отправьте их на перевод
3. Убедитесь, что они отображаются переведенными на фронтенде

2. Подготовьте строки для перевода

Строки — это любые тексты, которые появляются на сайте и не являются частью записей, страниц или таксономий. Чтобы WPML мог переводить строки в Вашем плагине или теме оформления, следуйте инструкциям ниже для каждого случая использования.

При настройке строк используйте плагин Multilingual Tools, чтобы проверить, какие строки можно перевести, а какие требуют дополнительной настройки.

Жестко закодированные строки

Жестко закодированные строки необходимо регистрировать с помощью функций gettext. Узнайте больше об использовании gettext и подготовке Вашего кода.

Строки в wp_options

Если Ваш плагин или тема оформления использует строки из таблицы wp_options , зарегистрируйте их в файле wpml-config.xml.

Если ключи Ваших опций не фиксированы, а в теме оформления используется массив записей, который может увеличиваться при вводе данных пользователем, регистрируйте эти записи динамически. Для этого Вы можете использовать функции API WPML.

Динамические строки

Если ни один из предыдущих методов не подходит для Ваших строк, следуйте этим руководствам, чтобы подготовить строки к переводу:

Тестовая настройка
1. Отсканируйте Ваш плагин / тему оформления на наличие строк в WPML → Локализация тем и плагинов
2. Создайте страницу со строками
3. Проверьте, появляются ли строки в модуле Перевод строк
4. Переведите несколько строк и убедитесь, что они отображаются переведенными на фронтенде

3. Зарегистрируйте пользовательские виджеты и блоки для перевода

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

Ознакомьтесь со следующими руководствами, чтобы узнать больше о регистрации контента конструкторов страниц:

Тестовая настройка
1. Создайте страницу со всеми Вашими пользовательскими виджетами
2. Отправьте страницу на перевод и убедитесь, что тексты виджетов появляются в Расширенном редакторе переводов
3. Проверьте, что переводы отображаются на фронтенде
4. Повторите шаги для тестирования различных настроек виджета

4. Автоматическое получение ID из разных языков

Если Ваша тема оформления или плагин имеет функции или опции, которые загружают разные ID записей для каждого языка, используйте фильтр wpml_object_id для автоматического получения ID переведенной записи.

Например, рассмотрим слайдер со слайдами на разных языках, каждый из которых имеет уникальный ID. Чтобы автоматически загружать правильный ID слайда для каждого языка, мы можем использовать фильтр wpml_object_id :

// Loop posts
while (have_posts()): the_post();
$post = get_post( apply_filters( 'wpml_object_id', $post->ID, 'slide' ) );

Тестовая настройка
1. Создайте соответствующую запись / шаблон и т. д. и добавьте текстовую строку
2. Настройте Вашу функцию на использование этой записи
3. Переведите запись и задайте другое значение в текстовой строке
4. Проверьте, что функция загружает переведенный ID на фронтенде

5. Обеспечьте совместимость с WooCommerce

WPML может переводить контент WooCommerce с помощью дополнения WPML Multilingual & Multicurrency for WooCommerce. Если Ваша тема оформления или плагин содержит элементы WooCommerce, следуйте нашему руководству по совместимости с WPML Multilingual & Multicurrency for WooCommerce, чтобы сделать их совместимыми с WPML.

6. Отображение или скрытие переключателя языков в админ-панели

По умолчанию WPML добавляет переключатель языков в панель администратора WordPress. Этот переключатель виден авторизованным пользователям как на фронтенде, так и в бэкенде.

Переключатель языков в верхней панели администратора

В некоторых случаях Вы можете захотеть скрыть переключатель языков на важных страницах, например, в разделе настроек. Для этого добавьте следующий код в Ваш файл functions.php:

//Make sure to rename the function before adding to your plugin
add_filter( 'wpml_show_admin_language_switcher', 'compsupp_disable_wpml_admin_lang_switcher' );
 
function compsupp_disable_wpml_admin_lang_switcher( $state ) {
    global $pagenow;
 
    // Add the admin pages that we need to hide the language switcher
    $admin_pages_to_hide_ls = array(
        'admin-page-slug', 'another-admin-page-slug', 'one-more-admin-page-slug'
    );
 
    // We can also have a filter here in case we need to add/remove pages later
    $admin_pages_to_hide_ls = apply_filters( 'compsupp_filter_disable_wpml_lang_switcher_in_admin', $admin_pages_to_hide_ls);
     
    if (
        $pagenow == 'admin.php'
        && isset( $_GET['page'] )
        && in_array( $_GET['page'], $admin_pages_to_hide_ls)
    ) {
        $state = false;
    }
    return $state;
}

Обеспечение совместимости специальных функций

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

Ознакомьтесь с нашими ресурсами для разработчиков для получения информации о пользовательской разработке.

Распространенные проблемы и их решения

Метки форм не могут быть переведены, так как они берутся из базы данных +

Решение:

$label = esc_html( apply_filters('wpml_translate_single_string', $this->checkout_item->name, 'wpsc', '$this->checkout_item->name .'_checkout_form_label'' ) );

wp_query($args) или get_posts($args) не фильтрует правильные ID записей для текущего языка +

Решение:

Если Вы используете wp_query($args) или get_posts($args), Вам нужно добавить «suppress_filters=0» в аргументы.

Все слайды отображаются на одном языке +

Решение:

// Unset not translated slides
foreach( $slides as $k => $slide ) {
	$check = apply_filters( 'wpml_post_language_details', NULL, $slide->ID )
	$slide_language_code = substr( $check['locale'], 0, 2 );

	if( $check['different_language'] ) {
		unset( $slides[$k] );
	}
}

ID слайда отличается на втором языке +

Решение:

// Loop posts
while (have_posts()): the_post();
$post = get_post( apply_filters( 'wpml_object_id', $post->ID, 'slide' ) );

Слайдер использует пользовательскую страницу админ-панели, и мне нужно зарегистрировать значения произвольных полей для переводов +

Решение:

// Adding a new slide code
$slide_id = $this->slide->ID;
$url = $fields['url'];

// Register slide URL to translations
do_action( 'wpml_register_single_string', 'Slider', 'Slide_ID_' . $this->slide->ID, $url);

$this->add_or_update_or_delete_meta($this->slide->ID, 'url', $url);

ID пользовательской таксономии отличается на втором языке +

Решение:

$taxonomy_id = apply_filters( 'wpml_object_id', $taxonomy_id, 'my_custom_taxonomy' );

Пользовательские (нестандартные для WordPress) AJAX-запросы всегда возвращают контент на языке по умолчанию +

Решение:

При создании пользовательских AJAX URL-адресов используйте хук wpml_current_language и добавляйте текущий язык в качестве параметра для AJAX URL-адресов.

$ajax_url = 'http://my-site.com/wp-content/plugins/my-plugin/handle-ajax.php';
$my_current_lang = apply_filters( 'wpml_current_language', NULL ); 
if ( $my_current_lang ) {
	$ajax_url = add_query_arg( 'wpml_lang', $my_current_lang, $ajax_url );
	// $ajax_url will be something like 'http://my-site.com/wp-content/plugins/my-plugin/handle-ajax.php?wpml_lang=es'
}

При обработке AJAX-запросов в файле handle-ajax.php, перед генерацией вывода контента, используйте хук wpml_switch_language для переключения языка контента. Закройте область действия языка по завершении. Начиная с WPML 5.0, переключения языков вкладываются друг в друга, поэтому каждое переключение требует собственного восстановления.

if ( ! empty( $_GET[ 'wpml_lang' ] ) ) {
    // Opens a language scope. Only a non-empty language code switches the language.
    do_action( 'wpml_switch_language', sanitize_text_field( $_GET[ 'wpml_lang' ] ) );

    try {
        // Run other content queries.
    } finally {
        // Closes the scope that the call above opened.
        do_action( 'wpml_switch_language', null );
    }
}

Неправильное использование значения «id» в аргументе(ах) WP_Query $args[ ‘tax_query’ ][ ‘field’ ] +

Решение:

Использование аргумента «id» для параметра «field» работает для языка по умолчанию, но не работает для второго языка. Ниже приведен пример неправильного запроса:

$args = array(
    'post_type' => 'post',
    'tax_query' => array(
        array(
            'taxonomy' => 'people',
            'field'    => 'id',
            'terms'    => 'bob',
        ),
    ),
);
$query = new WP_Query( $args );

Разработчикам следует исправить параметр «field».

'field'    => 'id',

на:

'field'    => 'term_id',

Справка: https://codex.wordpress.org/Class_Reference/WP_Query#Taxonomy_Parameters. Для параметра «field» не существует значения «id». Его значением по умолчанию является «term_id».