Languages

Use navigation.languages to give each translation its own documentation tree and add a language selector to the header. Every configured language builds, and selecting a language opens its first page.

Configure languages#

Set language to a language code such as en, es, or pt-BR. Shiso uses the code as the document language and date-formatting locale. It also enables right-to-left layout for languages such as Arabic and Hebrew.

{
  "navigation": {
    "languages": [
      {
        "language": "en",
        "default": true,
        "tabs": [
          {
            "tab": "Docs",
            "pages": ["index", "installation"]
          }
        ]
      },
      {
        "language": "es",
        "pages": ["es/index", "es/installation"]
      }
    ]
  }
}

Set default: true on the language that should open by default. If you do not set a default, Shiso uses the first visible language. Only one language may be the default.

Content and URLs#

URLs come from page references, not language codes. Keep each translation's files in its own directory, such as es/ or fr/, and use those paths in its page references.

Set hidden: true to keep a language out of the header selector, sitemap, and search while continuing to build its pages and make them directly reachable.

Versions inside languages#

Each language may define its own versions. The version selector then offers only the versions of the active language. Switching languages opens that language's default version.

{
  "navigation": {
    "languages": [
      {
        "language": "en",
        "default": true,
        "versions": [
          { "version": "v2", "default": true, "pages": ["index"] },
          { "version": "v1", "pages": ["v1/index"] }
        ]
      },
      {
        "language": "es",
        "versions": [
          { "version": "v2", "default": true, "pages": ["es/index"] },
          { "version": "v1", "pages": ["es/v1/index"] }
        ]
      }
    ]
  }
}

Built-in search stays inside the active version and language, so results from different documentation scopes are not mixed.