Skip to content

Sitio web de Astro ​

Para sitios de marketing o aplicaciones estáticas de Astro (Astro simple, no Starlight), combine el enrutamiento i18n integrado de Astro con ai-i18n-tools. Consulte también la integración de Astro.

La implementación de referencia es examples/astro-website (consulte también su README): inglés en /, nueve configuraciones regionales de destino en /{locale}/ (de, fr, es, ar, ja, ko, zh-cn, zh-tw, pt-br).

Pipelines híbridos ​

La mayoría de los equipos usan una hibridación de dos canalizaciones (no entran en conflicto):

CanalizaciónUso paraComandosSalida
HTML de páginaEncabezados, párrafos, etiquetas de navegación, matrices en línea en el cuerpo de la plantillatranslate-docssrc/pages/{locale}/index.astro por configuración regional
Cadenas de interfaz de usuario (t())Datos de frontmatter, etiquetas de pestañas de capturas de pantalla, arrays compartidosextract → translate-uipublic/locales/{locale}.json (cadena en el idioma de origen como clave)

Mantenga tres listas alineadas cuando agregue o elimine un idioma: targetLocales en ai-i18n-tools.config.json, i18n.locales en astro.config.mjs (Astro usa códigos de ruta en minúsculas como pt-br) y ui-languages.json (a través de generate-ui-languages). Los nombres de archivo de los paquetes planos usan la carcasa de configuración (pt-BR.json); asigne la ruta pt-br de Astro a ese archivo a través de su campo de manifiesto code (consulte examples/astro-website/src/i18n/locale.ts).

Ejemplos de scripts package.json (del proyecto de referencia):

json
{
  "i18n:extract": "ai-i18n-tools extract",
  "i18n:translate-ui": "ai-i18n-tools translate-ui",
  "i18n:translate": "ai-i18n-tools translate-docs",
  "i18n:locales": "ai-i18n-tools generate-ui-languages",
  "i18n:sync": "ai-i18n-tools sync"
}

Cadenas de UI (SSG) ​

Genera la extracción de la interfaz de usuario con init -t ui-astro-website -P ollama, luego fusiona en un bloque docs[] cuando también traduzcas el HTML de la página (consulta Analizar y reemplazar páginas). También traduce el README del repositorio: init -t ui-astro-website -P ollama --with-readme. Consulta Añadir i18n a tu README y documentos Markdown. Envuelve el texto en t('…') en módulos TypeScript y en el frontmatter de .astro (y bloques de plantilla {expression} cuando prefieras cadenas de UI en lugar de páginas de localización duplicadas). El HTML de la página no necesita t(): translate-docs lo copia. La indicación de JS/TS se aplica a esos archivos de frontmatter y de datos, excepto la instalación y el arranque de i18next — Astro resuelve t en tiempo de compilación con makeT, no con i18next.

bash
ai-i18n-tools init -t ui-astro-website -P ollama
ai-i18n-tools extract
ai-i18n-tools translate-ui

Configura sourceLocale para que coincida con i18n.defaultLocale en astro.config.mjs. Escribe paquetes planos en un directorio que Astro pueda importar en tiempo de compilación (la plantilla usa public/locales/). Resuelve t('…') en tiempo de compilación buscando el literal del idioma de origen como clave (consulta examples/astro-website/src/i18n/t.ts; strings.json es la caché de extracción, no el paquete en tiempo de ejecución). Ese idioma es sourceLocale y puede ser cualquier idioma. El ejemplo usa inglés. No necesitas ai-i18n-tools/runtime ni i18next para un sitio estático a menos que añadas islas de cliente que cambien de idioma después de la carga.

Conecta cada página que llama a t() (la página de localización de origen y cada copia src/pages/{locale}/):

astro
import { loadFlatBundle, makeT } from '../i18n/t';        // or ../../i18n/t in locale subfolders
import { resolvePageLocale, useTranslations } from '../i18n/utils';

const locale = resolvePageLocale(Astro.currentLocale);
const flat = await loadFlatBundle(Astro.currentLocale);
const t = useTranslations(locale, makeT(flat));

Helpers de soporte en el ejemplo: src/i18n/utils.ts, src/i18n/locale.ts y ui-languages.json para etiquetas, dirección y códigos BCP-47. Ejecute generate-ui-languages después de cambiar targetLocales (opcionalmente, configure languagesManifestPath para que el manifiesto se encuentre junto a sus helpers, por ejemplo, src/i18n/ui-languages.json). MainLayout.astro establece <html lang> y <html dir> desde resolveUiLanguage(Astro.currentLocale); LanguagePicker.astro usa getRelativeLocaleUrl desde astro:i18n.

Páginas (analizar y reemplazar) ​

Para páginas de marketing con HTML codificado en archivos .astro, permite que translate-docs extraiga nodos de texto y atributos (alt, title, aria-label, placeholder), los traduzca mediante la caché del documento y escriba copias específicas del idioma en tu árbol de páginas. No necesitas t() para la mayoría de los textos visibles.

Los valores de atributos y claves estructurales no se traducen de forma predeterminada: la protección integrada cubre atributos JSX/HTML como class, id, style, src, href, data-* y la mayoría de los aria-*, además de claves de objeto como class, key y id dentro de los bloques de plantilla {expression}. Use docs[].protectAttributes y docs[].protectKeys para extender esas listas cuando use atributos personalizados (por ejemplo, variant de Tailwind o campos slug de CMS). Las mismas opciones se aplican a MDX JSX durante la traducción de markdown (consulte protectAttributes / protectKeys).

Habilite features.translateDocs y agregue un bloque docs[], por ejemplo:

json
{
  "features": { "translateDocs": true },
  "docs": [{
    "contentPaths": ["src/pages/index.astro"],
    "outputDir": "src/pages",
    "docsOutput": {
      "style": "astro-starlight",
      "docsRoot": "src/pages"
    },
    "addFrontmatter": false
  }]
}

Ejecuta ai-i18n-tools translate-docs (o pnpm i18n:translate en examples/astro-website). La página de origen permanece en src/pages/index.astro (inglés en el ejemplo; sourceLocale puede ser cualquier idioma); cada localización de destino obtiene src/pages/{locale}/index.astro con las importaciones ajustadas para el nivel de directorio adicional (por ejemplo, ../layouts/ → ../../layouts/).

Dentro del cuerpo de la plantilla, los literales de cadena en bloques {expression} (arrays en línea, campos de objeto title/desc) se traducen cuando están orientados al usuario; los valores entre comillas en atributos/claves protegidos, los literales dentro de t('…'), <script> y <style> se dejan sin cambios. El Frontmatter TypeScript no se traduce por esta ruta — mantén el frontmatter compartido (incluidas las importaciones t() y los arrays de datos) idéntico en las páginas en inglés y en las páginas de localización, o vuelve a ejecutar translate-docs después de editar la página en inglés para que las copias de localización recojan los cambios del frontmatter. Para contenido solo de frontmatter, usa la canalización de cadenas de interfaz de usuario en su lugar.

Consulte examples/astro-website para ver la página de destino híbrida completa (HTML a través de translate-docs, etiquetas de pestañas de captura de pantalla a través de t() + translate-ui).

Publicado bajo la licencia MIT.