Molti siti (e temi) necessitano di un selettore di lingua personalizzato, che si fonderà nel design complessivo. Questo tutorial spiega come progettare selettori di lingua personalizzati utilizzando solamente modelli HTML e senza scrivere PHP.

Introduzione ai modelli twig per i selettori di lingua

Twig è un motore di modelli che vi consente di progettare con HTML e lo pseudo codice.

Per esempio questo è un modello twig:




<div class="[ css_classes ] my-custom-switcher">



<ul>

   {% for code, language in languages %}



<li class="[ language.css_classes ] my-custom-switcher-item">

           <a href="[ language.url ]">

               {% if language.flag_url %}

                   <img src="[ language.flag_url ]" alt="[ language.code ]" title="[ language.flag_title ]">

               {% endif %}

               [ language.native_name ]

               ([ language.display_name ])

           </a>

       </li>



   {% endfor %}

   </ul>



</div>



Ciò che fa questo modello è:

  1. Aprire il DIV contenitore e i tag UL del selettore di lingua.
  2. Eseguire l’iterazione per le diverse lingue.
  3. Generare come output un elemento elenco (LI) per ciascuna lingua.
  4. All’interno dell’elemento elenco, generare come output un link alla lingua.
  5. Se la lingua ha una bandiera, generarla come output.
  6. Generare come output il nome della lingua.
  7. Chiudere tutti i tag annidati.

Sembra semplice? Scoprite come potete creare questi modelli per i vostri selettori di lingua.

Aggiungere un modello del selettore di lingua al vostro tema

WPML vi consente di aggiungere una directory con i modelli del selettore di lingua per il tema. Se state creando un tema da vendere, potete includere questi modelli nel vostro tema per permettere a tutti di utilizzarli. Se state personalizzando un tema dovete creare questi modelli del selettore di lingua personalizzato in un tema figlio, in modo da non perdere le vostre modifiche ad ogni aggiornamento del tema.

Il modello del selettore di lingua deve andare nella seguente struttura di cartelle:

my-theme/wpml/templates/language-switchers/my-template

Struttura di directory per i file del vostro selettore di lingua

Struttura di directory per i file del vostro selettore di lingua

In altri termini, dovete creare una cartella chiamata “wpml” all’interno della radice del vostro tema (o del tema figlio). In esso create le cartelle templates/language-switchers. All’interno della directory language-switchers potete creare delle sottodirectory per i diversi modelli che create (nel nostro esempio “my-template”).

All’interno della directory del modello (“my-template”) dovete avere i seguenti file, con i seguenti nomi:

  • Il file template.twig (obbligatorio)
  • Il file config.json (obbligatorio)
  • I file CSS (opzionali)
  • I file JS (opzionali)
  • La directory delle bandiere (opzionale)

Progettare il file template.twig

Il file template.twig è il modello attuale che state progettando. Utilizza la sintassi twig. Nel modello potete utilizzare questi variabili:

current_language_code (stringa)

css_classes           (stringa)

languages             (array)

code          (stringa)

url           (stringa)

flag_url      (stringa)

flag_title   (stringa)

native_name   (stringa)

display_name  (stringa)

is_current    (bool)

css_classes   (stringa)

Impostare le opzioni nel file config.json

Ogni selettore di lingua deve avere un file chiamato config.json, che fornisce informazioni di WPML sul selettore.

Ecco i campi per quel file:

  • name (obbligatorio): il nome del modello. Non serve apporgli il prefisso, WPML lo farà con il nome del tema o del plug-in. Questo è l’unico campo obbligatorio.
  • version (opzionale): la versione del modello. Questo è consigliato, perché forzerà l’aggiornamento dei fogli di stile e delle risorse javascript.
  • css (opzionale): come impostazione predefinita scansionerà e accoderà tutti i file CSS esistenti nella directory del modello. Tuttavia potete passare un array JSON di file CSS all’interno della directory del modello. Esempio: “css”: [“style.css”, “responsive.css”] .
  • js (opzionale): come impostazione predefinita scansionerà e accoderà tutti i file JS esistenti nella directory del modello. Tuttavia potete passare un array JSON dei file JS all’interno della directory del modello.

    Esempio: “js”: [“script.js”, “click-script.js”] . Nota: lo script deve essere scritto in puro Javascript, a meno che il tema o il plug-in includa di suo un’altra libreria.

  • flags_dir (opzionale): come impostazione predefinita scansionerà una directory “flags” esistente all’interno della cartella del modello o in quella specificata, se è definita.
  • flag_extension (opzionale): l’estensione del file per i file delle bandiere (png, svg, jpg, gif).
  • for (opzionale): per impostazioni predefinite il modello sarà disponibile per tutte le posizioni del sito (“menus”, “sidebars”, “footer”, “post_translations”, “shortcode_actions”). Tuttavia potete specificare una o più di queste posizioni in un array JSON.

    Esempio: “for”: [“sidebars”, “post_translations”] .

  • settings (opzionale): potete sovrascrivere le impostazioni dell’utente nell’IU dell’amministratore forzando alcune impostazioni. Passate semplicemente un oggetto JSON con il valore richiesto (0 o 1) per display_flags , display_names_in_native_lang , display_names_in_current_lang o display_link_for_current_lang.

    Esempio: “settings”: {“display_link_for_current_lang”: 1} .

