From d28ab975c05076967a0ddd51213e36e2eb0f4980 Mon Sep 17 00:00:00 2001 From: Brandon Waselnuk Date: Thu, 2 Jan 2025 11:00:21 -0800 Subject: [PATCH 1/5] added localization setup details to versioning page --- settings/global.mdx | 2 +- settings/versioning.mdx | 54 +++++++++++++++++++++++++++++++++++------ 2 files changed, 47 insertions(+), 9 deletions(-) diff --git a/settings/global.mdx b/settings/global.mdx index 53d5fb73b..4c1d8a7c6 100644 --- a/settings/global.mdx +++ b/settings/global.mdx @@ -313,7 +313,7 @@ Japanese, and Portuguese. For more information, please refer to our -[versioning documentation](/settings/versioning). +[versioning & localization documentation](/settings/versioning). Example: diff --git a/settings/versioning.mdx b/settings/versioning.mdx index bb45dbdca..9de46706b 100644 --- a/settings/versioning.mdx +++ b/settings/versioning.mdx @@ -1,12 +1,16 @@ --- -title: 'Versioning' -description: 'Build separate versions' +title: 'Versioning & Localization' +description: 'Build separate versions or localizations' icon: 'square-chevron-down' --- +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. -## Setup +## 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. @@ -26,7 +30,7 @@ If you would like to specify a default version, you can do so like this: `mint.json`. -## Versioning Groups and Pages +### 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. @@ -55,7 +59,7 @@ version: 'v2' 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. -### Versioning Tabs and Anchors +#### 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. @@ -102,7 +106,7 @@ In `mint.json`, simply add `version` to your tab or anchor. Tabs and anchors wit ``` -### Sharing Between Versions +#### 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! @@ -110,7 +114,7 @@ Not _all_ content has to be hidden though! Any content without a specified versi 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. -## Troubleshooting +### Troubleshooting Common errors and how to fix them @@ -126,4 +130,38 @@ Common errors and how to fix them navigation, make sure you spelled the version the same as in your `versions` array in `mint.json`. - \ No newline at end of file + + +## Localization + +### Setup + +Using `"versions"` in your `mint.json` file where `en`, `fr`, and `es` are the names of your localizations. The first localization from the array serves as the default localization. + +We currently support localization in English, Chinese, Spanish, French, Japanese, and Portuguese. + +Set your localization in your `mint.json` file like this: + +```json +"versions": [ + { + "name": "English", + "locale": "en", + }, + { + "name": "French", + "locale": "fr", + }, + { + "name": "Spanish", + "locale": "es" + } +] +``` + + + The versions dropdown will show your localizations in the order you include them in + `mint.json`. + + +Once setup, the rest of localization is handled by the versioning setup described above. \ No newline at end of file From f689fabce05c6ff63303841f873332218a3b10a9 Mon Sep 17 00:00:00 2001 From: Brandon Waselnuk Date: Thu, 2 Jan 2025 13:02:19 -0800 Subject: [PATCH 2/5] Update settings/versioning.mdx Co-authored-by: Hahnbee Lee <55263191+hahnbeelee@users.noreply.github.com> --- settings/versioning.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/settings/versioning.mdx b/settings/versioning.mdx index 9de46706b..c291f401c 100644 --- a/settings/versioning.mdx +++ b/settings/versioning.mdx @@ -136,7 +136,7 @@ Common errors and how to fix them ### Setup -Using `"versions"` in your `mint.json` file where `en`, `fr`, and `es` are the names of your localizations. The first localization from the array serves as the default localization. +`"versions"` in your `mint.json` can be leveraged to create different language versions. The first localization from the array serves as the default localization. We currently support localization in English, Chinese, Spanish, French, Japanese, and Portuguese. From ff5a336412a3068e1ff4453a0b6b69e0a7a6f828 Mon Sep 17 00:00:00 2001 From: Brandon Waselnuk Date: Thu, 2 Jan 2025 13:02:40 -0800 Subject: [PATCH 3/5] Update settings/versioning.mdx Co-authored-by: Hahnbee Lee <55263191+hahnbeelee@users.noreply.github.com> --- settings/versioning.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/settings/versioning.mdx b/settings/versioning.mdx index c291f401c..d633860d9 100644 --- a/settings/versioning.mdx +++ b/settings/versioning.mdx @@ -138,7 +138,7 @@ Common errors and how to fix them `"versions"` in your `mint.json` can be leveraged to create different language versions. The first localization from the array serves as the default localization. -We currently support localization in English, Chinese, Spanish, French, Japanese, and Portuguese. +We currently support localization in English (`en`), Chinese, Spanish (`es`), French (`fr`), Japanese, and Portuguese. Set your localization in your `mint.json` file like this: From 68f8b1af825910afc2b5a0485dfe64cd65958473 Mon Sep 17 00:00:00 2001 From: Hahnbee Lee <55263191+hahnbeelee@users.noreply.github.com> Date: Thu, 2 Jan 2025 16:14:28 -0800 Subject: [PATCH 4/5] update copy --- settings/global.mdx | 4 ++-- settings/versioning.mdx | 36 +++++++++++++++++++++--------------- 2 files changed, 23 insertions(+), 17 deletions(-) diff --git a/settings/global.mdx b/settings/global.mdx index 4c1d8a7c6..350cb3c18 100644 --- a/settings/global.mdx +++ b/settings/global.mdx @@ -308,8 +308,8 @@ locale. We currently support localization in English, Chinese, Spanish, French, Japanese, and Portuguese. - Localization applies to the UI and fixed assets in the docs, such as "was this - page helpful". + Localization auto-translates the UI and fixed assets in the docs, such as "Was + this page helpful?". You must translate the content of the pages yourself. For more information, please refer to our diff --git a/settings/versioning.mdx b/settings/versioning.mdx index d633860d9..5e723f264 100644 --- a/settings/versioning.mdx +++ b/settings/versioning.mdx @@ -1,7 +1,7 @@ --- -title: 'Versioning & Localization' -description: 'Build separate versions or localizations' -icon: 'square-chevron-down' +title: "Versioning & Localization" +description: "Build separate versions or localizations" +icon: "square-chevron-down" --- Mintlify supports versioning or localization. You can use one or the other, not both. @@ -49,14 +49,17 @@ You can also specify the version of a single page in the page metadata. Versions ```yaml Pages (quickstart.mdx) --- -title: 'Quickstart' -version: 'v2' +title: "Quickstart" +version: "v2" --- ``` + - 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. + 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. #### Versioning Tabs and Anchors @@ -104,6 +107,7 @@ In `mint.json`, simply add `version` to your tab or anchor. Tabs and anchors wit }, ], ``` + #### Sharing Between Versions @@ -111,7 +115,10 @@ In `mint.json`, simply add `version` to your tab or anchor. Tabs and anchors wit 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! - 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. + 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. ### Troubleshooting @@ -123,6 +130,7 @@ Common errors and how to fix them 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. + @@ -136,13 +144,11 @@ Common errors and how to fix them ### Setup -`"versions"` in your `mint.json` can be leveraged to create different language versions. The first localization from the array serves as the default localization. +`"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, Spanish (`es`), French (`fr`), Japanese, and Portuguese. +We currently support localization in English (`en`), Chinese (`cn`), Spanish (`es`), French (`fr`), Japanese (`jp`), Portuguese (`pt`), and German (`de`). -Set your localization in your `mint.json` file like this: - -```json +```json mint.json example "versions": [ { "name": "English", @@ -160,8 +166,8 @@ Set your localization in your `mint.json` file like this: ``` - The versions dropdown will show your localizations in the order you include them in - `mint.json`. + The versions dropdown will show your localizations in the order you include + them in `mint.json`. -Once setup, the rest of localization is handled by the versioning setup described above. \ No newline at end of file +Once setup, the rest of localization is handled by the versioning setup described above. From d8de8e4ba3457b795b6bcadfb712e10f4bb0f779 Mon Sep 17 00:00:00 2001 From: Hahnbee Lee <55263191+hahnbeelee@users.noreply.github.com> Date: Thu, 2 Jan 2025 16:15:14 -0800 Subject: [PATCH 5/5] add the --- settings/versioning.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/settings/versioning.mdx b/settings/versioning.mdx index 5e723f264..bc60a79b1 100644 --- a/settings/versioning.mdx +++ b/settings/versioning.mdx @@ -167,7 +167,7 @@ We currently support localization in English (`en`), Chinese (`cn`), Spanish (`e The versions dropdown will show your localizations in the order you include - them in `mint.json`. + them in the `mint.json`. Once setup, the rest of localization is handled by the versioning setup described above.