Los 6 secretos para internacionalizar bien tu plugin

Nelson Mandela dijo una vez:

Si hablas a un hombre en una lengua que entiende, el mensaje llega a su cabeza. Si le hablas en su lengua, le llega a su corazón.

Hace un par de semanas hablábamos sobre cómo internacionalizar tu instalación WordPress y, así, ofrecer tus contenidos en múltiples idiomas. Teniendo en cuenta que tu web es la primera cosa que muchos de tus potenciales clientes van a conocer lde ti, no está de más que te dirijas a ellos en su idioma (si puedes), ¿no? Ya vimos que hacerlo tiene ciertas ventajas… y el amigo Mandela las resume muy bien ?

Este esfuerzo por traducir e internacionalizar tu trabajo no debería limitarse únicamente a tu web. Si eres un desarrollador WordPress que ofrece plugins o temas, también tendrás que dedicar un poco de tiempo y esfuerzo en internacionalizarlo para que tus usuarios puedan disfrutarlo en su idioma, quedando perfectamente integrado dentro de su escritorio. Además, podrás ampliar tu negocio llegando a otros mercados que posiblemente no comprarían tu producto si estuviera sólo en tu idioma.

¿No sabes cómo hacerlo? ¿Crees que es muy complicado? Tranquilo, que nosotros te explicamos los 6 secretos para internacionalizar y traducir correctamente tu plugin.

Secreto 1. El código y textos originales deben estar en inglés

Quiero pensar que este es un secreto a voces y que, por lo tanto, todo el mundo es consciente de él. Pero como estoy seguro de que todavía hay alguno de vosotros que anda un poco despistado, creo que no está de más recordarlo. Cuando estés creando un nuevo plugin o tema, no lo hagas en español o en tu idioma:

La mayoría de los desarrolladores están acostumbrados a trabajar en inglés. De hecho, las propias palabras reservadas del lenguaje están en inglés (por eso escribimos function, if o while y no función, si o mientras). Si escribes tu código en inglés harás que la vida de todo el mundo sea mucho más sencilla:

1. El ecosistema WordPress es de código abierto. Los plugins y temas están escritos en PHP y JavaScript. Así que ten en cuenta que la gente querrá poder leer y entender tu código.
2. No tienes por qué ser tú quien internacionalice tu plugin o tema; en teoría podría encargarse cualquiera. Es más fácil que el traductor conozca el inglés que el catalán, por ejemplo.
3. Las funciones de internacionalización (hablaremos de ellas en un par de líneas) están pensadas para ser usadas con cadenas de texto en inglés.

El ejemplo anterior está escrito en catalán. Aunque es un idioma que se parece mucho al castellano y, por lo tanto, podrías llegar a deducir qué pone (quizás lo más difícil es descubrir que «cerca» es «buscar»), está claro que la versión en inglés será mucho más comprensible para cualquier desarrollador:

Secreto 2. Conoce las funciones de internacionalización de WordPress

La internacionalización de plugins y temas en WordPress funciona con una biblioteca llamada gettext. En general, gettext funciona de la siguiente forma:

1. En lugar de escribir o manipular directamente cadenas de texto, las «envuelves» en funciones de gettext.
2. Usando las herramientas adecuadas, exploras todos los ficheros de tu proyecto y extraes todas las cadenas de texto «traducibles» (es decir, aquellas cadenas que definiste con las funciones de gettext). Esto generara un fichero con extensión .pot que contiene la lista con todos los textos esperando ser traducidos.
3. Este fichero se pasa a un traductor y genera una versión para su propio idioma con la extensión .po. Este nuevo fichero contiene la lista con todas las cadenas de texto originales junto con su correspondiente traducción.
4. Estos ficheros .po se compilan en otro formato llamado .mo para que todo funcione un poco más rápido. Son estos .mo los que se acaban usando en producción.

¿Y todo este rollo qué quiere decir para ti, desarrollador? Pues que si quieres que la siguiente cadena de texto se pueda traducir:

tendrás que escribirla de la siguiente forma:

Como puedes ver, en lugar de hacer echo del texto directamente, lo que hacemos es un echo del resultado que nos da la función __(). Esta es una de las muchas funciones que incluye la librería gettext, y lo que hace básicamente es devolver la versión traducida de la cadena de texto que le pasamos como parámetro. Si no existiera dicha traducción, se usaría la versión en inglés.

Si aplicamos este sencillo paso a todas las cadenas de texto, tendremos el plugin casi listo para internacionalizarlo; sólo nos quedan dos pasos. En primer lugar, tendremos que generar el fichero .pot que te comentaba antes usando la herramienta makepot.php de WordPress (la puedes descargar de este repositorio Subversion). Desde un terminal, y suponiendo que estás en el directorio del plugin, haz lo siguiente:

esto dejará el fichero plugin-name.pot dentro del directorio languages de tu plugin.

