A la hora de internacionalizar (i18n) themes y plugins de WordPress se vuelve rápidamente necesario adoptar un flujo de trabajo que nos permita realizar los cambios con rapidez y eficacia.

Las primeras versiones de nuestros templates están repletas de cambios frecuentes, de nuevas cadenas que se cambian o que agregan, y requieren nuevas traducciones y actualizaciones.

A la hora de definir este workflow es importante poner un cuidado especial en definir las bases sobre las que luego trabajaremos. Ahí entra un correcto uso de los Text Domains, y de las funciones de internacionalización de WordPress.

Dejamos aquí el flujo de trabajo que utilizamos en Mínimo a la hora de desarrollar y traducir templates.

Definir y cargar el Text Domain

El «Text Domain» se traduce en español como «Dominio de texto». Este es un identificador único que ayudará a WordPress cargar las traducciones necesarias y específicas de nuestro theme o plugin.

El Text Domain se define en el encabezado de nuestro archivo style.css en el caso de themes. Este debe ser en minúscula, sin espacios y de ser necesarios deberemos utilizar guiones en vez de guiones bajos.

/*
* Theme Name: My Theme
* Author: Theme Author
* Text Domain: my-theme
*/

El paso siguiente es cargar nuestros archivos de traducciones (ya veremos cómo generarlos). Estos archivos elegimos guardarlos en una carpeta llamada «languages» que se encuentra el directorio raíz de nuestro theme WordPress.

function mytheme_setup{
    load_theme_textdomain( 'my-theme', get_template_directory() . '/languages'  );
}

En nuestro caso decidimos cargar estas traducciones en la acción «after_setup_theme» que se ejecuta luego que el theme es cargado por el proceso de inicialización de cada página.

add_action( 'after_setup_theme', 'mytheme_setup' );

Con esto tendremos la base para utilizar en nuestro template las funciones de localización, que luego nos permitirán generar nuestros archivos de traducción.

Utilizar funciones de localización

WordPress trae incorporadas funciones de localización. Estas nos permitan que todas las cadenas o «strings» visibles al usuario que utilizamos al desarrollar un template WordPress puedan ser traducidas o internacionalizadas.

Es una buena práctica en el desarrollo de nuestros themes y plugins no «hardcodear» ninguna cadena visible a los usuarios. Es decir, no dejar fijas, fuera de las funciones de localización ninguna de ellas.

¿Porqué? Es posible que en un comienzo no tengamos necesidad de crear nuestro theme o plugin con soporte para varios idiomas, pero esto suele cambiar, y convertirse en un problema y en horas perdidas que se pueden ahorrar realizando un trabajo correcto desde el comienzo.

¿Cómo? Como decíamos, teniendo la precaución que cada cadena o «string» sea «imprimida» en pantalla por una de las funciones de localización. WordPress trae muchas de ellas para facilitar la vida de los desarrolladores, pero veamos los dos ejemplos mas utilizados.

<?php _e("Developed by", "my-theme");  ?>
<?php echo '<a href="#">'.__("Link", "my-theme").'</a>'; ?>

Estas funciones tienen dos parámetros esenciales. El primero de ellos es la cadena a imprimir en pantalla y luego a traducir. El segundo de ellos es el Text Domain que hemos definido previamente.

Es importante tener la precaución de utilizar correctamente el segundo parámetro correspondiente al Text Domain, ya que será fundamental a la hora de generar los archivos de traducción.

Generar los archivos de traducción

WordPress utiliza la herramienta Getttext de GNU para manejar la internacionalización. Como todo software libre existen muchas maneras diferentes de implementarlo.

En Mínimo utilizamos la herramienta Open-Source Poedit para realizar los trabajos de traducción y generar los archivos necesarios, junto con la herramienta de linea de comando WP-CLI, la interfaz de lineas de comando para WordPress.

¿El objetivo? Generar los archivos .po y .mo para guardar en el directorio «languages» de nuestro theme o plugin. Para generarlos primero deberemos generar un archivo previo .pot.

Este archivo .pot recopilará todas las cadenas a traducir, es decir, todas las cadenas o «strings» que hemos internacionalizado utilizando las funciones de localización.

Debemos recordar que es normal en el proceso de desarrollo que tengamos que agregar, quitar o modificar cadenas. De ahí la importancia de establecer un flujo de trabajo dinámico cada vez que tengamos que generar estos tres archivos fundamentales.

Una vez instalada la interface de linea de comando de WordPress WP-CLI vamos a generar nuestro archivo pot con el siguiente comando.

wp i18n make-pot ~/Wordpress/wp-content/themes/my-theme/

Por supuesto debemos sustituir el parámetro final por la dirección local de nuestro theme. Esto generará un archivo .pot en dicho directorio.

Utilizar Poedit

Una vez que tengamos este archivo base con las cadenas traducibles instalaremos y abriremos el editor de traducciones Poedit.

Abrimos el archivo pot recientemente generado. Estos archivos, como hemos dicho, no contienen traducciones, son plantillas o catálogos con las traducciones a realizar. Una vez abierto y cargado en el editor podremos crear un archivo .po de traducción haciendo click en «Crear traducción nueva».

Se nos preguntará el idioma de la traducción a realizar. Debemos tener la precaución de hacer coincidir esta con el código del idioma correcto, según nuestro interés.

Poedit creando una traducción para el idioma es_ES

Al guardarlo Poedit generará los archivos .po y .mo para finalmente guardarlos en el archivo el directorio «languages» de nuestro theme o plugin.

¿Qué ocurre si generamos una nueva cadena visible al usuario?

Queda simplemente generar un nuevo pot con la interface de lineas de comando. Luego abrir nuestro archivo de traducción .po para el idioma a trabajar y actualizarlo con el nuevo pot, desde la opción del menú: «Catálogo > Actualizar desde archivo POT».

Poedit se encargará de dejar nuestras traducciones ya realizadas y de actualizar y agregar las nuevas cadenas a traducir.

Esto se convierte fácilmente en un proceso sencillo de tres pasos, que nos permite aprovechar la magia de la internacionalización en la creación profesional de themes y plugins para WordPress.