Cómo traducir archivos PO sin romper tu aplicación

Los archivos PO parecen simples archivos de texto hasta que una traducción de %s, una forma plural faltante o una edición de msgid rompe tu aplicación. Utiliza este flujo de trabajo para traducir las cadenas visibles para el usuario sin alterar la estructura de gettext.

No pegues todo el archivo en un traductor de texto normal. Un archivo PO es casi como código fuente: las palabras son traducibles, pero la estructura del archivo, los marcadores de posición, los comentarios y los índices de plural deben permanecer intactos.

Método 1: Utiliza un Traductor de Archivos PO

Elige esta opción si quieres un primer borrador rápido y seguro, y no deseas editar los pares msgid / msgstr manualmente.

1. Haz una copia de seguridad del archivo .po original. Guarda una copia limpia en tu repositorio antes de enviar cualquier cosa a un traductor. Si el archivo traducido falla, necesitas una versión comprobada para comparar.

2. Abre un traductor compatible con archivos PO. Utiliza una herramienta diseñada para archivos gettext, como OpenL PO Translator, una herramienta de traducción de documentos de pago por uso. Una herramienta compatible con PO debe traducir las cadenas objetivo manteniendo intactas las cadenas fuente, los comentarios, los marcadores de posición y la estructura del archivo. Si aún estás eligiendo herramientas, compara opciones en nuestra guía de los mejores traductores PO.

3. Sube el archivo .po. Utiliza el archivo de idioma que contiene las entradas msgid y msgstr. Si solo tienes una plantilla .pot, primero crea un archivo .po en el idioma objetivo a partir de ella y luego sube el archivo .po.

4. Elige el idioma de origen y destino. Haz coincidir el idioma de origen con el texto dentro de msgid, no con el idioma de tu interfaz de administración. Por ejemplo, si el archivo contiene cadenas msgid en inglés y necesitas la salida en español, elige inglés a español.

5. Descarga el archivo traducido. Guárdalo siguiendo la convención de nombres de locales que espera tu framework. Los plugins de WordPress suelen usar un patrón de dominio de texto más local, mientras que Django normalmente almacena los archivos bajo locale/<language>/LC_MESSAGES/.

6. Revisa primero las cadenas de riesgo. Busca en el archivo traducido los caracteres %, {, }, <, >, msgid_plural, msgctxt y #, fuzzy. Estas son las entradas que más probablemente afectarán el comportamiento en tiempo de ejecución.

7. Prueba el archivo traducido en tu aplicación. Carga el idioma localmente y navega por las pantallas que utilizan las cadenas traducidas. Un archivo PO no está terminado cuando se traduce; está terminado cuando la aplicación sigue mostrando todo correctamente.

Método 2: Traducir archivos PO en Poedit

Elige esta opción si necesitas revisión humana, compatibilidad con WordPress o un flujo de trabajo cuidadoso entrada por entrada.

1. Abre el archivo en Poedit. Poedit es un editor de traducción dedicado para archivos PO y otros formatos de localización; el editor básico es gratuito, con funciones Pro de pago para flujos de trabajo más avanzados. Para WordPress, el manual oficial de Polyglots explica que Poedit puede crear archivos .po y .mo a partir de un archivo POT, y soporta formas plurales y UTF-8.

2. Actualiza desde la plantilla POT si el origen cambió. Si los desarrolladores modificaron el texto de la aplicación, actualiza el archivo .po desde el último .pot antes de traducir. Esto mantiene visibles las cadenas nuevas, eliminadas y difusas, en lugar de enviar silenciosamente textos de interfaz obsoletos.

3. Traduce solo el campo msgstr. El msgid es la cadena fuente que tu aplicación utiliza para buscar la traducción. En los flujos de trabajo normales de gettext, los traductores deben editar msgstr, no msgid.

