> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify-delete-quickstart-page-389072bb.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Versioning & Localization

> Build separate versions or localizations

Mintlify supports versioning or localization. You can use one or the other, not both.

These guides will assume `v1` pages are in a folder named `v1`, `v2` pages are in a folder named `v2`, and so on. While this method of structuring your files isn't strictly necessary, it's a great way to keep your files organized.

## Versioning

### Setup

Add `"versions": ["v2", "v1"]` to your `mint.json` file where `v1` and `v2` are the names of your versions. You can put any number of versions in this array. The first version from the array serves as the default version.

If you would like to specify a default version, you can do so like this:

```json
"versions": [
  {
    "name": "version-name",
    "default": true
  }
]
```

<Tip>
  The versions dropdown will show your versions in the order you include them in
  `mint.json`.
</Tip>

### Versioning Groups and Pages

The best way to specify page versions is by adding a version value to a group in the navigation. When you specify the version of a group, that version is applied to all pages within that group.

You can also specify the version of a single page in the page metadata. Versions on individual pages always take precedence.

<CodeGroup>
  ```json Groups (mint.json)
  "navigation": [
    {
      "group": "Getting Started",
      "version": "v1",
      "pages": [...]
    }
  ],
  ```

  ```yaml Pages (quickstart.mdx)
  ---
  title: "Quickstart"
  version: "v2"
  ---
  ```
</CodeGroup>

<Warning>
  While it is possible to nest versioned groups within versioned groups, it is
  not recommended. If you do take this approach, the more deeply-nested version
  takes precedence.
</Warning>

#### Versioning Tabs and Anchors

You can hide a tab or anchor based on a version. This is useful if you have links that are only relevant in one version. Importantly, this does **not** apply the version to the pages within that anchor.

In `mint.json`, simply add `version` to your tab or anchor. Tabs and anchors without a specified version are shown in every version.

<CodeGroup>
  ```json Tabs
  "tabs": [
    {
      "name": "API Reference V1",
      "url": "v1/api-reference",
      "version": "v1"
    },
    {
      "name": "API Reference V2",
      "url": "v2/api-reference",
      "version": "v2"
    },
    {
      "name": "Migrating from V1 to V2",
      "url": "https://mintlify.com/changelog/v2"
    },
  ],
  ```

  ```json Anchors
  "anchors": [
    {
      "name": "API Reference V1",
      "url": "v1/api-reference",
      "version": "v1"
    },
    {
      "name": "API Reference V2",
      "url": "v2/api-reference",
      "version": "v2"
    },
    {
      "name": "Migrating from V1 to V2",
      "url": "https://mintlify.com/changelog/v2",
      "version": "v2"
    },
  ],
  ```
</CodeGroup>

#### Sharing Between Versions

Not *all* content has to be hidden though! Any content without a specified version appears in every version so you don't have to duplicate content!

<Tip>
  When using localization with versioning, each version can have its own set of
  translations. This means you can have different language versions for
  different API versions, giving you full flexibility in managing both versioned
  and localized content.
</Tip>

### Troubleshooting

Common errors and how to fix them

<AccordionGroup>
  <Accordion title="Pages Show Up In Wrong Version" icon="circle-exclamation">
    You likely nested a version inside of another. For example, your group had version "v1" but your page had version "v2".

    We do not recommend nesting versions inside of each other because it's hard to maintain your docs later.
  </Accordion>

  <Accordion title="Missing Pages" icon="circle-exclamation">
    If you add versions to your docs and the pages disappeared from your
    navigation, make sure you spelled the version the same as in your `versions`
    array in `mint.json`.
  </Accordion>
</AccordionGroup>

## Localization

### Setup

`"versions"` in your `mint.json` can be leveraged to create different language versions by adding a `locale` value to the version. The first localization from the array serves as the default localization.

We currently support localization in English (`en`), Chinese (`cn`), Spanish (`es`), French (`fr`), Japanese (`jp`), Portuguese (`pt`), and German (`de`).

```json mint.json example
"versions": [
  {
    "name": "English",
    "locale": "en",
  },
  {
    "name": "French",
    "locale": "fr",
  },
  {
    "name": "Spanish",
    "locale": "es"
  }
]
```

<Tip>
  The versions dropdown will show your localizations in the order you include
  them in the `mint.json`.
</Tip>

Once setup, the rest of localization is handled by the versioning setup described above.