# Versions and languages

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

## Versions

```json title="project.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.

```json title="site.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](../features/api-reference.md).