Ecco l’esempio più semplice di un file config.json:


{

"name":           "My custom switcher",

}

Ecco un esempio più completo, con i campi (opzionali) aggiuntivi:


{

"name":           "Vertical List",

"version":         "1.0",

"css":            ["style.css"],

"js":             ["script.js"],

"flags_dir":      "super-flags",

"flag_extension": "png",

"for":            ["sidebars", "shortcode_actions"],

"settings":       {"display_link_for_current_lang": 1}

}

Esempi di selettore di lingua

Selettore di lingua a menu

Diciamo che volete creare una lingua personalizzata da far apparire nel menu, come questa:

Selettore di lingua personalizzato con codici ISO

Selettore di lingua personalizzato con codici ISO

Il menu conterrà soltanto il codice ISO per ciascuna lingua (nello stile maiuscolo).

  1. Create la cartella di un nuovo modello nel nostro tema: mytheme/wpml/templates/language-switchers/menu-iso-codes/
  1. In questa cartella aggiungete un file config.json con il contenuto sottostante:


{

"name" : "ISO codes for menus",

"for": ["menus"]

}

In sostanza definite il nome del modello (che verrà elencato nelle scelte disponibili) e in quale contesto questo modello sarà disponibile (solo per i menu).

  1. Ora aggiungete il file template.twig con il contenuto sottostante:


[ code|upper ]

Poiché è un modello di menu, è sufficiente rendere il contenuto dell’elemento “elemento del menu”. Qui visualizziamo il codice linguistico dopo che è stato processato dal filtro upper twig (consultate la documentazione qui http://twig.sensiolabs.org/doc/filters/upper.html).

Nota: è ancora possibile modificare le opzioni di visualizzazione (bandiera, lingua nativa, …) nell’interfaccia di amministrazione di WordPress, ma non avranno alcun effetto sul front-end perché il nostro modello personalizzato non le gestisce. Per evitare di confondere l’utente possiamo forzare la disattivazione di queste impostazioni. Ecco un file config.json potenziato:


{

"name" : "ISO codes for menus",

"for": ["menus"],

"settings": {

   "display_flags": 0,

   "display_names_in_native_lang": 0,

   "display_names_in_current_lang": 0

 }

}

E questo è l’output che verrà generato nell’interfaccia utente dell’amministrazione:

Selettore di lingua personalizzato nel back end.

Selettore di lingua personalizzato nel back end

Ottenete la fonte: potete trovare i file di questo esempio sulla nostra pagina GitHub dedicata.

Selettore di lingua ad elenco orizzontale

Vorreste visualizzare un selettore di lingua orizzontale minimalista con le sole bandiere e il nome della lingua come titolo del link. Inoltre utilizzerete la nostra collezione di bandiere SVG.

Selettore di lingua orizzontale con le sole bandiere

Selettore di lingua orizzontale con le sole bandiere

  1. Create la cartella del vostro modello personalizzato in mytheme/wpml/templates/language-switchers/custom-flags-with-titles/
  1. Importate la vostra collezione di bandiere nella cartella mytheme/wpml/templates/language-switchers/custom-flags-with-titles/flags/.

(fonte: https://github.com/lipis/flag-icon-css)

Nota: la raccolta di bandiere deve includere un file per ciascun codice linguistico, come questo: “en.svg”, “fr.svg”, “es.svg”, “pt-pt.svg”, …

  1. Create un file config.json come il seguente:


{

"name": "Custom flags with titles",

"for": ["sidebars"],

"flag_extension": "svg",

"settings": {

  "display_flags": 1,

  "display_names_in_native_lang": 1,

  "display_names_in_current_lang": 1

 }

}

Definite semplicemente l’estensione del file per le bandiere (“svg”), ma non serve definire la cartella delle bandiere, in quanto stiamo utilizzando il nome della cartella predefinito (“flags”).

  1. Create un file template.twig come il seguente:




<div class="[ css_classes ] custom-flags-with-titles">



<ul>

     {% <b>for</b> code, language <b>in</b> languages %}



<li class="[ language.css_classes ] item-custom-flags-with-titles">

           <a href="[ language.url ]">

              <img src="[ language.flag_url ]" title="[ language.flag_title ]">

           </a>

        </li>



     {% <b>endfor </b>%}

  </ul>



</div>



  1. Per avere qualche stile CSS dovete anche creare un file style.css come il seguente:


.custom-flags-with-titles li {

  list-style: none;

  float: left;

  margin: 0 3px;

}



.item-custom-flags-with-titles img {

  max-width: 32px;

  height: auto;

}

Ottenete la fonte: potete trovare i file di questo esempio sulla nostra pagina GitHub dedicata.