Cómo crear un archivo .pot para un tema o plugin
Acabas de terminar un plugin de WordPress que quieres compartir con el mundo. El código funciona, las características son sólidas y alguien en Alemania te envía un correo electrónico preguntando cómo traducirlo al alemán. Les indicas la carpeta languages y te das cuenta de que no hay nada allí. Ni plantilla, ni cadenas, ni forma de que un traductor sepa qué necesita traducción. Tu plugin es técnicamente "listo para traducir" solo de nombre.
Todo proyecto de WordPress traducible comienza con un archivo: la plantilla .pot. Antes de que nadie pueda producir una versión en alemán, francés o japonés, debes crear un archivo POT que liste cada cadena visible para el usuario en tu código. Si omites este paso, los traductores se verán obligados a leer tu código fuente línea por línea, adivinando qué cadenas están destinadas a ser visibles.
Esta guía te lleva a través de las dos mitades del trabajo: preparar tu código fuente para que las cadenas sean detectables, y luego generar el .pot con tres herramientas diferentes. Utilizaremos WP-CLI, Poedit y el enfoque heredado makepot/grunt, con comandos reales que puedes copiar. Al final, tendrás una plantilla limpia lista para entregar a cualquier traductor.
Paso uno: Marca tus cadenas como traducibles
Antes de poder crear un archivo POT, cada cadena que un usuario pueda ver debe estar envuelta en una función Gettext. Un escáner solo puede extraer las cadenas que reconoce, y las reconoce por estas llamadas a funciones; los literales de cadena simples le son invisibles.
WordPress proporciona una familia de funciones de localización, cada una para un contexto ligeramente diferente:
// Return a translated string
$label = __( 'Add to Cart', 'my-plugin' );
// Echo a translated string directly
_e( 'Your cart is empty', 'my-plugin' );
// Translate with context to disambiguate identical words
$verb = _x( 'Post', 'verb: to publish', 'my-plugin' );
// Translate AND escape for safe HTML output
echo esc_html__( 'Welcome back', 'my-plugin' );
El segundo argumento en cada llamada — 'my-plugin' — es el dominio de texto. Agrupa todas las cadenas de un plugin o tema bajo un mismo espacio de nombres para que WordPress sepa qué archivo .mo cargar para ellas. Cada cadena traducible en tu proyecto debe compartir exactamente el mismo dominio de texto, o algunas cadenas nunca serán traducidas.
Usa _x() siempre que una palabra sea ambigua. El "Post" en inglés puede ser un sustantivo o un verbo, y muchos idiomas los traducen de manera diferente. Las cadenas de contexto permiten a los traductores distinguirlos. Y recurre a las variantes esc_html__() y esc_attr__() siempre que la cadena traducida se imprima en HTML, para que permanezcas seguro y localizado al mismo tiempo.
Hay algunos hábitos que mantienen tus cadenas extraíbles. Pasa siempre un literal de cadena simple como primer argumento — nunca una variable o una concatenación como __( 'Hello ' . $name, 'my-plugin' ), porque el escáner lee el texto fuente estáticamente y no puede resolver valores en tiempo de ejecución. Para oraciones con un número, usa _n() para que las formas plurales se capturen correctamente, y para oraciones con un valor dinámico, usa sprintf() alrededor de un marcador de posición como %s en lugar de unir cadenas. La coherencia aquí es lo que hace que el siguiente paso —generar la plantilla— produzca un resultado completo y utilizable.
Paso dos: Declara el dominio de texto en tu cabecera
WordPress necesita dos campos en la cabecera para saber dónde residen tus traducciones: el Dominio de Texto y la Ruta del Dominio. Configúralos en el archivo principal de tu plugin o en el style.css de tu tema, y WordPress cargará automáticamente el .mo correcto en tiempo de ejecución.
<?php
/**
* Plugin Name: My Plugin
* Description: A perfectly localized WordPress plugin.
* Version: 1.0.0
* Requires at least: 6.4
* Text Domain: my-plugin
* Domain Path: /languages
*/
El Dominio de Texto debe coincidir con la cadena que pasaste a cada llamada __() y _e() — my-plugin aquí. La Ruta del Dominio le dice a WordPress qué subcarpeta contiene los archivos de traducción, relativa a la raíz del plugin o tema. La convención es /languages, y ahí es exactamente donde debería residir tu .pot generado.
Con las cadenas envueltas y la cabecera declarada, tu código está listo para ser escaneado. Una visión más amplia de cómo preparar un proyecto para la traducción —incluyendo temas que no son tuyos— se cubre en cómo localizar cualquier tema de WordPress aunque no seas desarrollador.
¿Cómo se genera el archivo .pot? Tres métodos
Generas un .pot ejecutando un escáner sobre tu código fuente que encuentra cada llamada Gettext y escribe las cadenas en una plantilla. Aquí tienes tres formas fiables de hacerlo, desde el método moderno predeterminado hasta el enfoque heredado.
Método 1: WP-CLI (Recomendado)
La forma oficial y moderna de crear un archivo POT es WP-CLI con el comando i18n. Se incluye como parte de las herramientas del núcleo de WordPress, entiende cadenas PHP y JavaScript, y produce una plantilla que cumple con los estándares en una sola línea.
# Run from your plugin or theme root directory
wp i18n make-pot . languages/my-plugin.pot
# Add a text domain explicitly if auto-detection misses it
wp i18n make-pot . languages/my-plugin.pot --domain=my-plugin
# Scan only specific paths and exclude vendor folders
wp i18n make-pot . languages/my-plugin.pot --exclude=vendor,node_modules
El primer argumento es el directorio fuente (. para la carpeta actual), y el segundo es la ruta de salida. WP-CLI recorre tus archivos, extrae cada cadena envuelta, registra el archivo fuente y el número de línea como un comentario, y escribe el .pot. Es rápido, programable y la elección correcta para cualquier proyecto serio.
La plantilla generada incluye metadatos útiles que puedes ajustar con banderas adicionales. Pasa --headers para establecer el nombre del proyecto, la versión y la dirección de contacto de los traductores, de modo que el bloque de cabecera del .pot se rellene correctamente en lugar de dejarse como marcadores de posición. WP-CLI también extrae cadenas de JavaScript de las llamadas a wp_set_script_translations() automáticamente, lo cual es importante para los temas de bloques modernos y los plugins de Gutenberg donde la mitad del texto visible para el usuario reside en JavaScript en lugar de PHP. Un solo comando cubre ambos mundos.
Método 2: Poedit (Gráfico)
Si prefieres una aplicación de escritorio, Poedit puede escanear tu código fuente y generar la plantilla a través de su interfaz. Abre Poedit, elige crear una nueva traducción desde POT o escanear fuentes directamente, apúntalo a la carpeta de tu proyecto y configura las palabras clave de origen (__, _e, _x, esc_html__) bajo las propiedades del catálogo.
Las funciones de escaneo de código fuente y generación de .pot de Poedit están disponibles en su edición Pro, pero el flujo de trabajo es amigable para los desarrolladores que prefieren hacer clic en lugar de escribir comandos. También es un editor sólido para la fase de traducción que le sigue. Poedit y otras opciones de escritorio se comparan en las 5 mejores herramientas gratuitas para editar y traducir archivos PO en Mac y Windows.
Método 3: makepot / grunt (Heredado)
Antes de WP-CLI, la herramienta estándar era el script makepot.php del repositorio i18n-tools de WordPress, a menudo integrado en una tarea de construcción de Grunt con grunt-wp-i18n. Todavía lo encontrarás en plugins y temas más antiguos.
# Legacy makepot.php invocation
php makepot.php wp-plugin /path/to/my-plugin languages/my-plugin.pot
Funciona, pero no tiene mantenimiento en comparación con WP-CLI y es más lento de configurar. Úsalo solo cuando estés manteniendo un proyecto heredado que ya depende de él; para cualquier cosa nueva, prefiere wp i18n make-pot.
Mantén la plantilla actualizada a medida que cambia tu código
Un .pot es una instantánea de tus cadenas en un momento dado. Cada vez que añades una característica, cambias una etiqueta o corriges un error tipográfico en una cadena visible, la plantilla se vuelve obsoleta y los traductores se pierden la nueva redacción.
Haz de la regeneración parte de tu rutina de lanzamiento. Vuelve a ejecutar wp i18n make-pot antes de cada actualización de versión, luego fusiona la plantilla actualizada con las traducciones existentes usando wp i18n update-po o msgmerge para que los traductores conserven su trabajo terminado y solo vean las nuevas lagunas. Trata el .pot como un artefacto de compilación que regeneras, no como un archivo que editas manualmente.
Una plantilla obsoleta causa un fallo sutil y frustrante: aparecen cadenas nuevas en inglés incluso en un sitio "completamente traducido", porque nunca estuvieron en el .pot con el que trabajó el traductor. Detectar esto es tan simple como integrar la regeneración en tu proceso de compilación, para que la plantilla nunca se quede atrás del código. Algunos equipos añaden una comprobación de CI que falla la compilación si la regeneración del .pot produce una diferencia, garantizando que la plantilla comprometida siempre coincida con el código fuente actual.
Una vez que los traductores devuelven los archivos .po terminados, estos aún necesitan ser compilados al binario .mo que WordPress realmente carga — y si prefieres saltarte todo el ciclo de descarga, traducción y recompilación, una herramienta en la nube puede manejarlo de principio a fin. SimplePoTranslate acepta tu .pot directamente, lo traduce con IA Contextual que entiende lo que significa cada cadena en tu interfaz, y devuelve un único ZIP con los archivos .po, .mo y más ya construidos y nombrados. Su Bloqueo de Sintaxis congela marcadores de posición como %s y %1$s para que tus variables nunca se rompan en la traducción.
En resumen
Para crear un archivo POT de la manera correcta, primero haz que tu código sea detectable — envuelve cada cadena visible en __(), _e(), _x() o una variante de escape, todas compartiendo un único dominio de texto, y declara ese dominio más la Ruta del Dominio en tu cabecera. Luego, genera la plantilla con WP-CLI para proyectos nuevos, Poedit si prefieres una GUI, o makepot solo cuando mantengas código heredado.
Genera pronto, regenera a menudo y nunca dejes que tu plantilla se quede atrás de tu código. Un .pot actualizado es la diferencia entre un plugin que está genuinamente listo para el mundo y uno que solo lo afirma.
¿Listo para convertir tu plantilla
.poten traducciones terminadas sin el proceso manual de compilación? Prueba SimplePoTranslate gratis — no se requiere tarjeta de crédito. Sube tu plantilla en el nivel gratuito y descarga archivos de traducción listos para usar en minutos.