Come rendere i tuoi plugin e temi compatibili con WPML

Segui la nostra guida passo passo per rendere i tuoi plugin e temi compatibili con WPML.

Questa guida è destinata agli autori di temi e plugin che hanno già aderito al nostro programma di compatibilità: Go Global. Se non hai ancora aderito, invia la tua candidatura prima di seguire questa guida.

Come diventare compatibili con WPML

1. Crea un file di configurazione della lingua

Un file di configurazione della lingua dice a WPML quali testi tradurre (e quali no) nel tuo plugin o tema. Questo include i testi nei tipi di post personalizzati, nelle tassonomie, nei campi, nelle schermate dell'area di amministrazione, nei widget e altro ancora.

Se sai già come creare un file di configurazione della lingua, segui le istruzioni sottostanti per testare la tua configurazione. Altrimenti, consulta la nostra guida alla configurazione della lingua per imparare a crearne uno.

Configurazione di test
1. Crea alcuni articoli e tassonomie
2. Inviali per la traduzione
3. Verifica che appaiano tradotti nel front-end

2. Prepara le stringhe per la traduzione

Le stringhe sono tutti i testi che appaiono sul sito e non fanno parte di articoli, pagine o tassonomie. Per consentire a WPML di tradurre le stringhe nel tuo plugin o tema, segui le istruzioni sottostanti per ogni caso d'uso.

Mentre configuri le tue stringhe, usa il plugin Multilingual Tools per verificare quali stringhe sono traducibili e quali richiedono una configurazione aggiuntiva.

Stringhe hard-coded

Le stringhe hard-coded devono essere registrate con le funzioni gettext. Scopri di più su come usare gettext e preparare il tuo codice.

Stringhe in wp_options

Se il tuo plugin o tema usa stringhe dalla tabella wp_options, registrale nel file wpml-config.xml.

Se le chiavi delle tue opzioni non sono fisse e il tuo tema usa un array di voci che può crescere con l'input dell'utente, registra queste voci dinamicamente. Puoi usare le funzioni dell'API di WPML per farlo.

Stringhe dinamiche

Se nessuno dei metodi precedenti si applica alle tue stringhe, segui queste guide per preparare le stringhe per la traduzione:

Configurazione di test
1. Scansiona il tuo plugin / tema alla ricerca di stringhe in WPML → Localizzazione di temi e plugin
2. Crea una pagina con delle stringhe
3. Controlla se le stringhe appaiono in Traduzione stringhe
4. Traduci alcune stringhe e verifica che appaiano tradotte nel front-end

3. Registra widget e blocchi personalizzati per la traduzione

Se il tuo tema o plugin include widget personalizzati per page builder, come Elementor, devi registrarli per la traduzione.

Consulta le seguenti guide per saperne di più sulla registrazione dei contenuti dei page builder:

Configurazione di test
1. Crea una pagina con tutti i tuoi widget personalizzati
2. Invia la pagina per la traduzione e verifica che i testi dei widget appaiano nell'Editor di traduzione avanzato
3. Controlla che le traduzioni vengano visualizzate nel front-end
4. Ripeti i passaggi per testare diverse impostazioni dei widget

4. Recupera automaticamente gli ID da lingue diverse

Se il tuo tema o plugin ha funzionalità o opzioni che caricano ID di articoli diversi in ogni lingua, usa il filtro wpml_object_id per recuperare automaticamente l'ID dell'articolo tradotto.

Ad esempio, considera uno slider con slide in lingue diverse, ognuna con un ID univoco. Per caricare automaticamente l'ID della slide corretta in ogni lingua, possiamo usare il filtro wpml_object_id:

// Loop posts
while (have_posts()): the_post();
$post = get_post( apply_filters( 'wpml_object_id', $post->ID, 'slide' ) );

Configurazione di test
1. Crea l'articolo / template pertinente, ecc., e aggiungi una stringa di testo
2. Imposta la tua funzionalità per usare quell'articolo
3. Traduci l'articolo e imposta un valore diverso nella stringa di testo
4. Controlla che la funzionalità stia caricando l'ID tradotto nel front-end

