Preparar tema WordPress para traducción

Preparar tema WordPress para traducción:

Hoy en día no tiene sentido, con el grado de avance de WordPress, publicar un tema nuevo sin que venga preparado para traducciones, para que los usuarios puedan fácilmente añadir la localización para su idioma. Si queremos que nuestro tema sea popular, que llegue a todas partes y sea fácil de utilizar por usuarios de WordPress de cualquier país, no tienes excusa para facilitar su internacionalización.
Además, es muy sencillo preparar un tema WordPress para traducción, internacionalización, localización, como quieras llamarlo, así que vamos a verlo ya mismo …

Los 5 pasos para preparar un tema WordPress para traducción que vamos a seguir son los siguientes:

1. Cargar un dominio de texto
2. Procesar los mensajes de texto con funciones WordPress
3. Extraer los mensajes con Poedit
4. Ofrecer una traducción para cada mensaje y crear un archivo de idioma para una traducción concreta
5. Decir a WordPress que active la localización y cargue el archivo de idioma

Vamos a ello …

1. Cargar un dominio de texto

Lo primero que hay que hacer es cargar un dominio de texto añadiendo la siguiente línea al archivo functions.php de tu tema:

load_theme_textdomain('mitema', get_template_directory() . '/languages');

El primer argumento debe ser un identificador único (una buena práctica es usar el nombre de tu tema); lo que define el dominio del tema, ya que el texto para la traducción no estará en los archivos de instalación de WordPress. El segundo argumento define la carpeta de los archivos de idioma. Para cargar estos archivos la función debe estar unida a la acción after_setup_theme action:

add_action('after_setup_theme', 'my_theme_setup');
function my_theme_setup(){
    load_theme_textdomain('mitema', get_template_directory() . '/languages');
}

2. Procesar los mensajes de texto con funciones WordPress

Después de editar el fichero functions.php, el siguiente paso es revisar el código de los archivos del tema, encontrar los mensajes que tienen que traducirse y procesarlos con la función WordPress adecuada. Los dos más importantes, y que se usan más a menudo, son _e($text_message) y __($text_message).
La primera función busca la traducción del $text_message y lo imprime. Si la traducción no existe entonces imprime $text_message. Esta función se usa para los mensajes de texto que no sean funciones PHP, ya que imprime el resultado. Por ejemplo, eliges la siguiente línea:

echo ‘Hello user’;

Y hay que transformarla a:

_e(‘Hello user’,’mitema’);

La segunda función busca la traducción del $text_message y lo devuelve. Si no existe traducción entonces devuelve el $text_message. Esto se usa para el texto que esté en funciones PHP. Por ejemplo:

the_content( ‘Read more’ );

Hay que transformar la llamada de la función a:

the_content( __(‘Read more’,’mitema’) );

A veces un mensaje de texto incluye datos dinámicos, como números de una variable PHP. En estos casos usaremos la función PHP printf para producir la cadena del mensaje final:

$results_found = 12;
$message = sprintf( __(‘%s results found’ , ‘mitema’) , $results_found );

Singular y plural
WordPress ofrece una función para la traducción singular y plural del mismo mensaje de texto:

_n( $single, $plural, $number, $domain )

El primer argumento es el texto que se usará para el singular, y el segundo es el texto que se usará para el plural. El tercer argumento es el número con el que comparar para decidir cual usar.
Aunque la función _n() está incluida en WordPress no se recomienda usarla ya que el software de traducción solo usa el primer parámetro de una función, así que no se procesarían estos dos mensajes de texto. En su lugar podemos usar la declaración PHP if:

if($results_found == 1)
$message = __(‘1 result found’ , ‘my-text-domain’);
else
$message = sprintf( __(‘%s results found’ , ‘my-text-domain’) , $results_found );

3. Extraer los mensajes con Poedit

Una vez hemos procesado cada mensaje de texto con las funciones antes mencionadas nuestro tema está listo para traducción. A estos efectos hay tres tipos de ficheros de idioma:

1. El archivo .POT contiene una lista de todos los mensajes traducibles de tu tema
2. El archivo .po se crea cuando traducimos un fichero POT a un idioma concreto
3. El archivo .mo es un archivo binario que lo crea automáticamente Poedit. Este es el que WordPress lee para traducir temas y plugins

Creamos el POT

Lo primero es crear el fichero POT, que contiene todos los mensajes del código del tema y que será el archivo que el traductor use para traducir los mensajes de otro fichero de idioma. Aunque hay varias aplicaciones para editar y crear ficheros de idioma te recomiendo Poedit, que es multiplataforma y es el que yo uso.

