Internacionalización

Squidoc usa @squidoc/plugin-i18n para documentación localizada. El idioma predeterminado permanece en la URL normal de docs y cada idioma adicional se publica bajo su código.

plugins: [
  {
    name: "@squidoc/plugin-i18n",
    options: {
      defaultLocale: "en",
      locales: [
        { code: "en", label: "English" },
        { code: "es", label: "Español" },
      ],
    },
  },
];

Con docs.basePath predeterminado, las páginas en inglés se publican en /docs y las páginas en español en /es/docs.

Los códigos deben usar formato BCP 47 como en, es o pt-BR. Squidoc rechaza formatos con guion bajo como en_US.

Estructura de carpetas

El idioma predeterminado vive directamente en docs/. Los idiomas adicionales viven en una carpeta con el código del idioma:

docs/
  index.md
  configuration.md
  es/
    index.md
    configuration.md

Versionado

i18n se compone con @squidoc/plugin-versions. Cuando ambos están instalados, lista @squidoc/plugin-versions antes de @squidoc/plugin-i18n.

Las traducciones versionadas usan la misma estructura dentro del idioma:

docs/
  versions/
    0.1/
      configuration.md
  es/
    versions/
      0.1/
        configuration.md

Eso se publica como /docs/versions/0.1/configuration y /es/docs/versions/0.1/configuration, salvo que personalices los prefijos de versiones.

UI de tema

El plugin agrega el slot locale-selector. El tema básico lo renderiza en la navbar como un control compacto de idioma.

Cuando existe una traducción equivalente, cambiar idioma mantiene al lector en la misma página. Si esa página no existe en el idioma destino, el selector cae al inicio de docs de ese idioma.

La navegación se limita a páginas existentes en el idioma activo. Si una traducción no existe, ese item no aparece para evitar enlaces rotos.

Búsqueda y SEO

La búsqueda se limita al idioma y versión activos. El plugin SEO lee los metadatos i18n y emite alternates hreflang cuando site.url está configurado.

Límites actuales

Squidoc no traduce contenido automáticamente. El plugin maneja rutas, metadatos, selector de idioma, búsqueda por idioma y alternates SEO.

Los slugs localizados todavía no están soportados. Mantén las páginas traducidas en la misma ruta que la página fuente.

Ejemplos de referencia

plugins: [
  {
    name: "@squidoc/plugin-versions",
    options: {
      versions: [{ name: "0.1", label: "0.1" }],
    },
  },
  {
    name: "@squidoc/plugin-i18n",
    options: {
      defaultLocale: "en",
      locales: [
        { code: "en", label: "English" },
        { code: "es", label: "Español" },
      ],
    },
  },
];

docs/
  versions/
    0.1/
      configuration.md
  es/
    versions/
      0.1/
        configuration.md