From 4c347e461aae28d22cb2df1eeb474d7ba7c3ad28 Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Thu, 22 Jan 2026 11:48:46 -0800
Subject: [PATCH] Update guides/internationalization.mdx

Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
---
 guides/internationalization.mdx | 56 +++++++++++++++++++++++++++++++++
 1 file changed, 56 insertions(+)

diff --git a/guides/internationalization.mdx b/guides/internationalization.mdx
index da1acf3ec..8e023db6e 100644
--- a/guides/internationalization.mdx
+++ b/guides/internationalization.mdx
@@ -129,6 +129,62 @@ To add global navigation elements that appear across all languages, configure th
 }
 ```
 
+### External URLs for language switcher
+
+For multi-domain documentation setups where different locales are hosted on separate domains, you can configure external URLs in the language switcher. This is useful when not all pages exist in all locales or when you maintain separate documentation sites per region.
+
+Configure default external URLs in your `docs.json`:
+
+```json docs.json
+{
+  "navigation": {
+    "global": {
+      "languages": [
+        {
+          "language": "en",
+          "default": true,
+          "href": "https://developers.example.com/docs"
+        },
+        {
+          "language": "de",
+          "href": "https://developers.example.de/docs"
+        },
+        {
+          "language": "fr",
+          "href": "https://developers.example.fr/docs"
+        },
+        {
+          "language": "es",
+          "href": "https://developers.example.es/docs"
+        }
+      ]
+    }
+  }
+}
+```
+
+#### Per-page locale links
+
+Override the default language switcher URLs for specific pages using frontmatter. This allows you to link directly to the translated version of the current page instead of the homepage.
+
+Add locale-specific links to your page frontmatter using the pattern `{language_code}_link`:
+
+```mdx api-reference/introduction.mdx
+---
+title: "API Introduction"
+description: "Get started with our API"
+de_link: "https://developers.example.de/docs/api-reference/introduction"
+fr_link: "https://developers.example.fr/docs/api-reference/introduction"
+es_link: "https://developers.example.es/docs/api-reference/introduction"
+---
+```
+
+When a user switches languages on this page, they will be directed to the specific translated page URL instead of the default `href` configured in `docs.json`. This is particularly useful for:
+
+- Multi-domain documentation where each locale has its own domain
+- Documentation sites where not all pages are translated
+- Linking to equivalent pages across different documentation systems
+
 ## Maintain translations
 
 Keep translations accurate and synchronized with your source content.