1. Abre Poedit y crea un nuevo catálogo
2. Completa la información del catálogo en la pestaña “Información del proyecto”
   
   
3. En la pestaña “Rutas” identifica la carpeta donde Poedit buscará los archivos con el código que contiene los mensajes de texto traducibles. Estas carpetas son relativas a la carpeta de nuestro archivo de idioma así que guardaremos el archivo en una carpeta de la carpeta de tu tema, por lo que añadiremos ..:
   
   
4. En la pestaña “Palabras clave” definiremos las funciones WordPress utilizadas para traducir mensajes (recuerda que Poedit no es solo para WordPress). En nuestro tema las dos palabras clave utilizadas han sido __ y _e.
   
   
   
5. Una vez que hagas clic en “Aceptar” Poedit busca en las carpetas que le hemos dicho en la pestaña “Rutas” y te listará los mensajes de texto encontrados en los archivos del tema.
6. Guarda el archivo POT en una carpeta llamada languores dentro de la carpeta de tu tema.
   
   
   

Este archivo POT recién creado en realidad no lo necesita WordPress, es simplemente la plantilla que contiene las cadenas de mensajes traducibles, que puedes facilitar al traductor para que lo traduzca y te devuelva un fichero .po.

4. Ofrecer una traducción para cada mensaje y crear un archivo de idioma para una traducción concreta

Como ya tenemos el POT ahora solo hay que empezar a traducir cadenas de texto con Poedit, la aplicación, la primera vez que guardes cambios crea el solito los ficheros .po y .mo.

1. Empieza a elegir cadenas de texto de la lista y traduce una a una en los campos inferiores
   
   
2. Sigue traduciendo hasta que estén todas las cadenas de texto traducidas a tu idioma
3. Guarda y verás los ficheros .po y .mo generados automáticamente en la carpeta languages
   
   
   

5. Decir a WordPress que active la localización y cargue el archivo de idioma

Una vez hayamos creado los ficheros .po y .mo ya podemos decir a WordPress que active la localización y cargue los archivos del idioma. Edita el archivo wp-config.php, que encontrarás en la carpeta raíz de la instalación de WordPress.
Lo que hay que hacer es modificar la variable WPLANG al idioma que queremos usar. Por ejemplo:

define('WPLANG', '');

Pasaría a quedar así si vamos a usar la localización (traducción) al español de España:

define('WPLANG', 'es_ES');

Si WordPress encuentra un archivo de traducción al “español de España” como hemos definido en la configuración del catálogo, en la carpeta que configuramos en el primer paso de este tutorial, entonces mostrará los mensajes traducidos a este idioma en el tema y los visitantes lo verán en español de España. Si no lo encontrara entonces mostraría los mensajes por defecto.

EXTRA: Preparar para traducción plugins

Aunque no iba de plugins esta guía no está de más explicar como se prepara para traducción un plugin, máxime cuando hay pasos que se repiten, así que vamos a ver lo que cambia a la hora de internacionalizar plugins.
Al igual que hacemos con el tema, lo primero es decirle a WordPress donde encontrará los archivos de idioma, añadiendo la siguiente función, en este caso en el archivo principal del plugin:

load_plugin_textdomain('miplugin', false, basename( dirname( __FILE__ ) ) . '/languages' );

El primer parámetro define el dominio del texto, a ser posible usando el nombre del plugin, ya que debe ser único. El segundo parámetro define la ruta de la carpeta donde estará el fichero .mo. Como corresponde a una función anticuada, que fue válida hasta WordPress 2.7, especificaremos como valor false. El tercer parámetro es la carpeta donde están los archivos de idioma, en este caso asumimos que hay una carpeta llamada language dentro de la carpeta del plugin.
También, para cargar los archivos de idioma tenemos que añadir un ‘hook‘ y enlazar esta función en la acción init de WordPress:

function traduccion_miplugin()
{
load_plugin_textdomain('miplugin', false, basename( dirname( __FILE__ ) ) . '/languages' );
}
add_action('init', 'traduccion_miplugin');

Para terminar tendremos que procesar los mensajes de texto igual que hemos hecho con el tema, siguiendo los pasos 2 al 5, usando las funciones que a estas alturas ya conoces: _e($text_message) y __($text_message). Una vez procesado todo y creados los ficheros de traducción nuestro plugin estará listo para traducción.
Más información:

• Traduciendo WordPress
• l18n para desarrolladores WordPress