Как сделать Ваши плагины и темы совместимыми с 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-запросы всегда возвращают контент на языке по умолчанию +

Решение:

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

$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 для переключения языка контента.

if ( isset( $_GET[ 'wpml_lang' ] ) ) {
    do_action( 'wpml_switch_language',  $_GET[ 'wpml_lang' ] ); // switch the content language
}

// Run other content queries.

Неправильное использование значения «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».