Skip to content

Document localized footer and navbar for multi-language sites #4209

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ethanpalm merged 5 commits into from
Mar 10, 2026
+157 −3
Merged

Document localized footer and navbar for multi-language sites #4209

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
660153a
Document localized footer and navbar for multi-language sites
mintlify[bot] Mar 9, 2026
e6d1317
Improve i18n guide prose for localized footer/navbar section
ethanpalm Mar 9, 2026
70736bb
fix JSON example and language code
ethanpalm Mar 10, 2026
f66a1d2
fix links
ethanpalm Mar 10, 2026
7f33bf4
Merge branch 'main' into docs-localized-footer-navbar-1773091482
ethanpalm Mar 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
87 changes: 86 additions & 1 deletion guides/internationalization.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@
- `ru` - Russian
- `sv` - Swedish
- `tr` - Turkish
- `ua` - Ukrainian
- `uk` - Ukrainian
- `uz` - Uzbek
- `vi` - Vietnamese
</Expandable>
Expand Down Expand Up @@ -195,6 +195,91 @@
}
```

### Localized footer and navbar

Customize the footer and navbar for each language to display translated content and region-specific links.

Add `footer` and `navbar` properties to each language configuration:

```json docs.json
{
"navigation": {
"languages": [
{
"language": "en",
"footer": {
"socials": {
"x": "https://x.com/mintlify"
},
"links": [
{
"header": "Resources",
"items": [
{ "label": "Documentation", "href": "/en/docs" },
{ "label": "Blog", "href": "https://mintlify.com/blog" }
]
}
]
},
"navbar": {
"links": [
{ "label": "Docs", "href": "/en/docs" }
],
"primary": {
"type": "button",
"label": "Get Started",
"href": "/en/quickstart"
}
},
"groups": [
{
"group": "Getting started",
"pages": ["en/quickstart", "en/index"]
}
]
},
{
"language": "es",
"footer": {
"socials": {
"x": "https://x.com/mintlify"
},
"links": [
{
"header": "Recursos",
"items": [
{ "label": "Documentación", "href": "/es/docs" },
{ "label": "Blog", "href": "https://mintlify.com/blog" }
]
}
]
},
"navbar": {
"links": [
{ "label": "Documentación", "href": "/es/docs" }
],
"primary": {
"type": "button",
"label": "Comenzar",
"href": "/es/quickstart"
}
},
"groups": [
{
"group": "Comenzando",
"pages": ["es/quickstart", "es/index"]
}
]
}
]
}
}
```

Language-specific `footer` and `navbar` override the global settings for that language. If a language doesn't define these properties, it inherits the global configuration.

You can also configure a language-specific `banner` using the same pattern.

## Maintain translations

Keep translations accurate and synchronized with your source content.
Expand Down Expand Up @@ -603,7 +688,7 @@

Consider locale-specific formatting for dates and numbers.

- Date formats: MM/DD/YYYY vs DD/MM/YYYY

Check warning on line 691 in guides/internationalization.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/internationalization.mdx#L691 

Spell out 'YYYY', if it's unfamiliar to the audience.

Check warning on line 691 in guides/internationalization.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/internationalization.mdx#L691 

Spell out 'YYYY', if it's unfamiliar to the audience.
- Number formats: 1,000.00 vs 1.000,00
- Currency symbols: $100.00 vs 100,00€

Expand Down
50 changes: 49 additions & 1 deletion organize/navigation.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -120,11 +120,11 @@

Use the `expanded` property to control the default state of a nested group in the navigation sidebar.

- `expanded: true`: Group is expanded by default.

Check warning on line 123 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L123 

In general, use active voice instead of passive voice ('is expanded').
- `expanded: false` or omitted: Group is collapsed by default.

Check warning on line 124 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L124 

In general, use active voice instead of passive voice ('is collapsed').

<Note>
The `expanded` property only affects nested groups--groups within groups. Top-level groups are always expanded and cannot be collapsed.

Check warning on line 127 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L127 

In general, use active voice instead of passive voice ('be collapsed').
</Note>

```json
Expand Down Expand Up @@ -574,7 +574,7 @@
alt="Decorative graphic of a language switcher."
/>

In the `navigation` object, `languages` is an array where each entry is an object that requires a `language` field and can contain any other navigation fields, including language-specific banner configurations.
In the `navigation` object, `languages` is an array where each entry is an object that requires a `language` field and can contain any other navigation fields, including language-specific banner, footer, and navbar configurations.

We currently support the following languages for localization:

