Enviar e-mails aos usuários do seu site no idioma que eles preferem é importante. Para esse fim, o WPML oferece uma API para armazenar o idioma preferido do usuário enquanto ele estiver usando o site e, em seguida, aplicar essa preferência ao enviar e-mails para ele.
Este documento explica aos autores de plugins e temas como integrar seus produtos com a função padrão wp_mail() do WordPress no contexto do idioma preferido.
Quando você precisa enviar e-mails localizados por usuário?
Aqui estão exemplos que ilustram alguns casos típicos onde você precisa enviar e-mails no idioma preferido do usuário:
- Você é um administrador do site enviando uma newsletter para os assinantes: o administrador do site é francês e visualiza a interface da newsletter no idioma francês. Resultado: todos os e-mails serão enviados em francês. Como seus assinantes vêm de todo o mundo, muitos não entenderão este e-mail.
- Você administra um site de rede social: os membros deste site podem publicar suas fotos. Outros membros podem curtir e favoritar essas fotos – quando eles as curtem, o autor da imagem será informado por e-mail. Agora considere este cenário:
- Mathias, que é alemão, publicou sua foto.
- Seu amigo Pierre, que é francês, vê a foto de Mathias e clica no botão Curtir.
- Como durante essa ação, Pierre estava visualizando a página em francês, Mathias receberá uma notificação por e-mail em francês.
- Você administra um site de e-commerce: se algum produto estiver temporariamente indisponível, os usuários podem deixar seu e-mail para serem informados quando o produto voltar ao estoque. Um visitante japonês deixa seu e-mail em alguns dos produtos. Então, o administrador do site, que é espanhol, atualiza a disponibilidade. Resultado: o cliente japonês recebe um e-mail automático “O produto x está disponível novamente” em espanhol, não em japonês.
Existem muitos outros exemplos semelhantes, e você é a pessoa perfeita para saber se isso apresentará um problema para o seu plugin ou tema.
Em todos esses casos, precisamos de alguma forma armazenar o idioma preferido do destinatário e, em seguida, mudar por um momento para esse idioma ao enviar os e-mails.
Como envolver a função wp_mail() com código específico do WPML
Ao enviar e-mails, você precisa adicionar três etapas adicionais ao código do seu plugin ou tema:
- Mudar o contexto do idioma para o preferido pelo destinatário do e-mail.
- Em seguida, executar todo o seu código para o envio real do e-mail.
- Mudar o idioma de volta para o idioma do site.
A segunda etapa provavelmente já está pronta neste momento. A única coisa a fazer é adicionar duas linhas adicionais, específicas do WPML – você só precisa adicionar as linhas que estão em negrito.
$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');
Como você pode ver, as alterações são pequenas, mas você precisa se lembrar dos dois pontos importantes a seguir.
1. Mude o idioma antes que o primeiro conteúdo do e-mail seja recuperado
Lembre-se de que você está mudando o idioma para traduzir o conteúdo do e-mail. É por isso que você precisa se lembrar de definir o idioma correto antes de recuperar qualquer conteúdo do e-mail – assunto ou conteúdo da mensagem.
O código a seguir não funcionará:
$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');
Em vez disso, você deve usar:
$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. Não envie e-mails para um array de destinatários
A função wp_mail() permite passar o $email como um array de parâmetros de e-mails. Infelizmente, isso é proibido se você quiser tornar o conteúdo do e-mail traduzível.
Portanto, se você tiver um código que não está funcionando, como este:
$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');
Você deve reescrevê-lo para:
$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;
Armazenar o idioma do destinatário
Informações de idioma para usuários do WP
Se seus destinatários estiverem registrados como usuários padrão do WordPress, você não precisará salvar as informações de idioma e criar um hook. Você pode simplesmente informar aos seus usuários que eles podem definir o idioma preferido no painel de administração do WordPress em Perfis->Seu perfil.
Essas informações são armazenadas em um campo meta de usuário comum, então se por algum motivo você quiser recuperá-las, você pode usar este trecho útil:
$user = get_user_by( 'email', $email );
if ( $user && isset( $user->ID ) ) {
$lang = get_user_meta( $user->ID, 'icl_admin_language', true );
}
Quando os destinatários não são usuários regulares do WP
Toda vez que o seu plugin ou tema registrar um endereço de e-mail, você também deve salvar o idioma preferido do destinatário. Você não precisa de nenhum local ou tipo de dado especial para isso. A única coisa que você precisa fazer é adicionar um filtro que retornará a informação do idioma. O nome do filtro é wpml_user_language.
O código de exemplo que você precisa implementar pode ser parecido com este:
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
}
Widget de idioma
Se você fornecer alguma interface de usuário no front-end com painel de configuração para os seus assinantes, você pode perguntar a eles sobre o idioma deles com o seguinte action hook:
do_action('wpml_user_language_switcher', array('mail'=>'mail@example.com') );
Observe que você precisa substituir o mail@example.com pelo e-mail real de um assinante atual.
Este código exibirá uma caixa de seleção com os idiomas disponíveis. Quando um assinante selecionar um, esse valor será enviado por meio de uma chamada AJAX para o servidor.
Em seguida, você precisa salvar esses dados nas tabelas do seu banco de dados. Para fazer isso, adicione um hook para o filtro wpml_user_language_switcher_save, como este:
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;
}
Se o seu filtro não retornar um valor true, ou se você não tiver nenhum filtro para isso, o WPML tentará salvar a informação de idioma na tabela meta do usuário (veja o próximo capítulo).
Envio de e-mails para endereços que não estão armazenados
Às vezes, você precisa enviar e-mails para endereços que não estão em nenhuma tabela de banco de dados. Como os destinatários não estão no seu banco de dados, você também não está armazenando as preferências de idioma de nenhum destinatário.
Para esses casos, o WPML espera que o código do idioma esteja disponível em uma destas três variáveis globais:
$_POST['wpml_user_email_language']$_GET['wpml_user_email_language']$GLOBALS['wpml_user_email_language']
Como traduzir e-mails
Traduzir o conteúdo do e-mail é o mesmo que traduzir quaisquer outras strings no seu site. Para informações mais detalhadas sobre este tópico, visite a nossa página de documentação da Tradução de Strings.
Resumindo, certifique-se de que o seguinte seja aplicado a todas as strings que são usadas como conteúdo de e-mail (assunto ou corpo do e-mail):
- Se forem strings estáticas, certifique-se de que estejam localizadas com as funções gettext _e() ou __()).
- Se elas forem salvas na tabela de opções do WordPress e recuperadas usando a função get_option(), você precisará “informar” o WPML de que elas também são traduzíveis. Isso é feito usando o arquivo de configuração de idioma.
Se essas condições forem atendidas no seu plugin ou em um tema, os usuários poderão traduzi-las na página WPML->Tradução de Strings.
Exemplo prático
Para ver um exemplo mais prático das informações apresentadas nesta página, visite nosso post no blog sobre o uso da integração da API de e-mail do WPML com o plugin Sensei.