Muchos sitios web (y temas) necesitan un intercambiador de idiomas personalizado que se integre adecuadamente al diseño general de su gráfica. Este tutorial explica cómo diseñar tales intercambiadores utilizando solamente plantillas HTML, sin escribir ningún código PHP.

Introducción a las plantillas Twig para intercambiador de idiomas

Twig es un motor de plantillas que permite diseñar utilizando HTML y seudocódigo

Este es un ejemplo de una plantilla Twig:

La función de esta plantilla:

  1. Abre el contener DIV y las etiquetas UL para el intercambiador de idiomas.
  2. Itera por los diversos idiomas.
  3. Genera un elemento de lista (LI) para cada idioma.
  4. Dentro del elemento de la lista, genera un enlace al idioma.
  5. Si el idioma cuenta con bandera, la muestra.
  6. Muestra el nombre del idioma.
  7. Cierra todas las etiquetas relacionadas.

¿Suena simple? Veamos cómo crear estas plantillas para su propio intercambiador de idiomas.

Agregar una plantilla de intercambiador de idiomas a su tema

WPML permite agregar un directorio con plantillas de intercambiador de idiomas al tema. Si está construyendo un tema para comercializar, puede agregar esas plantillas para que todos tengan acceso a ellas. Si está personalizando un tema, debería integrar estas plantillas para intercambiadores de idiomas personalizados en un tema hijo a efectos que las modificaciones no se pierdan en cada actualización.

La plantilla del intercambiador de idiomas debe tener la estructura de carpetas siguiente:

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

Estructura de carpetas para los archivos del intercambiador de idiomas
Estructura de carpetas para los archivos del intercambiador de idiomas

Esto implica que deberá crear la carpeta “wpml” dentro de la raíz del tema (o tema hijo). Dentro de ella, cree las carpetas templates/language-switchers. Dentro de la carpeta language-switchers, puede crear subdirectorios para las distintas plantillas que deba tener (en nuestro ejemplo: “my-template”).

Los archivos siguientes, con los nombres detallados a continuación, deben estar presentes dentro del directorio de la plantilla (“my-template”), :

  • template.twig (obligatorio)
  • config.json (obligatorio)
  • Archivos CSS (opcional)
  • Archivos JS (opcional)
  • Directorio de banderas (opcional)

Diseño del archivo template.twig

El archivo template.twig es la plantilla real sobre la cual realizará el diseño. Utiliza sintaxis Twig. Dentro de la plantilla, se posible utilizar las variables siguientes:

current_language_code (cadena)

css_classes           (cadena)

languages             (arreglo)

code          (cadena)

url           (cadena)

flag_url      (cadena)

flag_title   (cadena)

native_name   (cadena)

display_name  (cadena)

is_current    (boleano)

css_classes   (cadena)

Definir las opciones en el archivo config.json

Todo intercambiador de idiomas debe tener un archivo denominado config.json, el cual aporta información sobre el intercambiador a WPML.

He aquí los campos para ese archivo:

  • name (obligatorio): nombre de la plantilla. No hay necesidad de incluir el prefijo; WPML lo hará en el nombre del tema o plugin. Este es el único campo obligatorio.
  • version (opcional): versión de la plantilla. Se recomienda su utilización porque fuerza el refresco de las hojas de estilo y de los recursos javascript.
  • css (opcional): por defecto, realizará un escaneo y armará una cola de todos los archivos CSS existentes en el directorio de la plantilla. No obstante, es posible pasar un arreglo JSON de archivos CSS dentro del directorio de la plantilla. Ejemplo: «css»: [«style.css», «responsive.css»] .
  • js (opcional): por defecto, realizará un escaneo y armará una cola de todos los archivos JS existentes en el directorio de la plantilla. No obstante, es posible pasar un arreglo JSON de archivos JS dentro del directorio de la plantilla.

    Ejemplo: «js»: [«script.js», «click-script.js»]. Advierta que el script debería ser escrito en Javascript puro, a menos que el tema o el plugin incluya alguna otra librería propia.

  • flags_dir (opcional): por defecto verificará la existencia de un directorio «flags» dentro de la carpeta de la plantilla o en otro lugar especificado, si estuviere definido.
  • flag_extension (opcional): extensión del archivo para los archivos de banderas (png, svg, jpg o gif).
  • for (opcional): por defecto, la plantilla está disponible para todos los lugares del sitio (“menus”, «sidebars», «footer», «post_translations», «shortcode_actions»). No obstante, es posible especificar uno o más de dichos lugares en un arreglo JSON.

    Ejemplo: «for»: [«sidebars», «post_translations»] .

  • settings (opcional): es posible sobrescribir la configuración del usuario desde la IU de administración  forzando algunos parámetros. Simplemente pase un objeto JSON con el valor deseado (0 o 1) para display_flags , display_names_in_native_lang , display_names_in_current_lang o display_link_for_current_lang.

    Ejemplo: «settings»: {«display_link_for_current_lang»: 1} .

