Inviare email agli utenti del tuo sito nella loro lingua preferita è importante. A questo scopo, WPML offre un’API per memorizzare la lingua preferita dell’utente mentre utilizza il sito e applicare poi questa preferenza quando gli vengono inviate delle email.
Questo documento spiega agli autori di plugin e temi come integrare i loro prodotti con la funzione standard di WordPress wp_mail() nel contesto della lingua preferita.
Quando è necessario inviare email localizzate per utente?
Ecco alcuni esempi che illustrano i casi tipici in cui è necessario inviare email nella lingua preferita dall’utente:
- Sei un amministratore del sito che invia una newsletter agli iscritti: l’amministratore del sito è francese e visualizza l’interfaccia della newsletter in francese. Risultato: tutte le email verranno inviate in francese. Poiché i tuoi iscritti provengono da tutto il mondo, molti non capiranno questa email.
- Gestisci un sito di social network: i membri di questo sito possono pubblicare le loro foto. Altri membri possono mettere “Mi piace” e aggiungere una stella a queste foto; quando mettono “Mi piace”, l’autore dell’immagine verrà informato via email. Ora considera questo scenario:
- Mathias, che è tedesco, ha pubblicato la sua foto.
- Il suo amico Pierre, che è francese, si imbatte nella foto di Mathias e fa clic sul pulsante Mi piace.
- Poiché durante questa azione Pierre stava visualizzando la pagina in francese, Mathias riceverà una notifica via email in francese.
- Gestisci un sito di e-commerce: se un prodotto è temporaneamente non disponibile, gli utenti possono lasciare la loro email per essere informati quando il prodotto torna disponibile. Un visitatore giapponese lascia la sua email sotto alcuni prodotti. Successivamente l’amministratore del sito, che è spagnolo, aggiorna la disponibilità. Risultato: il cliente giapponese riceve un’email automatica “Il prodotto x è di nuovo disponibile” in spagnolo, non in giapponese.
Ci sono molti altri esempi simili e tu sei la persona perfetta per sapere se questo rappresenterà un problema per il tuo plugin o tema.
In tutti questi casi dobbiamo in qualche modo memorizzare la lingua preferita del destinatario e poi passare temporaneamente a questa lingua durante l’invio delle email.
Avvolgere la funzione wp_mail() con codice specifico di WPML
Quando invii email devi aggiungere tre passaggi aggiuntivi al codice del tuo plugin o tema:
- Passa al contesto linguistico preferito dal destinatario dell’email.
- Esegui tutto il tuo codice per l’effettivo invio dell’email.
- Riporta la lingua a quella del sito.
Il secondo passaggio è probabilmente già pronto a questo punto. L’unica cosa da fare è aggiungere due righe aggiuntive, specifiche per WPML: devi solo aggiungere le righe in grassetto.
$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');
Come puoi vedere, le modifiche sono minime, ma devi ricordare i seguenti due punti importanti.
1. Cambia la lingua prima di recuperare il primo contenuto dell’email
Ricorda che stai cambiando la lingua per tradurre il contenuto dell’email. Per questo motivo devi ricordarti di impostare la lingua corretta prima di recuperare qualsiasi contenuto dell’email (l’oggetto o il contenuto del messaggio).
Il seguente codice non funzionerà:
$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');
Invece dovresti usare:
$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. Non inviare email a un array di destinatari
La funzione wp_mail() consente di passare $email come un array di email. Purtroppo, questo non è consentito se si desidera rendere traducibile il contenuto dell’email.
Quindi, se hai un codice che non funziona, come questo:
$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');
Dovresti riscriverlo così:
$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;
Memorizzare la lingua del destinatario
Informazioni sulla lingua per gli utenti di WP
Se i tuoi destinatari sono registrati come utenti standard di WordPress, non è necessario salvare le informazioni sulla lingua e creare un hook. Puoi semplicemente informare i tuoi utenti che possono impostare la loro lingua preferita nell’area di amministrazione di WordPress in Profilo->Il tuo profilo.
Queste informazioni sono memorizzate in un normale campo meta dell’utente, quindi se per qualche motivo desideri recuperarle, puoi usare questo pratico snippet:
$user = get_user_by( 'email', $email );
if ( $user && isset( $user->ID ) ) {
$lang = get_user_meta( $user->ID, 'icl_admin_language', true );
}
Quando i destinatari non sono utenti regolari di WP
Ogni volta che il tuo plugin o tema registra un indirizzo email, dovresti salvare anche la lingua preferita del destinatario. Non hai bisogno di un posto o di un tipo di dati speciale per questo. L’unica cosa che devi fare è aggiungere un filtro che restituirà le informazioni sulla lingua. Il nome del filtro è wpml_user_language.
Il codice di esempio che devi implementare potrebbe avere questo aspetto:
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 della lingua
Se fornisci un’interfaccia utente sul front-end con un pannello di configurazione per i tuoi iscritti, puoi chiedere loro la lingua con il seguente action hook:
do_action('wpml_user_language_switcher', array('mail'=>'mail@example.com') );
Nota che devi sostituire mail@example.com con l’email reale di un iscritto attuale.
Questo codice visualizzerà una casella di selezione con le lingue disponibili. Quando un iscritto ne seleziona una, questo valore verrà inviato tramite una chiamata AJAX al server.
Successivamente, devi salvare questi dati nelle tabelle del tuo database. Per farlo, aggiungi un hook per il filtro wpml_user_language_switcher_save, in questo modo:
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 il tuo filtro non restituirà un valore true, o se non hai affatto un filtro per questo, WPML cercherà di salvare le informazioni sulla lingua nella tabella meta dell’utente (vedi il capitolo successivo).
Inviare email a indirizzi che non sono memorizzati
A volte è necessario inviare email a indirizzi che non si trovano in nessuna tabella del database. Poiché i destinatari non sono nel tuo database, non stai memorizzando nemmeno le loro preferenze linguistiche.
Per questi casi, WPML si aspetta che il codice della lingua sia disponibile in una di queste tre variabili globali:
$_POST['wpml_user_email_language']$_GET['wpml_user_email_language']$GLOBALS['wpml_user_email_language']
Come tradurre le email
Tradurre il contenuto delle email è come tradurre qualsiasi altra stringa nel tuo sito. Per informazioni più dettagliate su questo argomento, visita la nostra pagina di documentazione su Traduzione stringhe.
In breve, assicurati che quanto segue sia applicato a tutte le stringhe utilizzate come contenuto dell’email (oggetto o corpo dell’email):
- Se sono stringhe statiche, assicurati che siano localizzate con le funzioni gettext _e() o __()).
- Se sono salvate nella tabella delle opzioni di WordPress e recuperate utilizzando la funzione get_option(), devi “informare” WPML che anche queste sono traducibili. Questo viene fatto utilizzando il file di configurazione della lingua.
Se queste condizioni sono soddisfatte nel tuo plugin o tema, gli utenti saranno in grado di tradurle nella pagina WPML->Traduzione stringhe.
Esempio pratico
Per vedere un esempio più pratico delle informazioni presentate in questa pagina, visita il post del nostro blog sull’utilizzo dell’integrazione dell’API Mail di WPML con il plugin Sensei.