Отправлять письма пользователям Вашего сайта на предпочитаемом ими языке очень важно. Для этого WPML предлагает API, позволяющий сохранять предпочитаемый язык пользователя во время использования им сайта, а затем применять эту настройку при отправке ему писем.
В этом документе разработчикам плагинов и тем оформления объясняется, как интегрировать их продукты со стандартной функцией WordPress wp_mail() в контексте предпочитаемого языка.
Когда необходимо отправлять локализованные письма для каждого пользователя?
Вот примеры, иллюстрирующие некоторые типичные ситуации, когда необходимо отправлять письма на предпочитаемом пользователем языке:
- Вы — администратор сайта, рассылающий новостную рассылку подписчикам: администратор сайта — француз, и интерфейс рассылки отображается у него на французском языке. Результат: все письма будут отправлены на французском. Поскольку Ваши подписчики находятся по всему миру, многие из них не поймут это письмо.
- Вы управляете социальной сетью: участники этого сайта могут публиковать свои фотографии. Другие участники могут ставить лайки и отмечать эти фотографии звездочками — когда они это делают, автор изображения получает уведомление по электронной почте. Теперь рассмотрим такой сценарий:
- Матиас из Германии опубликовал свою фотографию.
- Его друг Пьер, француз, натыкается на фотографию Матиаса и нажимает кнопку Нравится.
- Поскольку во время этого действия страница у Пьера отображалась на французском языке, Матиас получит уведомление по электронной почте на французском.
- Вы управляете сайтом электронной коммерции: если какой-то товар временно недоступен, пользователи могут оставить свой email, чтобы получить уведомление, когда товар снова появится в наличии. Посетитель из Японии оставляет свой email под одним из товаров. Затем администратор сайта, испанец, обновляет информацию о наличии. Результат: японский покупатель получает автоматическое письмо «Товар X снова в наличии» на испанском, а не на японском языке.
Существует множество других подобных примеров, и Вы лучше всех знаете, станет ли это проблемой для Вашего плагина или темы оформления.
Во всех этих случаях нам нужно как-то сохранить предпочитаемый язык получателя, а затем на время переключиться на этот язык при отправке писем.
Обертывание функции wp_mail() кодом, специфичным для WPML
При отправке писем Вам необходимо добавить три дополнительных шага в код Вашего плагина или темы оформления:
- Переключить языковой контекст на язык, предпочитаемый получателем письма.
- Затем выполнить весь Ваш код для фактической отправки письма.
- Переключить язык обратно на язык сайта.
Второй шаг, скорее всего, у Вас уже готов. Единственное, что нужно сделать, — добавить две дополнительные строки, специфичные для WPML: Вам нужно добавить только те строки, которые выделены жирным шрифтом.
$email = get_option('receiver-email');
// Switch language context…
do_action('wpml_switch_language_for_email', $email);
// your code for sending email:
$subject = __('Hello, World!', 'text-domain');
$message = __('This is our newsletter', 'text-domain');
wp_mail($email, $subject, $message);
// switch language back
do_action('wpml_restore_language_from_email');
Как видите, изменения невелики, но Вам нужно помнить о следующих двух важных моментах.
1. Переключайте язык до получения самого первого контента письма
Помните, что Вы переключаете язык для перевода контента письма. Именно поэтому Вам нужно не забыть установить правильный язык до получения любого контента письма — темы или текста сообщения.
Следующий код работать не будет:
$email = my_func_to_get_receiver_email();
$subject = my_func_to_get_title(); // will come in site’s lang
$message = my_func_to_get_msg_body(); // will come in site’s lang
do_action('wpml_switch_language_for_email', $email);
wp_mail($email, $subject, $message);
do_action('wpml_restore_language_from_email');
Вместо этого Вам следует использовать:
$email = my_func_to_get_receiver_email();
do_action('wpml_switch_language_for_email', $email);
$subject = my_func_to_get_title(); // will come in receiver’s lang
$message = my_func_to_get_msg_body(); // will come in receiver’s lang
wp_mail($email, $subject, $message);
do_action('wpml_reset_language_after_mailing');
2. Не отправляйте письма массиву получателей
Функция wp_mail() позволяет передавать $email как массив адресов электронной почты. К сожалению, это недопустимо, если Вы хотите сделать контент письма переводимым.
Поэтому, если у Вас есть код, который не работает, как этот:
$emails = my_func_get_emails_array(); // array(email1, email2...)
do_action('wpml_switch_language_for_email', $emails); // will not work
$subject = my_func_to_get_title();
$message = my_func_to_get_msg_body();
do_action('wpml_restore_language_from_email');
Вам следует переписать его так:
$emails = my_func_get_emails_array(); // array(email1, email2...)
foreach($emails as $email) :
do_action('wpml_switch_language_for_email', $email); // now is ok
$subject = my_func_to_get_title();
$message = my_func_to_get_msg_body();
do_action('wpml_restore_language_from_email');
endforeach;
Сохранение языка получателя
Информация о языке для пользователей WP
Если Ваши получатели зарегистрированы как стандартные пользователи WordPress, Вам не нужно сохранять информацию о языке и создавать хук. Вы можете просто сообщить своим пользователям, что они могут установить предпочитаемый язык в админ-панели WordPress в разделе Профиль->Ваш профиль.
Эта информация хранится в обычном метаполе пользователя, поэтому, если по какой-то причине Вы хотите ее получить, Вы можете использовать этот удобный фрагмент кода:
$user = get_user_by( 'email', $email );
if ( $user && isset( $user->ID ) ) {
$lang = get_user_meta( $user->ID, 'icl_admin_language', true );
}
Когда получатели не являются обычными пользователями WP
Каждый раз, когда Ваш плагин или тема оформления регистрирует адрес электронной почты, Вам также следует сохранять предпочитаемый язык получателя. Для этого не требуется никакого специального места или типа данных. Единственное, что Вам нужно сделать, — добавить фильтр, который будет возвращать информацию о языке. Имя фильтра — wpml_user_language.
Пример кода, который Вам нужно реализовать, может выглядеть так:
add_filter(‘wpml_user_language’, ‘my_recipients_language’, 10, 2);
function my_recipient_language($lang, $email) {
return get_language_from_my_database($email); // implement it in your plugin/theme
}
Языковой виджет
Если Вы предоставляете какой-либо пользовательский интерфейс на фронтенде с панелью настроек для Ваших подписчиков, Вы можете запросить у них язык с помощью следующего хука:
do_action('wpml_user_language_switcher', array('mail'=>'mail@example.com') );
Обратите внимание, что Вам нужно заменить mail@example.com на реальный email текущего подписчика.
Этот код отобразит выпадающий список с доступными языками. Когда подписчик выберет один из них, это значение будет отправлено на сервер с помощью AJAX-запроса.
Затем Вам нужно сохранить эти данные в таблицах Вашей базы данных. Для этого добавьте хук для фильтра wpml_user_language_switcher_save следующим образом:
add_filter('wpml_user_language_switcher_save', 'my_func', 10, 3);
function my_func($saved, $email, $language) { // your code to save email - language pair, i.e.:
save_language_in_my_database($email, $language);
// if you saved data correctly, return true
return true;
}
Если Ваш фильтр не вернет значение true, или у Вас вообще нет фильтра для этого, WPML попытается сохранить информацию о языке в таблице метаданных пользователя (см. следующий раздел).
Отправка писем на адреса, которые не сохранены
Иногда Вам нужно отправить письма на адреса, которых нет ни в одной таблице базы данных. Поскольку получателей нет в Вашей базе данных, Вы также не сохраняете языковые предпочтения получателя.
Для таких случаев WPML ожидает, что код языка будет доступен в одной из этих трех глобальных переменных:
$_POST['wpml_user_email_language']$_GET['wpml_user_email_language']$GLOBALS['wpml_user_email_language']
Как переводить письма
Перевод контента писем ничем не отличается от перевода любых других строк на Вашем сайте. Для получения более подробной информации на эту тему, пожалуйста, посетите нашу страницу документации Перевод строк.
Вкратце, убедитесь, что следующее применимо ко всем строкам, которые используются в качестве контента письма (темы или тела письма):
- Если это статические строки, убедитесь, что они локализованы с помощью функций gettext _e() или __()).
- Если они сохранены в таблице опций WordPress и извлекаются с помощью функции get_option(), Вам нужно «сообщить» WPML, что они также переводимы. Это делается с помощью файла языковой конфигурации.
Если эти условия соблюдены в Вашем плагине или теме оформления, пользователи смогут перевести их на странице WPML->Перевод строк.
Практический пример
Чтобы увидеть более практический пример информации, представленной на этой странице, пожалуйста, посетите нашу статью в блоге об использовании интеграции WPML Mail API с плагином Sensei.