Skip to content
docsp
On this page

Versions and languages

Keep docs for old releases, mark versions as deprecated, translate pages and fall back when a translation is missing.

Versions

JSONproject.json
{
  "versions": {
    "current": "2.4",
    "list": ["2.4", "2.3", "1.x"],
    "deprecated": ["1.x"]
  }
}
versions field Effect
current The version served without a URL segment: /rocket/guides/quickstart/. Must be in list.
list Every version, newest first. This is the order of the version menu.
deprecated Pages of these versions show a warning banner that cannot be closed.

With versions, pages live in docs/<version>/<locale>/<section>/. A version in list without its own folder reuses the pages of the current version, so you only copy the folder when a version's docs diverge.

Old versions have the version in the URL: /rocket/1.x/guides/quickstart/. The version menu links to the same page in the other version when it exists there, otherwise to the first page of that version. Version links are plain links and work without JavaScript.

Some content exists only for the current version:

  • OpenAPI operation pages;
  • the changelog;
  • symbol pages, and ::snippet reads the same commit for every version.

A project without versions keeps its pages in docs/<locale>/<section>/ and has no version menu.

Languages

i18n lists the locales. Put it in site.json for every project, or in project.json to give one project its own list.

JSONsite.json
{
  "i18n": {
    "default": "en",
    "fallback": "en",
    "locales": [
      { "code": "en", "label": "English" },
      { "code": "it", "label": "Italiano" },
      { "code": "de", "label": "Deutsch", "status": "partial" }
    ]
  }
}
i18n field Effect
default Locale served without a URL prefix. Pages in other locales start with /<locale>/.
fallback Locale used to show a page that is not translated.
locales[].code Locale code and folder name, for example it or pt-BR.
locales[].label Language name in the language itself, shown in the language menu.
locales[].status partial shows a Partial badge in the language menu.

The URL prefix comes from the site's default locale. A project that lists only other locales still has every page under a prefix.

Missing translations

A page missing in a locale is rendered from i18n.fallback, then from i18n.default, at the URL of the requested locale, with a notice at the top that the page is not translated. The same applies to release notes. Keep the same file names in every locale, so docsp can match the translations of a page.

The language menu remembers the reader's choice.

Interface language

The interface text (menus, buttons, search, notices) is translated into English and Italian. A locale with a dictionary, or whose base language has one (it-CH uses it), gets its interface in that language. Any other locale gets the English interface, marked with lang="en" so screen readers read it with the right pronunciation.

Translated OpenAPI text

Next to openapi.yaml, an openapi.<locale>.yaml file (for example openapi.it.yaml) gives the API pages of that locale their translated summaries and descriptions. Without it, the locale uses the main file. See API reference.

↑ ↓ to move↵ to openSearching docsp