5. Diventa compatibile con WooCommerce

WPML può tradurre i contenuti di WooCommerce con il suo componente aggiuntivo WPML Multilingual & Multicurrency for WooCommerce. Se il tuo tema o plugin contiene elementi di WooCommerce, segui la nostra guida alla compatibilità di WPML Multilingual & Multicurrency for WooCommerce per renderlo compatibile con WPML.

6. Mostra o nascondi il selettore di lingua dell'area di amministrazione

Per impostazione predefinita, WPML aggiunge un selettore di lingua alla barra di amministrazione di WordPress. Questo selettore è visibile agli utenti connessi, sia sul front-end che sul back-end.

Selettore di lingua nella barra di amministrazione superiore

In alcuni casi, potresti voler nascondere il selettore di lingua su pagine sensibili, come la tua area delle impostazioni. Per farlo, aggiungi il seguente codice al tuo file 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;
}

Rendere compatibili le funzionalità speciali

Se il tuo tema o plugin include funzionalità speciali (come l'uso di tabelle personalizzate) dovrai usare del codice personalizzato per renderle compatibili con WPML.

Consulta le nostre risorse per sviluppatori per informazioni sullo sviluppo personalizzato.

Problemi comuni e soluzioni

Le etichette dei moduli non possono essere tradotte perché provengono dal database +

Soluzione:

$label = esc_html( apply_filters('wpml_translate_single_string', $this->checkout_item->name, 'wpsc', '$this->checkout_item->name .'_checkout_form_label'' ) );

wp_query($args) o get_posts($args) non filtra gli ID degli articoli corretti per la lingua corrente +

Soluzione:

Se usi wp_query($args) o get_posts($args) devi aggiungere “suppress_filters=0” agli argomenti.

Tutte le slide vengono mostrate in una sola lingua +

Soluzione:

// 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] );
	}
}

L'ID della slide è diverso in una seconda lingua +

Soluzione:

// Loop posts
while (have_posts()): the_post();
$post = get_post( apply_filters( 'wpml_object_id', $post->ID, 'slide' ) );

Lo slider usa una pagina di amministrazione personalizzata e devo registrare i valori dei campi personalizzati per le traduzioni +

Soluzione:

// 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);

L'ID di una tassonomia personalizzata è diverso in una seconda lingua +

Soluzione:

$taxonomy_id = apply_filters( 'wpml_object_id', $taxonomy_id, 'my_custom_taxonomy' );

Le richieste AJAX personalizzate (non standard di WordPress) restituiscono sempre il contenuto nella lingua predefinita +

Soluzione:

Quando crei URL AJAX personalizzati, usa l'hook wpml_current_language e aggiungi la lingua corrente come parametro per gli 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'
}

Quando gestisci le richieste AJAX nel file handle-ajax.php, prima di generare l'output del contenuto, usa l'hook wpml_switch_language per cambiare la lingua del contenuto.

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

// Run other content queries.

Uso errato del valore “id” negli argomenti $args[ ‘tax_query’ ][ ‘field’ ] di WP_Query +

Soluzione:

L'uso dell'argomento “id” per il parametro “field” funziona per la lingua predefinita ma non funziona per la seconda lingua. Di seguito è riportato un esempio di query non corretta:

$args = array(
    'post_type' => 'post',
    'tax_query' => array(
        array(
            'taxonomy' => 'people',
            'field'    => 'id',
            'terms'    => 'bob',
        ),
    ),
);
$query = new WP_Query( $args );

Gli sviluppatori dovrebbero correggere il parametro “field”.

'field'    => 'id',

in:

'field'    => 'term_id',

Riferimento: https://codex.wordpress.org/Class_Reference/WP_Query#Taxonomy_Parameters. Non c'è alcun valore “id” per il parametro “field”. Il suo valore predefinito è “term_id”.