Añadir i18n a un sitio web o sitio de documentación

Esta página está pensada para un sitio de documentación (Markdown o MDX) o un sitio de marketing o estático (un sitio web de Astro o HTML simple) en un solo idioma. La herramienta traduce el contenido de tu página con los modelos de tu proveedor de LLM y escribe una copia localizada por cada idioma. El framework de tu sitio sirve esas copias y proporciona el selector de idioma.

Para una aplicación cuyas cadenas de interfaz de usuario residen en llamadas a t(), usa Añadir i18n a una aplicación JS/TS o Añadir i18n a una aplicación Python en su lugar.

¿Qué tienes?

Su sitio	Plantilla de inicio	Empiece aquí
Astro Starlight o Astro simple	Cadenas de UI ui-starlight / híbridas	Astro
Docusaurus	ui-docusaurus	Docusaurus
VitePress	ui-vitepress	VitePress
Nextra 4 (Next.js App Router)	ui-nextra	Nextra
Fumadocs 4 (Next.js App Router)	ui-fumadocs	Fumadocs
Páginas HTML planas	ui-plain-html o docs-plain-html	Aplicaciones HTML planas
Sin framework de sitio, solo un README y archivos Markdown	docs-markdown, o cualquier plantilla más --with-readme	Añadir i18n a tu README y documentos Markdown

Prompts del agente

• Astro Starlight: solo notas. Archivos Astro t(): prompt JS/TS (omitir i18next).
• Docusaurus: solo notas (<Translate> es la propia API de Docusaurus).
• VitePress: prompt de catálogo de temas.
• Nextra: prompt de diccionario y prompt híbrido t().
• Fumadocs: prompt de catálogo de UI.
• Archivos README y Markdown: prompt de README.

Pasos

La misma estructura funciona para cada framework; los detalles se encuentran en la guía del framework enlazada anteriormente.

1. Instala la CLI y configura la clave API: Instalación, Proveedor y clave API.
2. Genera el esqueleto: ai-i18n-tools init -t <template> -P <provider>.
3. Configura sourceLocale, targetLocales y docs[].contentPaths (las páginas y carpetas escritas en tu idioma de origen). sourceLocale puede ser cualquier idioma. La guía del framework muestra el docsOutput.style correcto.
4. Habilita la i18n de tu framework para que sirva y enlace las páginas localizadas. Cada guía tiene una sección "Habilitar i18n en un sitio existente": VitePress, Docusaurus, Nextra, Fumadocs, Astro.
5. Ejecuta ai-i18n-tools sync (o translate-docs), luego compila el sitio.
6. Verifica una ruta localizada en el navegador. El desplegable de idioma del propio framework es el selector. Para un archivo markdown plano como un README, añade una fila de enlace con languageListBlock.

¿Qué se traduce?

Los cuerpos de las páginas siempre pasan por el pipeline de Documentos. Los elementos de interfaz del framework (navegación, barra lateral, etiquetas de tema) se gestionan en la misma ejecución donde el framework lo soporta, no a través del pipeline de JSON separado.

Framework	Cadenas de shell y tema	Cómo
Docusaurus	Catálogo write-translations ({ message, description })	docs[].docusaurusCatalogDir más translate-docs
VitePress	Catálogo de tema, navegación y barra lateral	docsOutput.vitepressThemeCatalog más translate-docs
Nextra	Etiquetas de barra lateral _meta.ts	Automático con style: "nextra"
Nextra	Diccionario de tema .ts	docs[].nextraDictionaryPath
Fumadocs	Etiquetas de barra lateral meta.json	Automático con style: "fumadocs"
Fumadocs	Catálogo de anulaciones de interfaz de usuario	docsOutput.fumadocsUiCatalog
Astro Starlight	Cadenas de interfaz de usuario integradas en varias configuraciones regionales	Solo páginas

Las imágenes y capturas de pantalla no son traducidas por translate-docs. Para archivos específicos de la configuración regional, consulta Imágenes y capturas de pantalla.

HTML sin formato

Dos opciones, dependiendo de cómo deba comportarse la página:

• Una página que cambia de idioma en el navegador: marca el texto con atributos data-i18n* y usa el tiempo de ejecución de cadenas de interfaz de usuario (ui-plain-html). Consulta Aplicaciones HTML sin formato.
• Un archivo HTML traducido por configuración regional: usa la canalización de documentos (docs-plain-html). Consulta Páginas HTML.

Un archivo pertenece a una ruta.

¿No es su caso?

• Cadenas de interfaz de usuario de la aplicación: Añadir i18n a una aplicación JS/TS o Añadir i18n a una aplicación Python.
• Un README de repositorio junto al sitio, o archivos Markdown y sin un framework de sitio: Añadir i18n a tus documentos README y Markdown. init … --with-readme añade ese bloque junto a una plantilla de sitio.
• JSON de configuración regional anidado independiente: JSON.
• Traducción de cadenas de un sitio y de una aplicación: Combinar canalizaciones.

Referencia para las opciones compartidas y las diferencias por framework: Integraciones.