Índice
Localización API-First: Integra la Traducción en tu Flujo de Trabajo de Desarrollo
Puntos Clave
- La localización API-first reemplaza el intercambio manual de archivos con sincronización automatizada entre tu base de código y el sistema de gestión de traducciones
- Las herramientas CLI y las integraciones CI/CD habilitan flujos de trabajo push/pull que mantienen las traducciones sincronizadas con cada despliegue
- Las notificaciones basadas en webhooks disparan builds cuando se actualizan las traducciones, habilitando la localización continua
- Los enfoques API-first reducen el tiempo de comercialización para nuevos idiomas de semanas a horas
¿Qué es la Localización API-First?
La localización API-first es un enfoque en el que el sistema de gestión de traducciones (TMS) proporciona acceso programático a todos los flujos de trabajo de traducción mediante REST APIs, herramientas CLI y webhooks. En lugar de exportar/importar manualmente archivos de traducción, los desarrolladores integran la sincronización de traducciones directamente en sus pipelines de build y despliegue.
El Flujo de Trabajo Tradicional vs. API-First
Tradicional (Basado en Archivos)
- El desarrollador exporta cadenas fuente a un archivo (JSON, XLIFF, etc.)
- El archivo se sube al TMS o se envía a los traductores por correo electrónico
- Los archivos traducidos se devuelven después de días/semanas
- El desarrollador descarga y coloca los archivos en los directorios correctos
- El desarrollador hace commit y despliega
Problemas: Pasos manuales, divergencia de versiones, conflictos de merge, tiempos de ciclo lentos.
API-First
- El desarrollador sube las nuevas cadenas mediante CLI:
better-i18n push - El TMS notifica a los traductores del nuevo contenido
- Los traductores trabajan en el editor del TMS con contexto completo
- El webhook dispara el CI/CD cuando las traducciones están completas
- El build obtiene las últimas traducciones:
better-i18n pull - El despliegue incluye las traducciones actualizadas automáticamente
Beneficios: Sin manejo manual de archivos, sincronización continua, tiempos de ciclo más rápidos.
Componentes Principales de la Localización API-First
REST API
La API del TMS proporciona endpoints para:
POST /api/keys — Crear nuevas claves de traducción GET /api/translations — Obtener traducciones para un locale PUT /api/translations — Actualizar traducciones GET /api/projects — Listar proyectos y su estado POST /api/upload — Subir archivos fuente GET /api/download — Descargar archivos traducidos
Herramienta CLI
Una herramienta de línea de comandos que encapsula la API para comodidad del desarrollador:
# Subir nuevas cadenas fuente al TMS better-i18n push # Obtener las últimas traducciones better-i18n pull --locale=de,fr,ja # Verificar el estado de las traducciones better-i18n status # Escanear la base de código en busca de cadenas sin traducir better-i18n scan
Webhooks
Notificaciones orientadas a eventos cuando cambian las traducciones:
{
"event": "translations.completed",
"project": "my-app",
"locale": "de",
"completed_keys": 142,
"total_keys": 142
}
Usa webhooks para disparar pipelines CI/CD, notificaciones de Slack o despliegues automatizados.
Integración CI/CD
Integra la sincronización de traducciones en tu pipeline de build:
# Ejemplo de GitHub Actions
- name: Pull translations
run: better-i18n pull --all
env:
BETTER_I18N_TOKEN: ${{ secrets.BETTER_I18N_TOKEN }}
- name: Build
run: npm run build
Beneficios de la Localización API-First
| Beneficio | Impacto |
|---|---|
| Sincronización automatizada | Sin gestión manual de archivos |
| Control de versiones | Las traducciones se rastrean junto al código |
| Entrega continua | Las nuevas traducciones se publican con cada despliegue |
| Experiencia del desarrollador | Flujo de trabajo familiar con CLI/API |
| Menor tiempo de comercialización | Nuevos idiomas en horas, no semanas |
| Menos errores | Sin problemas de formato de archivo ni archivos mal ubicados |
Patrones de Implementación
Patrón 1: Pull en Tiempo de Build
Obtén las traducciones durante el paso de build. Las traducciones se empaquetan en la app en tiempo de build.
Ideal para: Sitios estáticos, páginas pre-renderizadas, aplicaciones móviles.
Patrón 2: Fetch en Tiempo de Ejecución
Obtén las traducciones desde la API en tiempo de ejecución. Permite actualizaciones instantáneas sin necesidad de redespliegue.
Ideal para: SPAs, aplicaciones web dinámicas, contenido en tiempo real.
Patrón 3: Híbrido
Obtén las traducciones en tiempo de build para la carga inicial, y actualízalas en tiempo de ejecución para correcciones urgentes.
Ideal para: Aplicaciones en producción que necesitan tanto rendimiento como flexibilidad.
Preguntas Frecuentes
¿Necesito cambiar mi formato de archivo para usar la localización API-first? No. La mayoría de las plataformas TMS API-first admiten formatos estándar (JSON, XLIFF, YAML, .strings, .xml) y gestionan la conversión de formato automáticamente.
¿Cómo manejo las claves de traducción que se renombran o eliminan?
El comando scan de la CLI detecta las claves no utilizadas. Los endpoints de la API permiten operaciones masivas de claves. La mayoría de las plataformas TMS rastrean el ciclo de vida de las claves y marcan las traducciones huérfanas.
¿Qué ocurre si la API no está disponible durante un build? Usa traducciones en caché como alternativa. Guarda el último pull exitoso en el control de versiones para que los builds siempre tengan una base, incluso si la API no está disponible.
¿Cómo gestiono las traducciones para múltiples entornos? Usa namespacing a nivel de proyecto o de rama. Algunas plataformas TMS admiten sobreescrituras específicas por entorno (staging, production) para el mismo proyecto.
¿Es la localización API-first adecuada para proyectos pequeños? Sí. El flujo de trabajo CLI push/pull es más sencillo que la gestión manual de archivos incluso para proyectos con pocos cientos de cadenas. El coste de configurar la integración con la API es mínimo comparado con el tiempo que se ahorra.