Por otro lado, tenemos que indicarle a WordPress que nuestro plugin puede internacionalizarse y que, por lo tanto, debe usar las traducciones que haya disponibles. Para ello, basta con que el fichero principal de tu plugin (normalmente, plugin-name/plugin-name.php) sea parecido a esto:

donde la línea 15 especifica el Text Domain, cuyo valor se corresponde al segundo parámetro de las funciones gettext que hemos visto unas líneas más arriba (lo más cómodo es que sea el nombre del plugin), la línea 16 especifica el Domain Path, que indica la carpeta donde encontrar el fichero .pot y en la línea 27 definimos la función plugin_name_i18n que sirve para cargar las traducciones. Si faltara alguno de estos tres elementos, la internacionalización no funcionaría.

Secreto 3. Escribe textos que se puedan traducir bien

Ahora que ya sabes cómo hacer que los textos de tu aplicación sean traducibles, es el momento de hablar sobre los textos en si. En el mundillo de las traducciones no todo vale. Por ejemplo, más de una vez me he encontrado con cadenas de texto de la siguiente forma:

que, como puedes ver, no se puede traducir bien:

• El usuario ha sido borrado. ? Una traducción impecable.
• El entrada ha sido borrado. ? ¿»El entrada»? ¿No tendría que ser «la entrada»? ¿Y es «borrado» o «borrada»?

