Skip to content

Integración con Docusaurus ​

Utilice init -t ui-docusaurus y docsOutput.style: "docusaurus" para sitios de documentación de Docusaurus. El preset crea un bloque docs[] con docusaurusCatalogDir para que translate-docs pueda traducir tanto las páginas de markdown como el shell JSON de Docusaurus en un solo comando.

Consulte también Documentos, la demostración ejecutable examples/docusaurus-docs y examples/nextjs-app para una aplicación Next.js combinada con documentos Docusaurus anidados, README plano y activos SVG.

Inicio rápido ​

bash
ai-i18n-tools init -t ui-docusaurus -P openai
# edit ai-i18n-tools.config.json (targetLocales, providers, contentPaths, docusaurusCatalogDir)
pnpm run i18n:sync   # or: ai-i18n-tools sync
cd docs-site && pnpm build   # or: cd examples/docusaurus-docs && pnpm build

Habilita features.translateDocs y establece docs[].docusaurusCatalogDir cuando traduzcas tanto las páginas de documentación como las cadenas de la interfaz del sitio (barra de navegación, pie de página, cadenas del tema). Ejecuta docusaurus write-translations en tu proyecto de Docusaurus cuando actualices @docusaurus/* o cambies las etiquetas de la barra de navegación/pie de página/tema — luego vuelve a ejecutar translate-docs o sync para que el JSON de la interfaz se traduzca en cada carpeta de idioma.

Diseño de página ​

El markdown y MDX en inglés se encuentran bajo la carpeta docs/ de su Docusaurus (por ejemplo docs-site/docs/). Las copias traducidas se escriben en el árbol de contenido del plugin de cada idioma:

text
docs-site/docs/getting-started.md
  →  docs-site/i18n/de/docusaurus-plugin-content-docs/current/getting-started.md
docs-site/docs/guide/quick-start.md
  →  docs-site/i18n/fr/docusaurus-plugin-content-docs/current/guide/quick-start.md

Configure un bloque docs[]:

json
{
  "contentPaths": ["docs-site/docs/"],
  "outputDir": "docs-site/i18n",
  "docusaurusCatalogDir": "docs-site/i18n/en",
  "addFrontmatter": true,
  "docsOutput": {
    "style": "docusaurus",
    "docsRoot": "docs-site/docs"
  }
}

Apunte contentPaths a los archivos y directorios .md / .mdx escritos en sourceLocale. Ese idioma puede ser cualquier idioma. Establezca docsRoot en la misma carpeta que Docusaurus usa como su raíz de contenido. Establezca outputDir en la carpeta padre de cada carpeta de idioma bajo i18n/.

Conecte la internacionalización de Docusaurus internacionalización: mantenga targetLocales en ai-i18n-tools.config.json alineado con la matriz locales en docusaurus.config.js. Cada localeConfigs[locale].path debe coincidir con el nombre de la carpeta bajo i18n/ (por ejemplo path: "fr" para i18n/fr/).

Habilitar i18n en un sitio existente ​

La configuración inicial utiliza la indicación en Añadir i18n a un sitio web o sitio de documentación. La lista de verificación a continuación es el mismo trabajo manual.

  • Agregue el bloque i18n en docusaurus.config.js: defaultLocale, locales y localeConfigs[locale].path cuando la ruta URL deba diferir del código de idioma.
  • Ejecute docusaurus write-translations para que i18n/<defaultLocale>/ exista, luego apunte docusaurusCatalogDir a esa carpeta y ejecute sync.
  • El React personalizado en src/pages y src/components no es markdown. Marque el texto visible para el usuario con <Translate> o translate() de @docusaurus/Translate para que write-translations pueda recopilarlo en code.json. El mensaje debe ser una cadena estática. write-translations escribe i18n/<locale>/code.json; con docusaurusCatalogDir configurado, translate-docs traduce ese JSON con el resto del catálogo de shell. ai-i18n-tools no escanea esos árboles JSX en busca de t().

Cadenas del shell (write-translations) ​

Las etiquetas de la barra de navegación, pie de página, marcador de búsqueda y otros plugins de tema de Docusaurus no se extraen del markdown. Ejecute docusaurus write-translations en su proyecto Docusaurus para generar catálogos JSON bajo la carpeta de idioma predeterminada (normalmente i18n/en/). Luego apunte docs[].docusaurusCatalogDir a esa carpeta:

json
{
  "features": {
    "translateDocs": true
  },
  "docs": [
    {
      "description": "Docusaurus pages + shell JSON",
      "contentPaths": ["docs-site/docs/"],
      "outputDir": "docs-site/i18n",
      "docusaurusCatalogDir": "docs-site/i18n/en",
      "docsOutput": {
        "style": "docusaurus",
        "docsRoot": "docs-site/docs"
      }
    }
  ]
}

Cuando docusaurusCatalogDir esté establecido y features.translateDocs esté habilitado, translate-docs traduce ambos:

  • Páginas de documentación — markdown/MDX desde contentPaths hasta i18n/<locale>/docusaurus-plugin-content-docs/current/
  • Shell JSON — catálogos de barra de navegación, pie de página y plugin de tema desde i18n/en/ hasta las carpetas de idioma hermanas

No coloque el shell JSON de Docusaurus en json[]; use docs[].docusaurusCatalogDir con Documentos en su lugar.

Proyecto de ejemplo ​

examples/docusaurus-docs — Fuentes en inglés en docs/, traducciones confirmadas en i18n/<locale>/docusaurus-plugin-content-docs/current/, además de JSON de shell traducido. Ejecute pnpm start en el puerto 3100 (compilar + servir) para que el menú desplegable de configuración regional funcione; use pnpm dev para la recarga en caliente solo en inglés.

Para cadenas de interfaz de usuario, traducción SVG y un README plano en el mismo diseño de repositorio, consulte examples/nextjs-app (docs-site/ anidado en el puerto 3040).

Publicado bajo la licencia MIT.