Internationalization

Squidoc uses @squidoc/plugin-i18n for localized documentation. The plugin keeps the default locale at your normal docs URL and publishes every additional locale under its locale code.

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

With the default docs base path, English pages publish under /docs and Spanish pages publish under /es/docs.

Locale codes should use BCP 47-style casing such as en, es, or pt-BR. Squidoc rejects underscore formats such as en_US because those create awkward URL paths and inconsistent SEO metadata.

Folder layout

Default locale content lives directly in docs/:

docs/
  index.md
  configuration.md

Additional locales live in a folder named after the locale code:

docs/
  es/
    index.md
    configuration.md

The Spanish files above publish to /es/docs and /es/docs/configuration.

Versioning

i18n composes with @squidoc/plugin-versions. When both plugins are installed, list @squidoc/plugin-versions before @squidoc/plugin-i18n in docs.config.ts:

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" },
      ],
    },
  },
];

Squidoc warns during build and check if the plugins are ordered the other way around. Put translated archived docs under the locale folder with the same version layout:

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

Those publish to /docs/versions/0.1/configuration and /es/docs/versions/0.1/configuration.

Theme UI

The plugin adds a locale-selector theme slot. The basic theme renders it as a compact language control in the top navbar so language switching stays available without crowding the docs sidebar. Theme authors should render this slot in docs layouts when they want localized sites to expose language switching.

When a matching translated page exists, switching languages keeps readers on the same page. If the target locale does not have that page, the selector falls back to that locale's docs root.

Navigation is scoped to pages that exist in the active locale. If a translated locale does not include a page, that nav item is hidden for that locale instead of linking to untranslated or missing content.

Search and SEO

Search results are scoped to the current locale and current version. A reader on /es/docs sees Spanish results; a reader on /docs/versions/0.1 sees results for that version.

The SEO plugin reads i18n metadata and emits hreflang alternates for translated pages when site.url is configured.

Current limits

Squidoc does not translate content for you. The plugin only handles routing, metadata, language switching, search scoping, and SEO alternates.

Localized slugs are not supported yet. Keep translated pages at the same path as the source page so selectors, alternates, and future translation tooling can match them reliably.