Contents
Introducción
Este tutorial explica, paso a paso y con todo lujo de detalles, cómo generar archivos .pot (Portable Object Template) para temas y plugins de WordPress usando WP-CLI y su comando i18n. Cubriremos la instalación del comando, ejemplos prácticos para plugins y themes, opciones útiles, buenas prácticas y cómo integrarlo en tu flujo de trabajo de desarrollo y liberación.
¿Por qué generar un .pot?
El archivo .pot reúne todas las cadenas traducibles de un proyecto para que traductores creen archivos .po/.mo en distintos idiomas. Mantener un .pot actualizado facilita que la comunidad traduzca tu plugin o tema y es un requisito casi obligatorio para publicar traducciones consistentes.
Requisitos previos
- Acceso a la línea de comandos (SSH o terminal local) en la raíz del proyecto o en la carpeta del plugin/tema.
- WP-CLI instalado. Si no lo tienes, instálalo desde https://wp-cli.org/.
- El comando i18n para WP-CLI (package wp-cli/i18n-command) instalado o disponible en tu instalación de WP-CLI.
- PHP (la versión que utilices para tu WordPress) y acceso a los archivos del proyecto.
- Buenas prácticas en el código: usar las funciones de internacionalización de WordPress (__(), _e(), _n(), _x(), esc_html__(), etc.) y declarar el Text Domain en el encabezado del plugin/tema.
Instalación del comando i18n para WP-CLI
Si WP-CLI no incluye ya el comando i18n, puedes instalar el paquete oficial con:
wp package install wp-cli/i18n-command
Verifica que el comando está disponible:
wp help i18n
Preparar el proyecto
Asegúrate de lo siguiente antes de generar el .pot:
- El Text Domain en el encabezado del plugin/tema coincide con el slug y con las llamadas a las funciones de internacionalización.
- Existe una carpeta /languages (o la ruta que prefieras) donde colocarás el .pot y luego los .po/.mo.
Ejemplo: encabezado de plugin correcto
Generar un .pot: uso básico
La forma básica del comando es:
wp i18n make-pot ltpath-al-codigogt ltruta-de-salida/archivo.potgt
Ejemplos prácticos:
Plugin
cd wp-content/plugins/mi-plugin wp i18n make-pot . languages/mi-plugin.pot --slug=mi-plugin
Tema
cd wp-content/themes/mi-tema wp i18n make-pot . languages/mi-tema.pot --slug=mi-tema
Opciones útiles y explicación
- –slug: especifica el slug del proyecto (suele coincidir con el text-domain). Ayuda a nombrar y agrupar cadenas.
- –exclude: rutas o patrones a excluir (por ejemplo vendor, node_modules). Se pueden separar por comas.
- –skip-js: omite el análisis de archivos JavaScript (si no quieres o no necesitas extraer cadenas desde JS).
- –merge: fusiona un .pot existente con el resultado para preservar comentarios o entradas previas. Útil para no perder el historial de traducciones cuando agregas nuevas cadenas.
- –help: muestra todas las opciones disponibles para tu versión del comando.
Ejemplo con exclusiones y merge
wp i18n make-pot . languages/mi-plugin.pot --slug=mi-plugin --exclude=vendor,node_modules --merge=languages/mi-plugin.pot
Qué cadenas se extraen
El extractor identifica las cadenas usadas con las funciones de internacionalización de WordPress, por ejemplo:
- __(), _e(), _x(), _ex()
- _n(), _nx(), _n_noop()
- esc_html__(), esc_html_e(), esc_attr__(), etc.
Para JavaScript, si usas wp.i18n.__() y funciones relacionadas, el extractor moderno de WP-CLI también puede reconocer esas cadenas si la versión del paquete lo soporta. Si tu JavaScript usa otra librería o patrón, puede no extraerlas automáticamente.
Ejemplos de código que se detectan (PHP)
Ejemplo de JavaScript compatible (WordPress i18n)
( function( wp ) {
const { __ } = wp.i18n
console.log( __( Texto en JS, mi-plugin ) )
} )( window.wp )
Buenas prácticas y recomendaciones
- Text Domain coherente: usa siempre el mismo text domain (idealmente el slug del plugin/tema) y decláralo en el encabezado.
- Carpeta languages: guarda el .pot y los .po/.mo en /languages dentro del plugin/tema o en la ruta declarada.
- Excluye dependencias: evita escanear vendor/ y node_modules/ para acelerar el proceso y evitar ruido.
- Ejecuta antes de cada release: actualiza el .pot cada vez que añadas o cambies cadenas.
- Usa herramientas complementarias: edita y revisa el .pot/.po con Poedit, GlotPress o editores de PO para comprobar contexto y placeholders.
- Comete el .pot al repositorio: así traductores y CI pueden trabajar con la plantilla más reciente.
Integración en flujos de trabajo y CI
Puedes automatizar la generación del .pot en tus scripts de build o en CI (GitHub Actions, GitLab CI, etc.). Un flujo típico:
- En el paso de build, instalar WP-CLI en el runner (o usar una imagen que lo incluya).
- Instalar el package i18n si es necesario.
- Ejecutar wp i18n make-pot con las opciones adecuadas.
- Comprobar cambios y, si hay modificaciones, crear un commit o abrir un PR que actualice /languages/.
Problemas comunes y soluciones
- No detecta cadenas JS: revisa que uses wp.i18n y que la versión del comando i18n que tienes soporte extracción de JS si no, usa –skip-js y procesa JS de otra forma.
- Text domain no encontrado: asegúrate de que el Text Domain en las funciones y en el encabezado coincide exactamente (minúsculas y guiones).
- Permisos de archivos: ejecuta el comando con un usuario que tenga permiso de escritura en la carpeta languages.
- Mucho ruido en el .pot: añade exclusiones con –exclude para omitir dependencias.
Ejemplo completo paso a paso para un plugin
- Confirma el encabezado del plugin con Text Domain y Domain Path.
- Instala el comando i18n si hace falta:
wp package install wp-cli/i18n-command - Posiciónate en la carpeta del plugin y genera el pot:
cd wp-content/plugins/mi-plugin wp i18n make-pot . languages/mi-plugin.pot --slug=mi-plugin --exclude=vendor,node_modules - Verifica el archivo generado en languages/mi-plugin.pot y súbelo al repositorio si procede.
Conclusión
WP-CLI y su comando i18n hacen que la generación de archivos .pot sea rápida, repetible y fácil de integrar en procesos automáticos. Mantener un .pot actualizado mejora la calidad de las traducciones y facilita la colaboración con traductores. Siguiendo las recomendaciones (text domain coherente, exclusiones, automatización en CI) tendrás un flujo sólido para internacionalizar tus plugins y temas en WordPress.
|
|
Acepto donaciones de BAT's mediante el navegador Brave 🙂 |