4. Mantén los marcadores de posición exactamente intactos. No traduzcas ni cambies el espacio de variables como %s, %d, %1$s, {name}, %(count)s, :name o etiquetas HTML. Si el orden de las palabras debe cambiar, mueve el marcador de posición como una unidad.

5. Gestiona las formas plurales como traducciones separadas. Una entrada plural puede contener msgid, msgid_plural y varios valores msgstr[n]. Completa cada espacio plural requerido por el idioma de destino en lugar de copiar la misma frase en todos.

6. Guarda y compila el archivo .mo si tu aplicación lo necesita. Algunos entornos leen los archivos .po directamente durante el desarrollo, pero WordPress y muchas configuraciones de gettext utilizan archivos .mo compilados en tiempo de ejecución. Poedit puede compilar el archivo .mo al guardar; Django puede compilar los mensajes con django-admin compilemessages.

7. Resuelve las advertencias antes de subir el archivo. En Poedit, los iconos de advertencia suelen indicar marcadores de posición rotos, variables faltantes o errores en las formas plurales. Corrige estos problemas antes de importar la traducción en WordPress, Django, Drupal o tu rama de lanzamiento.

Método 3: Usa una plataforma de localización

Elige esta opción cuando varios traductores, revisores o responsables de lanzamiento necesitan trabajar sobre los mismos archivos PO.

1. Importa el archivo PO en una plataforma que soporte gettext. Weblate y plataformas similares de localización admiten flujos de trabajo con archivos PO. Las plataformas de localización para equipos suelen ser productos de pago, aunque Weblate también ofrece una opción de código abierto para autoalojamiento. El manejo de comentarios, encabezados, cadenas difusas y marcadores de posición varía, así que revisa la configuración de formato antes de subir archivos de producción.

2. Activa las comprobaciones de marcadores de posición y etiquetas. Habilita reglas de control de calidad para marcadores de posición estilo printf, variables nombradas, etiquetas HTML/XML y formas plurales. Estas comprobaciones detectan errores que los correctores ortográficos normales no pueden ver.

3. Mantén visibles los comentarios de los desarrolladores. Los comentarios en los archivos PO pueden aportar contexto como referencias de origen, notas extraídas de los desarrolladores, banderas y cadenas fuente anteriores. Los traductores necesitan esas notas cuando una etiqueta corta de la interfaz como “Open” puede ser un verbo, adjetivo o comando de menú.

4. Usa memoria de traducción con revisión. La memoria de traducción es útil para cadenas repetidas en la interfaz, pero puede copiar una traducción antigua en un nuevo contexto. Revisa las cadenas reutilizadas cuando cambien msgctxt, las referencias de origen o el entorno de la interfaz.

5. Exporta los archivos PO y realiza comprobaciones locales. No confíes ciegamente en la exportación. Vuelve a integrar el archivo traducido en la aplicación, compílalo si es necesario y prueba las pantallas antes de hacer el merge.

Reglas de archivos PO que nunca debes romper

Elemento PO	¿Traducirlo?	Ejemplo seguro	Por qué es importante
msgid	No	msgid "Save changes"	La aplicación utiliza esta cadena fuente como clave de búsqueda en muchos flujos de trabajo de gettext.
msgstr	Sí	msgstr "Guardar cambios"	Este es el texto en el idioma de destino que ven los usuarios.
msgctxt	No	msgctxt "button"	El contexto ayuda a diferenciar cadenas fuente idénticas.
%s, %d, %1$s	No	Hello, %s -> Hola, %s	El código en tiempo de ejecución reemplaza estos marcadores de posición con valores reales.
{name}, %(count)s, :name	No	Welcome, {name}	Las variables nombradas deben coincidir con el código de la aplicación.
Etiquetas HTML	Normalmente no	<strong>Warning</strong>	Se traduce el texto, no la sintaxis de la etiqueta.
msgid_plural	No	msgid_plural "%d files"	El plural fuente pertenece a la ruta de código original.
msgstr[0], msgstr[1]	Sí, con cuidado	msgstr[0] "%d file"	Cada idioma tiene sus propias reglas de pluralización.
#, fuzzy	Revisar primero	#, fuzzy	”Fuzzy” indica que la traducción puede estar desactualizada o sin confirmar.
#. comentarios de desarrollador	Normalmente no	#. Button label	Estas notas ayudan a los traductores a entender el contexto.