Expand Down Expand Up @@ -618,6 +618,30 @@
"content": "🚀 Version 2.0 is now live! See our [changelog](/en/changelog) for details.",
"dismissible": true
},
"footer": {
"socials": {
"x": "https://x.com/mintlify"
},
"links": [
{
"header": "Resources",
"items": [
{ "label": "Documentation", "href": "/en/docs" },
{ "label": "Blog", "href": "https://mintlify.com/blog" }
]
}
]
},
"navbar": {
"links": [
{ "label": "Docs", "href": "/en/docs" }
],
"primary": {
"type": "button",
"label": "Get Started",
"href": "/en/quickstart"
}
},
"groups": [
{
"group": "Getting started",
Expand All @@ -631,6 +655,30 @@
"content": "🚀 ¡La versión 2.0 ya está disponible! Consulta nuestro [registro de cambios](/es/changelog).",
"dismissible": true
},
"footer": {
"socials": {
"x": "https://x.com/mintlify"
},
"links": [
{
"header": "Recursos",
"items": [
{ "label": "Documentación", "href": "/es/docs" },
{ "label": "Blog", "href": "https://mintlify.com/blog" }
]
}
]
},
"navbar": {
"links": [
{ "label": "Documentación", "href": "/es/docs" }
],
"primary": {
"type": "button",
"label": "Comenzar",
"href": "/es/quickstart"
}
},
"groups": [
{
"group": "Getting started",
Expand All @@ -647,7 +695,7 @@

## Nesting

Navigation elements can be nested within each other to create complex hierarchies. You must have one root-level parent navigation element such as tabs, groups, or a dropdown. You can nest other types of navigation elements within your primary navigation pattern.

Check warning on line 698 in organize/navigation.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/navigation.mdx#L698 

In general, use active voice instead of passive voice ('be nested').

Each navigation element can contain one type of child element at each level of your navigation hierarchy. For example, a tab can contain anchors that contain groups, but a tab cannot contain both anchors and groups at the same level.

Expand Down
23 changes: 22 additions & 1 deletion organize/settings.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -348,11 +348,11 @@
</ResponseField>

<ResponseField name="variables" type="object">
Global variables for use throughout your documentation. Variables are replaced at build time using `{{variableName}}` syntax.

Check warning on line 351 in organize/settings.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings.mdx#L351 

In general, use active voice instead of passive voice ('are replaced').

<Expandable title="Variables">
<ResponseField name="variableName" type="string">
A key-value pair where the key is the variable name and the value is the replacement text. All variables referenced in your content must be defined, or the build fails. Variable names can contain alphanumeric characters, hyphens, and periods. Values are sanitized to prevent XSS attacks.

Check warning on line 355 in organize/settings.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings.mdx#L355 

In general, use active voice instead of passive voice ('be defined').

Check warning on line 355 in organize/settings.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings.mdx#L355 

In general, use active voice instead of passive voice ('are sanitized').
</ResponseField>
</Expandable>
</ResponseField>
Expand Down Expand Up @@ -532,7 +532,28 @@
</Expandable>
</ResponseField>
<ResponseField name="languages" type="array of object">
Language switcher for [multi-language](/organize/navigation#languages) sites.
Language switcher for [multi-language](/organize/navigation#languages) sites. Each language entry can include language-specific `banner`, `footer`, and `navbar` configurations in addition to the navigation structure.

<Expandable title="Languages">
<ResponseField name="language" type='"ar" | "ca" | "cn" | "cs" | "de" | "en" | "es" | "fr" | "he" | "hi" | "id" | "it" | "ja" | "jp" | "ko" | "lv" | "nl" | "no" | "pl" | "pt" | "pt-BR" | "ro" | "ru" | "sv" | "tr" | "uk" | "uz" | "vi" | "zh" | "zh-Hans" | "zh-Hant"' required>
Language code in ISO 639-1 format.
</ResponseField>
<ResponseField name="default" type="boolean">
Whether this is the default language.
</ResponseField>
<ResponseField name="banner" type="object">
Language-specific banner configuration. See [banner](#param-banner-1) for available options.
</ResponseField>
<ResponseField name="footer" type="object">
Language-specific footer configuration. See [footer](#param-footer-1) for available options.
</ResponseField>
<ResponseField name="navbar" type="object">
Language-specific navbar configuration. See [navbar](#param-navbar-1) for available options.
</ResponseField>
<ResponseField name="hidden" type="boolean">
Whether to hide this language option by default.
</ResponseField>
</Expandable>
</ResponseField>
<ResponseField name="versions" type="array of object">
Version switcher for sites with multiple [versions](/organize/navigation#versions).
Expand Down