使用 WPML 发送电子邮件

以网站用户首选的语言向其发送电子邮件非常重要。为此，WPML 提供了一个 API，用于在用户使用网站时存储其首选语言，并在向其发送电子邮件时应用此首选项。

本文档向插件和主题作者说明了如何在首选语言上下文中将其产品与标准 WordPress wp_mail() 函数集成。

何时需要发送按用户本地化的电子邮件

以下示例说明了一些需要以用户首选语言发送电子邮件的典型情况：

您是向订阅者发送新闻通讯的网站管理员：网站管理员是法国人，他以法语显示新闻通讯界面。结果：所有电子邮件都将以法语发送。由于您的订阅者来自世界各地，许多人将无法看懂这封电子邮件。

您正在运营一个社交网络网站：该网站的成员可以发布他们的照片。其他成员可以为这些照片点赞并加注星标——当他们点赞时，图像作者将收到电子邮件通知。现在考虑以下场景：
1. 德国人 Mathias 发布了他的照片。
2. 他的法国朋友 Pierre 看到了 Mathias 的照片，并单击了赞按钮。
3. 因为在此操作期间，Pierre 一直以法语显示页面，所以 Mathias 将收到一封法语电子邮件通知。

您正在运营一个电子商务网站：如果某些产品暂时缺货，用户可以留下他们的电子邮件，以便在产品重新有货时收到通知。一位日本访客在某些产品下留下了他的电子邮件。然后，西班牙籍的网站管理员更新了库存情况。结果：这位日本客户收到了一封西班牙语（而不是日语）的自动电子邮件“产品 x 再次有货”。

还有许多类似的示例，而您最清楚这是否会对您的插件或主题造成问题。

在所有这些情况下，我们需要以某种方式存储收件人的首选语言，然后在发送电子邮件时暂时切换到该语言。

使用 WPML 特定代码包装 wp_mail() 函数

发送电子邮件时，您需要在插件或主题代码中添加三个额外的步骤：

将语言上下文切换为电子邮件收件人首选的语言。

然后运行所有用于实际发送电子邮件的代码。

将语言切换回网站语言。

此时第二步可能已经准备就绪。唯一要做的就是添加两行特定于 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 替换为当前订阅者的真实电子邮件。

此代码将显示包含可用语言的选择框。当订阅者选择一种语言时，此值将通过 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->字符串翻译页面上对其进行翻译。

实际示例

要查看本页所介绍信息的更实际示例，请访问我们关于在 Sensei 插件中使用 WPML 邮件 API 集成的博客文章。