He aquí el ejemplo más básico de un archivo config.json:


{

"name":           "My custom switcher",

}

Y este es un ejemplo más completo, con campos adicionales (opcional):


{

"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}

}

Ejemplos de intercambiadores de idiomas

Intercambiador de idiomas de menú

Supongamos que usted desea crear un idioma personalizado para que aparezca en el menú, como el que se muestra a continuación:

Intercambiador de idiomas personalizado con códigos ISO
Intercambiador de idiomas personalizado con códigos ISO

El menú contendrá solamente el código ISO para cada idioma (en estilo mayúsculas).

  1. Cree una carpeta de plantillas nueva en su tema: mytheme/wpml/templates/language-switchers/menu-iso-codes/
  1. En dicha carpeta, agregue un archivo config.json con el contenido que se muestra debajo:


{

"name" : "ISO codes for menus",

"for": ["menus"]

}

Básicamente, usted debe definir el nombre de la plantilla (que aparecerá listado en las opciones disponibles) y el contexto en el cual dicha plantilla estará disponible (solo para menúes).

  1. Ahora, agregue el archivo template.twig con el contenido que se muestra a continuación:

[ code|upper ]

Dado que es la plantilla del menú, simplemente debe generar el contenido del elemento del menú. Aquí mostramos el código de idioma luego de ser procesado por el filtro superior de la rama (puede consultar la documentación en http://twig.sensiolabs.org/doc/filters/upper.html).

Nota: es posible cambiar las opciones de presentación (bandera, idioma nativo, etc.) en la interfaz de administración de WordPress pero no surtirá efecto visible porque la plantilla personalizada no lo gestiona. Para evitar la confusión del usuario, puede forzar a que dichos parámetros se muestren inhabilitados. Este es un ejemplo de un archivo config.json mejorado:


{

"name" : "ISO codes for menus",

"for": ["menus"],

"settings": {

   "display_flags": 0,

   "display_names_in_native_lang": 0,

   "display_names_in_current_lang": 0

 }

}

Y aquí cómo se mostrará en la interfaz de administración de usuario.

Intercambiador de idiomas en el backend
Intercambiador de idiomas en el backend

Obtenga la fuente: puede encontrar los archivos de este ejemplo en nuestra página GitHub.

Intercambiador de idiomas de lista horizontal

Usted podría querer mostrar un intercambiador de idiomas minimalista conformado solamente con banderas y el nombre del idioma en el título del enlace. Además, podría querer utilizar su propio conjunto de banderas SVG.

Intercambiador de idiomas de banderas exclusivamente
Intercambiador de idiomas de banderas exclusivamente

  1. Cree una carpeta de plantilla personalizada en mytheme/wpml/templates/language-switchers/custom-flags-with-titles/
  1. Importe el conjunto de banderas a la carpeta mytheme/wpml/templates/language-switchers/custom-flags-with-titles/flags/.

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

Nota: el conjunto de banderas debe incluir un archivo para cada código de idioma que luzca como: “en.svg”, “fr.svg”, “es.svg”, “pt-pt.svg”, …

  1. Cree un archivo config.json como el que se muestra a continuación:


{

"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

 }

}

Simplemente debe definir la extensión del archivo para las banderas (“svg”), sin necesidad de definir la carpeta de banderas dado que utilizamos el nombre de carpeta por defecto (“flags”).

  1. Cree el archivo template.twig como se muestra en el ejemplo siguiente:

  1. A efectos de poder disponer de estilos CSS, también deberá crear un archivo style.css como el que se muestra a continuación:


.custom-flags-with-titles li {

  list-style: none;

  float: left;

  margin: 0 3px;

}



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

  max-width: 32px;

  height: auto;

}

Obtenga la fuente: puede encontrar los archivos de este ejemplo en nuestra página especial de GitHub.