Cómo hacer un plugin de WordPress listo para traducción

1. Escribe pensando en la localización

No uses echo o print() para generar texto de salida, en su lugar utiliza las funciones de WordPress __() y _e():

/** No compatible con localización */
echo "Bienvenido a mi plugin";    
// O
print("Bienvenido a mi plugin");

/** Compatible con localización */
_e('Bienvenido a mi plugin', 'mi-plugin');
// O
$mi_texto = __('Bienvenido a mi plugin', 'mi-plugin');
echo $mi_texto;

_e() y __() proporcionarán la traducción — en el idioma actual — del texto proporcionado como primer parámetro. _e() mostrará el texto mientras que __() lo devolverá.

El segundo parámetro es el dominio de texto, lo usarás para indicarle a WordPress que el texto proporcionado como primer parámetro pertenece a este plugin. Puedes usar cualquier nombre que desees pero yo prefiero usar el mismo nombre que usé para el archivo o directorio del plugin, lo encuentro más intuitivo.

¿Cómo mostrar texto dinámico como: "Hola <usuario>"?

Con __() y sprintf():

/** Obtener el nombre de usuario */
$usuario = 'Magictrick';

/** No compatible con localización */
echo "Hola $usuario";     

/** Compatible con localización */
printf(__('Hola %s', 'mi-plugin'), $usuario);
// O 
$mi_texto = sprintf(__('Hola %s', 'mi-plugin'), $usuario);
echo $mi_texto;

2. Prepara los archivos .pot/.po/.mo

Definiciones

• El archivo .pot: es puesto a disposición por el desarrollador del plugin y se usa como punto de partida para crear nuevas traducciones, WordPress no lo usa.
• Un archivo .po: es un archivo de traducción que tú o alguien más comenzó, y quizás completó, WordPress no lo usa.
• Un archivo .mo: es creado automáticamente por Poedit cuando guardas un archivo .po, todo lo que puedes hacer con estos archivos es subirlos o volver a subirlos cuando creas o actualices un archivo .po. WordPress obtiene las traducciones de los archivos .mo.

Abre Poedit y crea un nuevo catálogo (Archivo › Nuevo catálogo...) con estos ajustes:

• Información del proyecto: Usa tu información (o la de tu equipo), el idioma y país deben coincidir con el idioma por defecto de tu plugin
• Rutas:
  • Ruta base: .
  • Rutas: elimina todas y agrega .., (almacenaremos los archivos de idioma en un subdirectorio del plugin llamado languages)
• Palabras clave: elimina todas y agrega __ y _e

Guarda el catálogo como /mi_wordpress_blog/wp-content/plugins/mi-plugin/languages/<strong>mi-plugin.pot</strong> y escanea los archivos de tu plugin en busca de texto traducible presionando el botón de actualizar. Cuando termine la actualización cierra ese catálogo, no necesitarás actualizar ese archivo a menos que agregues nuevas cadenas traducibles (es decir, encerradas en __() o _e()) a tu plugin.

Ahora creemos la primera traducción (usaré fr_FR):

Usando Poedit, crea un catálogo desde un archivo POT (Archivo › Nuevo catálogo desde archivo POT...):

• Información del proyecto: Usa tu información (o la de tu equipo), cambia el idioma y país, usaré Francés y Francia
• Rutas: No cambies
• Palabras clave: No cambies

Guarda el catálogo como /mi_wordpress_blog/wp-content/plugins/mi-plugin/languages/<strong>mi-plugin-fr_FR.po</strong>. Traduce algunas o todas las cadenas, guarda nuevamente el archivo .po, sube ambos archivos .po y .mo.

Nota que cada vez que guardas un archivo .po se genera un archivo .mo con el mismo nombre, el nombre del archivo .po es crucial, está compuesto por la concatenación del dominio de texto del plugin (mi-plugin) y el locale del idioma (fr_FR), siempre nombra tus archivos .po para plugins así: [dominiodetexto]-[locale].po, aquí algunos ejemplos:

• Italiano/Italia: wpcf7-it_IT.po
• Portugués/Brasil: wpcf7-pt_BR.po
• Árabe: wpcf7-ar.po... ¡Sí!

Cuando el plugin sea actualizado con nuevo texto, actualiza el archivo po, traduce las nuevas cadenas y vuelve a subir los archivos .po y .mo

3. Indica al plugin que cargue el texto traducido para el idioma actual

En algún lugar de tu plugin, debes decirle a WordPress que use tu archivo .mo, puedes hacerlo usando este código al principio de tu archivo de plugin:

function mi_plugin_init() {
  load_plugin_textdomain( 'mi-plugin', false, 'mi-plugin/languages' );
}
add_action('init', 'mi_plugin_init');

Reemplaza mi-plugin con el nombre de tu plugin en el 1er y 3er parámetro de la función load_plugin_textdomain.

4. Prueba y soluciona problemas

Algunas razones por las que puede no funcionar:

• Las cadenas no se importaron al archivo .pot o .po
  • → Configuración incorrecta del catálogo (ruta o palabras clave o ambas)
• El texto no se traduce en el sitio de WordPress
  • → Archivo .mo para ese idioma faltante o con nombre incorrecto
  • → Dominio de texto no usado (reemplaza _e('mi texto') con _e('mi texto', 'mi-plugin'))
  • → Dominio de texto no cargado (usa el ejemplo anterior con los parámetros correctos, WP no te avisará sobre errores)