Caché, errores y referencia
Todos los paquetes siguen el mismo flujo y se comportan igual ante los errores. Esta página lo explica una vez; cada guía enlaza aquí.
Qué hace cada ejecución
- Calcula un hash de cada archivo fuente y pregunta a la API cuáles cambiaron.
- Envía solo los textos de los archivos que cambiaron.
- Pide la traducción de cada idioma y muestra el progreso en la terminal.
- Descarga las traducciones y escribe un archivo por idioma, con la misma estructura que el original.
Si un texto ya está traducido en la red compartida, la API lo devuelve al instante sin usar tu key de IA.
Caché
Una segunda ejecución sin cambios hace una sola petición y no traduce nada.
| Paquete | Dónde está la caché |
|---|---|
| React, Next.js, Astro, Docusaurus | ~/.config/translate-projects-core/cache.json (en Windows, %APPDATA%\translate-projects-core\cache.json). Es una caché por carpeta de proyecto. |
| Django | locale/.translate-projects.json |
| Laravel | lang/.translate-projects.json |
Forzar una traducción completa
Úsalo, por ejemplo, después de editar traducciones en el panel o de cambiar el modelo de IA.
| Paquete | Cómo forzar |
|---|---|
| Docusaurus | npx translate-projects-docusaurus --force o la opción force: true |
| Django | python manage.py translate --force |
| Laravel | php artisan translate --force |
| React, Next.js, Astro | Borra ~/.config/translate-projects-core/cache.json y vuelve a ejecutar. |
Errores comunes
Ningún error borra ni deja a medias tus archivos traducidos: los idiomas que fallan conservan lo que tenían y los que funcionan se escriben. Ante un error el comando termina con código de salida 1, así que tu CI también falla (en Astro, una traducción parcial es solo un aviso).
| Síntoma | Causa | Solución |
|---|---|---|
401 o Token no válido | El API token no existe, está desactivado o no se cargó la variable. | Comprueba TRANSLATE_PROJECTS_API_KEY y crea un token nuevo en Tokens API si hace falta. |
MISSING_API_KEY al iniciar | El paquete no encontró el API token. | Define TRANSLATE_PROJECTS_API_KEY (o la opción apiKey). Sin token no se hace ninguna petición. |
MISSING_API_KEY en la traducción, o textos que siguen en el idioma base | El proyecto no tiene configurados el proveedor, el modelo o la key de IA. Solo llegan los textos que ya estaban en la red. | Configura la IA del proyecto en el panel y vuelve a ejecutar: los textos que faltan se piden otra vez. |
| Traducción parcial | Algún texto no se tradujo (IA sin key, límite del proveedor, error puntual). | Los textos que faltan quedan en el idioma base y se reintentan solos en la siguiente ejecución. |
El idioma de origen no es el predeterminado | El idioma base del paquete no es el idioma por defecto del proyecto. | Usa el mismo idioma en los dos lados. |
El idioma de destino no está activo en tu proyecto | Ese idioma está desactivado en el proyecto. | Actívalo en el panel o quítalo de los idiomas destino. |
429, 5xx o error de red | La API o tu conexión fallaron. | Cada petición se reintenta 3 veces. Si sigue fallando, vuelve a ejecutar más tarde. |
Referencia rápida
Datos clave para personas y asistentes de IA que integren Translate Projects:
- La API está en
https://api.translateprojects.dev; se puede cambiar conTRANSLATE_PROJECTS_API_URL, por ejemplo para un servidor local. - Autenticación: cabecera
Authorization: Token <TRANSLATE_PROJECTS_API_KEY>. - El idioma base del paquete debe ser el mismo que el idioma por defecto del proyecto.
- La IA (proveedor, modelo y key) se configura en el proyecto, nunca en el paquete.
- Los códigos de idioma siguen el formato
es,en,fr,pt-BR.