Skip to content

Add warning about duplicating paths across locales #5487

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
mayankshouche merged 2 commits into from
Apr 22, 2026
+13 −0
Merged

Add warning about duplicating paths across locales #5487

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
df13f71
Add warning about duplicating paths across locales
mintlify[bot] Apr 22, 2026
cdd32cb
Apply suggestion from @ethanpalm
ethanpalm Apr 22, 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
3 changes: 3 additions & 0 deletions es/guides/internationalization.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -109,6 +109,9 @@ Cada entrada de idioma en el array `languages` requiere:

La estructura de navigation puede diferir entre idiomas para adaptarse a las necesidades de contenido específicas de cada idioma.

<Warning>
No utilices la misma ruta de página en más de una locale. Duplicar rutas entre locales produce un comportamiento indefinido. Cada ruta de página debe aparecer únicamente en la navegación de un solo idioma.
</Warning>

<div id="set-default-language">
### Establecer el idioma predeterminado
Expand Down
3 changes: 3 additions & 0 deletions fr/guides/internationalization.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -109,6 +109,9 @@ Chaque entrée de langue dans le tableau `languages` nécessite :

La structure de navigation peut différer selon les langues pour s’adapter aux besoins de contenu propres à chacune.

<Warning>
N’utilisez pas le même chemin de page dans plusieurs locales. La duplication de chemins entre les locales entraîne un comportement indéfini. Chaque chemin de page ne doit apparaître que dans la navigation d’une seule langue.
</Warning>

<div id="set-default-language">
### Définir la langue par défaut
Expand Down
4 changes: 4 additions & 0 deletions guides/internationalization.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -104,6 +104,10 @@

The navigation structure can differ between languages to accommodate language-specific content needs.

<Warning>
Do not use the same page path in more than one language. Duplicating paths across languages results in undefined behavior. Each page path must appear in only one language's navigation.
</Warning>

### Set default language

The first language in the `languages` array is automatically used as the default. To use a different language as the default, either reorder the array or add the `default` property:
Expand Down Expand Up @@ -657,11 +661,11 @@

```
images/
├── dashboard.png # English version

Check warning on line 664 in guides/internationalization.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/internationalization.mdx#L664 

Use 'PNG' instead of 'png'.
├── fr/
│ └── dashboard.png # French version

Check warning on line 666 in guides/internationalization.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/internationalization.mdx#L666 

Use 'PNG' instead of 'png'.
└── es/
└── dashboard.png # Spanish version

Check warning on line 668 in guides/internationalization.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/internationalization.mdx#L668 

Use 'PNG' instead of 'png'.
```

Reference images using relative paths in your translated content.
Expand Down Expand Up @@ -735,10 +739,10 @@
</Accordion>

<Accordion title="How do I handle code examples in translated content?">
Code itself should not be translated—variable names, function calls, and syntax are language-agnostic. Comments within code blocks can be translated if they explain concepts users need to understand. Instructions surrounding code blocks should be fully translated.

Check warning on line 742 in guides/internationalization.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/internationalization.mdx#L742 

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

Check warning on line 742 in guides/internationalization.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/internationalization.mdx#L742 

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

<Accordion title="Does Mintlify support right-to-left languages like Arabic or Hebrew?">
Yes. Arabic (`ar`) and Hebrew (`he`) are in the supported language codes list. Mintlify handles RTL layout automatically when these language codes are configured. Test your documentation in RTL to verify that navigation, tables, and code blocks display correctly.

Check warning on line 746 in guides/internationalization.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/internationalization.mdx#L746 

In general, use active voice instead of passive voice ('are configured').
</Accordion>
</AccordionGroup>
3 changes: 3 additions & 0 deletions zh/guides/internationalization.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -109,6 +109,9 @@ docs/

不同语言的导航结构可以有所不同，以满足各语言特定的内容需求。

<Warning>
请勿在多个语言环境中使用相同的页面路径。跨语言环境复制路径会导致未定义的行为。每个页面路径应仅出现在一种语言的导航中。
</Warning>

<div id="set-default-language">
### 设置默认语言
Expand Down
Loading