Improved i18n docs

1 files changed, 50 insertions, 2 deletions

diff --git a/docs/src/content/docs/guides/i18n.md b/docs/src/content/docs/guides/i18n.md
index 75cb5158..4765f77d 100644
--- a/docs/src/content/docs/guides/i18n.md
+++ b/docs/src/content/docs/guides/i18n.md
@@ -2,11 +2,11 @@
 title: Internationalization (i18n)
 ---
 
-Starlight provides built-in support for multilingual sites.
+Starlight provides built-in support for multilingual sites, including routing, fallback content, and full right-to-left (RTL) language support.
 
 ## Configure i18n
 
-1. Tell Starlight about the languages you support by passing a `locales` object to the Starlight integration:
+1. Tell Starlight about the languages you support by passing `locales` and `defaultLocale` to the Starlight integration:
 
    ```js
    // astro.config.mjs
@@ -39,6 +39,8 @@ Starlight provides built-in support for multilingual sites.
    });
    ```
 
+   Your `defaultLocale` will be used for fallback content and UI labels, so choose the language you are most likely to start writing content in, or already have content for.
+
 2. Create a directory for each language in `src/content/docs/`.
    For example, assuming the configuration shown in step 1, this might look like:
 
@@ -48,3 +50,49 @@ Starlight provides built-in support for multilingual sites.
          - ar/
          - en/
          - zh/
+
+3. You can now create content files in your language directories. Use the same file name to tie pages together across languages. For example, `ar/index.md` and `en/index.md` would represent the homepage for Arabic and English respectively.
+
+### Use a root locale
+
+You can use a “root” locale to serve a language without any i18n prefix in its path. For example, if English is your root locale, an English page path might look like `/about` instead of `/en/about`.
+
+To set a root locale, use the `root` key in your `locales` config:
+
+```js
+// astro.config.mjs
+import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+
+export default defineConfig({
+  integrations: [
+    starlight({
+      locales: {
+        root: {
+          label: 'English',
+          lang: 'en', // lang is required for root locales
+        },
+        zh: {
+          label: '简体中文',
+          lang: 'zh-CN',
+        },
+      },
+    }),
+  ],
+});
+```
+
+When using a `root` locale, place pages for that language directly in `src/content/docs/` instead of in a dedicated language folder. For example, here are the home page files for English and Chinese when using the config above:
+
+- src/
+  - content/
+    - docs/
+      - index.md
+      - zh/
+        - index.md
+
+## Fallback content
+
+Starlight expects you to create equivalent pages in all your languages. For example, if you have an `en/about.md` file, you should create an `about.md` for each other language you support.
+
+If a translation is not yet available for a language, Starlight will show readers the content for that page in the default language (set via `defaultLocale`). For example, if you have not yet created a French version of an about page and your default language is English, visitors to `/fr/about` will see the English content. This helps you add content in your default language and then progressively translate it when your translators have time.