Ejemplo rápido: Traducción PO segura vs. defectuosa

Aquí tienes una entrada normal de gettext:

#. %s es el nombre visible del usuario.
#, c-format
msgid "Welcome back, %s"
msgstr ""

Una traducción segura al español mantiene %s sin cambios:

#. %s es el nombre visible del usuario.
#, c-format
msgid "Welcome back, %s"
msgstr "Bienvenido de nuevo, %s"

Una traducción defectuosa modifica el marcador de posición:

msgid "Welcome back, %s"
msgstr "Bienvenido de nuevo, % s"

Ese pequeño espacio puede ser crucial. GNU msgfmt --check-format está diseñado para detectar errores de formato como marcadores de posición % incorrectos, y Poedit también advierte sobre problemas comunes con los marcadores de posición. Para una lista más amplia de cadenas que deben permanecer intactas, consulta nuestra guía sobre qué no traducir.

Cómo revisar un archivo PO traducido

1. Ejecuta la validación de gettext si tienes gettext instalado.

msgfmt --check --check-format -o /tmp/messages.mo path/to/messages.po

Esto verifica la sintaxis, los encabezados y las cadenas de formato, y luego escribe un catálogo compilado temporal si el archivo es válido.

2. Compila el archivo según lo que espera tu framework.

django-admin compilemessages

Para proyectos Django, compilemessages compila los archivos .po creados por makemessages en archivos .mo para el soporte de gettext.

3. Busca traducciones vacías.

grep -n 'msgstr ""' path/to/messages.po

Los campos msgstr vacíos pueden ser intencionales para entradas no traducidas, pero no deberían sorprenderte durante el lanzamiento.

4. Busca cadenas marcadas como fuzzy.

grep -n '#, fuzzy' path/to/messages.po

Las cadenas fuzzy deben ser revisadas por una persona antes del lanzamiento. Por defecto, msgfmt no utiliza traducciones fuzzy a menos que compiles con --use-fuzzy, por lo que una entrada fuzzy puede comportarse como una cadena no traducida en el catálogo final.

5. Prueba la interfaz real. Abre las pantallas que contienen formularios, recuentos de plurales, mensajes de error, menús de cuenta y flujos de pago. La validación de PO detecta problemas de archivo; solo las pruebas en la interfaz detectan frases incómodas, desbordamientos y falta de contexto.

¿Qué método deberías usar?

Situación	Mejor método	Por qué
Necesitas un primer borrador rápido para un archivo PO	Traductor de archivos PO	Camino más rápido con preservación de la estructura
Mantienes un plugin o tema de WordPress	Poedit	Flujo de trabajo familiar de WordPress con compilación .mo
Mantienes una aplicación Django	Traductor PO o Poedit, luego compilemessages	La traducción puede ser rápida, pero aún se requiere la compilación del framework
Tienes muchos idiomas y revisores	Plataforma de localización	Mejor asignación, historial, control de calidad y revisiones
Estás traduciendo cadenas para desarrolladores	Revisión humana después de traducción automática	Los términos de código, los marcadores de posición y el contexto son más importantes
También estás localizando archivos JSON o i18n de frontend	Usa un flujo de trabajo específico para el formato	Las reglas de PO no siempre aplican a JSON, YAML o mensajes ICU

Si tu proyecto mezcla archivos PO de gettext con archivos de locales JSON, traduce cada formato con una herramienta que entienda su estructura. Los archivos PO giran en torno a msgid y msgstr; la localización en JSON se basa en claves y valores. Para ese flujo de trabajo, consulta nuestra guía sobre los mejores traductores de JSON en 2026.

