Localización con WordPress

Este artículo debería llamarse “Sistema de traducción de themes para WordPress – Parte 2″, ya que en verdad es una especie de continuación de un artículo de aNieto2K en el que explica cómo funciona el sistema de… bueno, lo que dice en el título.

Creo que hubieron algunas cosas que faltó cubrir en ese post (seguramente porque este tipo siempre anda con un millón de proyectos), y sobre los cuales puedo aportar algo: cómo marcar las cadenas para localización y cómo generar automáticamente el catálogo de cadenas de localización.

Dado que en el último tiempo he estado trabajando (jugando, en verdad) en cuestiones relacionadas con esto, acá va mi grano de arena para Castellanizar la blogósfera

Marcando las cadenas

Como bien explica Nieto en su post, existen dos posibilidades para marcar las cadenas a localizar: _e('texto' , 'nombre_del_tema'); y __('texto' , 'nombre_del_tema');. Sin embargo, el propósito de cada una de estas alternativas es ligeramente distinto.

Para traducir un texto “simple”, es decir, que es parte del código XHTML del tema, _e() es ideal. Tomaré un ejemplo de [Satori->]:

<li><h2>Artículos relacionados</h2></li>

Se transforma en:

<li><h2><?php _e('Artículos relacionados','satori')?></h2></li>

Pero ahora viene lo “entretenido”: ¿qué pasa si es necesario traducir un texto que debe pasar como argumento en una función? Para eso está __()

<h2><?php comments_number('Aún no hay comentarios','Un Comentario','% Comentarios');?></h2>

Se transforma en:

<h2><?php comments_number(__('Aún no hay comentarios','satori_domain'),__('Un Comentario','satori_domain'),__('% Comentarios','satori_domain')); ?></h2>

O más simple:

<?php función('argumento'); ?>

Se transforma en:

<?php función(__('argumento','tema')); ?>

Ahora, a armar el catálogo.

Confeccionar un catálogo de traducciones con Gettext

Una vez que hemos marcado todas las cadenas a traducir es necesario generar un archivo “PO” (Portable Object) que actúa como un “catálogo” de todas ellas. Es posible generarlo manualmente, pero por lejos lo ideal es aprender a utilizar Gettext, un programa que realizará automáticamente una tarea que de otro modo sería muy, muy tediosa.

Es posible que Gettext esté instalado en tu web host, por lo que puedes ejecutarlo remotamente si tienes acceso a la línea de comandos (por ejemplo, yo lo he utilizado en DreamHost vía SSH) o bien puedes bajarlo a tu PC para ejecutarlo localmente. No necesita grandes recursos, y está disponible para Windows (vía gnuwin32) y, por supuesto, también para Linux. La versión para Windows trae un instalador tipo wizard (asistente), por lo que es muy fácil de utilizar. Gettext, por su parte, sólo se ejecuta desde la línea de comandos, por lo que no es tan “amistoso”.

Ocupando Gettext

Gettext es en realidad un conjunto de programas con distintas funciones. Nuestro principal aliado será xgettext, el que examina los archivos en busca de las cadenas para traducir y confecciona el catálogo. Para utilizarlo, puedes seguir estos pasos:

  1. Primero, confecciona un archivo de texto que contenga una lista de los archivos que contienen cadenas que deben ser traducidas —típicamente serán los archivos PHP del tema— de forma relativa al directorio en que guardarás este archivo. Este es el archivo que utilizo en [Satori->] (lo he llamado file-list.txt):

    archive.php
    category.php
    comments.php
    footer.php
    functions.php
    header.php
    index.php
    search.php
    single.php
    code/commonfooter.php
    code/dondeestoy.php
    code/navlinks.php
    code/post-format.php
    code/singlefooter.php
    code/social-bookmarks.php
    code/no-posts.php

  2. Ingresa a la línea de comandos. Una vez allí, ingresa lo siguiente: PATH c:archivos de programagnuwin32bin (suponiendo que esa es la ubicación donde está instalado Gettext). De esta manera, podrás ejecutar los programas que están en ese directorio desde cualquier directorio en el que te encuentres.
  3. Ingresa al directorio donde estás trabajando con el tema
  4. Ejecuta la siguiente orden: xgettext ––keyword=__ ––keyword=_e ––language=PHP ––files-from=file-list.txt ––from-code=UTF-8 -d es —asumiendo que tu lista de archivos se llama file-list.txt y las cadenas a traducir están codificadas como UTF-8. Tu archivo resultante se llamará es.po

De esta manera, tu catálogo de traducciones ya se habrá generado, y ahora es hora de editarlo. Recomiendo encarecidamente que utilices poedit, un programa disponible para Windows y Linux que te proveerá una interfaz gráfica muy fácil de usar.

poedit.png

Ya terminada la traducción, debes recordar cambiar los valores predeterminados de la cabecera, lo que en poedit puedes hacer dirigiéndote a Catálogo > Opciones: podrás ingresar el nombre y versión del proyecto, el equipo que trabajó en la traducción, idioma, juego de carácteres. El cuadro de formas plurales puede dejarse en blanco. Al guardar el catálogo poedit generará automáticamente el archivo es.mo que es el que finalmente se utilizará para la traducción del tema.

Hasta aquí, tenemos casi todo cubierto, sólo falta una cosa: ¿qué pasa si haces modificaciones al tema y debes agregar nuevas cadenas de localización? ¿Debes generar nuevamente el catálogo y perder todas las traducciones que ya has hecho? No, puedes agregar nuevas cadenas a tu catálogo ya traducido utilizando el siguiente comando:

xgettext ––keyword=__ ––keyword=_e ––language=PHP ––files-from=file-list.txt -j ––from-code=UTF-8 -d es

Nótese el -j, una opción que le indica a xgettext que deberá unir (join) las nuevas cadenas al catálogo es.po

Ahora sí, todo está dispuesto para que te lances a traducir temas.

Si estás trabajando en la traducción/localización de un tema, asegúrate de inscribirlo en la lista de themes en traducción (mientras estés trabajando en él) y luego en la lista de themes ya traducidos.

Explicación de los comandos gettext

Me he guardado para el final la explicación de aquella maravillosa línea de comandos que hemos utilizado para generar el catálogo de traducciones:

xgettext ––keyword=__ ––keyword=_e ––language=PHP ––files-from=file-list.txt -j ––from-code=UTF-8 -d es

xgettext
invoca al programa xgettext
––keword=__ ––keyword=_e
indica que las cadenas a traducir son aquellas marcadas como __() y _e()
––language=PHP
indica que el lenguaje de programación de los archivos a procesar es PHP
––files-from=file-list.txt
indica que debe procesar la lista de archivos guardada en file-list.txt
-j
indica que debe unir las nuevas cadenas al catálogo existente. Sólo debe utilizarse si no ya hay un catálogo existente
––from-code=UTF-8
indica que la codificación de los archivos a procesar es UTF-8
-d es
indica que el archivo de salida (el catálogo) deberá llamarse es.po

Una buena idea es crearse un archivo BAT con estas órdenes:

PATH c:archivos de programagnuwin32bin
xgettext ––keyword=__ ––keyword=_e ––language=PHP ––files-from=file-list.txt -j ––from-code=UTF-8 -d es

Así lo puedes invocar fácilmente o copiar y pegar al directorio del theme en el que estés trabajando