Saltar al contenido principal

Astro

El paquete translate-projects-astro traduce los archivos JSON de i18n de tu sitio Astro. Escribes los textos en un idioma y obtienes los demás en la estructura de carpetas que espera i18next.

Requisitos​

  • Node.js 18 o superior.
  • Un proyecto y un API token de Translate Projects. Mira Primeros pasos.

1. Instala el paquete​

Terminal
npm i -D translate-projects-astro

2. Escribe tus textos​

Pon los textos del idioma base en public/locales/<idioma base>/. Puedes tener varios archivos .json, también en subcarpetas, con claves anidadas. El paquete solo lee y escribe JSON, así que no depende de la versión de Astro:

public/locales/es/translation.json
{
  "title": "Bienvenido",
  "menu": { "home": "Inicio" }
}

3. Configura la traducción​

Crea translate.mjs. Si no pasas apiKey, se usa la variable de entorno TRANSLATE_PROJECTS_API_KEY:

translate.mjs
import { translateProject } from 'translate-projects-astro';

await translateProject({
  sourceLang: 'es', // Idioma base: el idioma por defecto del proyecto
  targetLangs: ['en', 'pt-BR', 'fr'], // Idiomas a generar
});
OpciónPor defectoDescripción
sourceLang—Idioma de los archivos fuente.
targetLangs—Idiomas a generar; el idioma base se omite.
apiKeyprocess.env.TRANSLATE_PROJECTS_API_KEYAPI token del proyecto.
outputDir./public/localesCarpeta con una subcarpeta por idioma.

Añade el script en package.json:

package.json
{
  "scripts": {
    "translate": "node translate.mjs"
  }
}

4. Traduce​

Terminal
export TRANSLATE_PROJECTS_API_KEY=tu_token
npm run translate

Archivos que genera​

public/locales/
├── es/translation.json      ← fuente, nunca se modifica
├── en/translation.json
├── pt-BR/translation.json
└── fr/translation.json

Cada archivo conserva la estructura del original: objetos anidados, arrays y claves con puntos como "v1.0". Se traducen hasta 3 idiomas en paralelo.

5. Usa las traducciones en Astro​

Puedes leer los archivos con i18next o directamente con import.meta.glob:

src/pages/[lang]/index.astro
---
export function getStaticPaths() {
  const files = import.meta.glob('/public/locales/*/translation.json');
  return Object.keys(files).map((file) => ({
    params: { lang: file.split('/')[3] },
  }));
}

const files = import.meta.glob('/public/locales/*/translation.json', {
  eager: true,
  import: 'default',
});
const { lang } = Astro.params;
const t = files[`/public/locales/${lang}/translation.json`];
---

<h1>{t.title}</h1>

Caché y forzar​

Una segunda ejecución sin cambios hace una sola petición y no traduce nada. Este paquete no tiene --force: para traducir todo de nuevo, borra ~/.config/translate-projects-core/cache.json y vuelve a ejecutar. Más detalles en Caché y errores.

Errores comunes​

translateProject devuelve true si todo salió bien. Si falla, muestra el error, devuelve false y deja el código de salida en 1, sin cerrar tu proceso.

  • Token inválido, errores 4xx/5xx o API caída: la ejecución falla con el mensaje de la API. Los archivos existentes nunca se sobrescriben con datos vacíos o parciales; los idiomas que sí funcionaron se escriben.
  • Falta la key de IA (MISSING_API_KEY): el proyecto no tiene IA configurada. Los textos sin traducir conservan el texto fuente, se muestra un aviso (el código de salida sigue siendo 0) y se piden otra vez en la siguiente ejecución.
  • Source folder not found: revisa sourceLang y outputDir, y ejecuta el comando desde la raíz del sitio.
  • Invalid JSON file: un archivo fuente no es JSON válido; corrígelo. No se escribe nada para él.
Gratis

🚀 Automatiza tus traducciones gratis​

Translate Projects es gratuito. Creas tu proyecto, conectas la key de tu proveedor de IA y solo le pagas a él lo que gastes.

  • Sin planes ni tarjeta de crédito: Todas las funciones están disponibles desde el primer día.
  • Usa tu propia IA: Claude, OpenAI, DeepSeek o Gemini. Tu key se guarda cifrada.
  • Red de traducciones compartida: Si un texto ya fue traducido, lo recibes al instante sin gastar tu key.
  • Panel de administración: Revisa y edita todas tus traducciones desde un solo lugar.

Crear cuenta gratis →

Soporte

Estamos aquí para ayudarte​

Si tienes alguna pregunta, necesitas ayuda o quieres contribuir, no dudes en contactarme. Estoy a tu disposición para apoyarte en lo que necesites.

Apoya el Proyecto​

Si este proyecto te ha sido útil, te invito a invitarme un café. Tu apoyo me ayuda a seguir mejorando y creando contenido de valor. ¡Gracias por estar aquí! ☕

Buy me a coffee