¿Qué está pasando aquí? Básicamente, estamos traduciendo fragmentos de una frase («The», «user», «post», «has been deleted») de forma individual para pegarlos a continuación según nos convenga en inglés (que para eso tenemos el texto en inglés: primero viene el artículo The, luego le pegamos un nombre (que puede ser user o post) y acabamos con el sintagma verbal (has been deleted). Y encima súmale que tenemos que poner los espacios para que no se peguen las palabras… ¡Un desastre!

Otro ejemplo horrible de traducciones es el que incluye frases en singular y en plural. Hay mil y un ejemplos de cómo hacerlo mal. Por ejemplo, un if y un else grande para separar el singular del plural:

o un if (a veces incluso en su forma «breve» en línea) al final para añadir una «s» cuando haga falta:

Evidentemente, todo esto consigue el resultado esperado en inglés, pero a la que intentamos traducirlo es todo un despropósito. ¿Cómo arreglamos este desbarajuste? Con estos tres sencillas reglas:

Nelio A/B Testing

Pruebas A/B nativas en WordPress

Usa tu editor de páginas favorito en WordPress para crear variaciones y lanza pruebas A/B con solo un par de clics. No se necesita saber nada de programación para que funcione.

Más info

1. Escribe frases enteras

En lugar de concatenar fragmentos de una frase, escribe la frase entera y deja que sea el traductor el que la traduzca como un todo. Esto añade un poquito de trabajo al desarrollador y al traductor (hay más texto por escribir), pero el resultado final de cara al usuario es magnífico. El ejemplo anterior quedaría de esta forma:

y sus traducciones así:

• El usuario ha sido borrado. ??
• La entrada ha sido borrada. ??

Impecable, ¿verdad?

2. Si tu frase tiene partes variables, usa placeholders

Hay veces en las que una parte de la cadena de texto es variable. Por ejemplo, un texto de bienvenida que incluya el nombre del usuario, como puede ser «Hola, David» u «Hola, María». Es evidente que no puedes generar todos los mensajes de bienvenida con todos los nombres posibles, así que quizás ahora sí puedas hacer esto:

¡Mal! No, no puedes hacerlo. El orden de las oraciones no es el mismo en todos los idiomas, con lo que no podemos forzar que el nombre aparezca al final de la cadena de texto (recuerda la primera regla). En estos casos, tienes que usar los placeholder de la función printf. Es decir, tienes que añadir una pequeña marca en la cadena de texto que indique dónde tiene que ponerse el pedazo de texto variable. El ejemplo anterior quedaría de la siguiente forma:

y su traducción al español sería así:

• Hola, %s

De esta forma, la función printf recibirá la cadena de texto traducida y reemplazará el placeholder %s por el nombre del usuario que toque.

3. Los plurales tienen sus propias funciones

En español tenemos una forma singular, que se usa cuando hay «uno» de «algo» («una entrada», «un usuario», «una página») y una forma plural que usamos en todos los demás casos («cero entradas», «dos usuarios», «500 páginas»). Y lo mismo pasa en inglés, así que siguiendo las reglas 1 y 2 que acabamos de ver, la forma de hacerlo tendría que ser así:

¿no? Pues, por desgracia, no. En otros idiomas pueden existir múltiples versiones del plural, y cada una de ellas se usa con un conjunto determinado de números. Por ejemplo, en polaco, la palabra plik (fichero) se usa de la siguiente forma:

• 1 plik
• 2, 3, 4 pliki
• 5-21 plików
• 22-24 pliki
• 25-31 plików
• etc.

Así que, como ves, no es posible separar entre «1 elemento» y «n elementos»; necesitamos algo más potente. Por suerte, la librería gettext también nos soluciona la papeleta en esta situación:

Usando la función _n() puedes especificar cuál es la frase en singular y cuál es la frase en plural (recuerda que en inglés sí que solo hay un singular y un plural). Cuando haya que traducir esta cadena de texto a un cierto idioma, el traductor deberá especificar tantas frases como su idioma requiera.

Finalmente, un comentario. Fíjate que en este ejemplo aparece dos veces la variable $count. El primer $count es un parámetro de la función _n() y sirve para que gettext sepa qué frase de entre las posibles traducciones que hay tiene que cargar. Una vez ha seleccionado la frase adecuada, ésta se pasa como parámetro a la función printf y, de nuevo, se vuelve a usar la variable $count (esta vez como parámetro de printf) para reemplazar el placeholder %s de la traducción por el valor adecuado.

Secreto 4. Usa los contextos…

Uno de los problemas de los idiomas (y especialmente del inglés) es que una misma palabra puede tener múltiples significados. Por ejemplo, la palabra «comment» puede corresponderse al verbo «comentar» o puede ser el sustantivo «comentario», así que… ¿cómo se traduce? ¿Qué tiene que hacer el traductor con esta palabra? Este tipo de palabras dependen del contexto en el que estamos: a veces queremos que se traduzca como un nombre y a veces queremos que se traduzca como un verbo:

Según mi experiencia, existen tres tipos de contexto en los que un texto puede aparecer (y estos son los nombres que suelo usar para indicar el contexto concreto):

1. command. El usuario ordena al ordenador/plugin/aplicación que haga alguna tarea. Ejemplos de ello son: «Eliminar entrada», «Crear usuario», etc. En todos estos casos, es el usuario quien se dirige a la máquina y le indica qué quiere hacer.
2. user. Hay veces en que los papeles están invertidos y es el ordenador/plugin/aplicación quien se dirige directamente al usuario, pidiéndole explícitamente que realice alguna acción. Algunos ejemplos pueden ser: «Introduce una dirección de correo válida» o «Inténtalo de nuevo más tarde».
3. text. Si no es ninguno de los casos anteriores, entonces son simplemente mensajes de texto que informan o notifican de lo que está pasando. Por ejemplo: «Se ha producido un error al iniciar sesión», «Los pagos se realizan a través de una plataforma segura», «Akismet ha eliminado 27 mensajes».

Te recomiendo usar los contextos en todas las cadenas de texto de tu plugin/tema. En mi opinión, es una buena práctica indicar de forma explícita cuál es la intención de tu texto con uno de los tres contextos anteriores, y hacerlo te permitirá asegurar que las cadenas siempre se traducen correctamente.

Habrá casos (palabras polisémicas, principalmente) en los que necesitarás usar un contexto diferente para indicar cuál de los posibles significados de la palabra es el que te interesa. Si ese es tu caso, adapta el contexto para evitar ambigüedades.

Secreto 5. …y ayuda a los traductores

Como te decía, el contexto es una buena forma para ayudar a los traductores a entender cuál es la intención de una cadena de texto para que, así, puedan traducirla mejor. No obstante, hay veces en las que una cadena de texto puede resultar confusa, difícil de comprender. En estos casos, lo mejor que puedes hacer es añadir una pequeña descripción a la cadena que les ayude a entender qué está pasando.

Por ejemplo, una cadena como la siguiente:

no tiene ningún sentido aparente. Sin embargo, si añadimos la descripción usando un comentario con la palabra translators:, nos queda lo siguiente:

Con esta información, ahora ya sabemos que la cadena anterior representa una fecha usando la notación de PHP para formatear fechas.

Secreto 6. Sigue las reglas

Finalmente, si decides traducir tu propio plugin a idiomas que domines (por ejemplo, al español) o si quieres traducir el trabajo de otra gente, que sepas que lo puedes hacer muy fácilmente desde la página oficial de WordPress. Simplemente apúntate al equipo de traducciones que te interese (hay uno por idioma) y empieza a traducir…

…pero antes de hacerlo, pásate por los canales de Slack y habla con la comunidad. Muchos equipos de traducción tienen reglas y guías sobre cómo hay que traducir ciertos términos o expresiones. En estas guías se resuelven dudas como, por ejemplo:

• ¿Cómo traducimos «You»? ¿»Tú»? ¿»Vos»? ¿»Usted»?
• ¿Cuál es la traducción de «Settings»? ¿»Ajustes»? ¿»Configuración»?
• Las órdenes como «Save» o «Comment», ¿se ponen en infinitivo («Guardar» y «Comentar») o en imperativo («Guarda» y «Comenta»)?

Recuerda que las traducciones están hechas por un montón de voluntarios de la comunidad; si queremos que el resultado final sea coherente, necesitamos adherirnos a unas reglas comunes para evitar que WordPress sea un Frankenstein de traducciones sin sentido, cada una de su padre y de su madre.

¿Estás pensando en traducir tu plugin o tema? ¿Has empezado ya? ¿Quieres contribuir al proyecto y tienes dudas? ¡Pues cuéntanoslo en los comentarios, hombre!

Imagen destacada de Mark Rasmuson.