Preguntas frecuentes

¿Puedo traducir archivos PO con Google Translate?

Puedes copiar valores individuales de msgstr en un traductor general, pero subir o pegar todo el archivo PO en un traductor de texto plano es arriesgado. Los traductores generales pueden alterar msgid, comentarios, el escape de comillas, índices de plural o marcadores de posición. Usa mejor un traductor compatible con PO, Poedit o una plataforma de localización.

¿Cuál es la diferencia entre .po, .pot y .mo?

.pot es la plantilla extraída del código fuente. Normalmente contiene cadenas originales pero no traducciones completas. .po es el archivo editable de traducción para un idioma objetivo. .mo es el catálogo binario compilado que muchas aplicaciones basadas en gettext cargan en tiempo de ejecución.

¿Debo traducir msgid?

No, no en el flujo de trabajo normal. Traduce msgstr. El manual de GNU gettext describe msgid como la cadena original sin traducir y msgstr como la traducción; las cadenas msgid son generadas y gestionadas por las herramientas de gettext.

¿Cómo puedo comprobar si un archivo PO es válido?

Ejecuta msgfmt --check --check-format si tienes gettext disponible, abre el archivo en Poedit o utiliza las comprobaciones de calidad de tu plataforma de localización. Luego compila y prueba el archivo dentro de la aplicación. La validación es necesaria, pero no sustituye las pruebas de interfaz de usuario.

¿Qué ocurre si rompo un marcador de posición?

En el mejor de los casos, la aplicación mostrará una cadena extraña. En el peor de los casos, el formateador en tiempo de ejecución lanzará un error porque la cadena traducida ya no coincide con las variables que el código pasa. Los marcadores de posición deben moverse solo como tokens completos, nunca traducirse ni editarse parcialmente.

¿Puede OpenL traducir archivos PO?

Sí. OpenL PO Translator está diseñado para archivos .po de gettext y afirma que mantiene intactos los marcadores de posición y variables mientras traduce a más de 100 idiomas. Utiliza un flujo de trabajo de traducción de documentos de pago por uso, así que úsalo para un primer borrador rápido cuando preservar la estructura PO sea más importante que hacerlo todo manualmente. Si solo tienes una plantilla .pot, crea un archivo .po en el idioma objetivo antes de usar OpenL.

Fuentes

• Manual de GNU gettext: Archivos PO — Explicación oficial de gettext sobre el formato de archivos PO.
• Manual de GNU gettext: Entradas de archivos PO — Fuente para msgid, msgstr, comentarios, banderas y la estructura de las entradas.
• Manual de GNU gettext: Entradas con formas plurales — Fuente sobre la estructura de entradas con formas plurales.
• Manual de GNU gettext: Invocación de msgfmt — Fuente para msgfmt --check y la validación de cadenas de formato.
• OpenL PO Translator — Página de producto de OpenL para traducir archivos .po preservando los marcadores de posición y variables.
• Poedit — Sitio oficial de Poedit para el editor de traducción de archivos PO y la oferta Pro.
• WordPress Polyglots Handbook: Poedit — Guía de WordPress sobre el uso de Poedit, archivos POT, archivos PO, compilación MO y advertencias sobre marcadores de posición.
• Documentación de Django: Traducción — Flujo de trabajo de Django para archivos de mensajes y traducción.
• Documentación de Django: compilemessages — Referencia de comandos de Django para compilar archivos .po en archivos .mo.
• Documentación de Drupal: Archivos PO y POT — Explicación de Drupal sobre archivos .po, .pot, contexto, formas plurales, comentarios y variables.
• Documentación de Weblate: GNU gettext PO — Notas de la plataforma de localización sobre cabeceras PO, cadenas fuente previas, cadenas obsoletas y archivos MO generados.