From a619297a7d5958a1901d9a5821342b6b64c8ecf8 Mon Sep 17 00:00:00 2001
From: Fuma Nama <god63820869@gmail.com>
Date: Tue, 24 Dec 2024 11:10:13 +0800
Subject: [PATCH] Docs: improve i18n section

---
 apps/docs/app/docs/layout.tsx                 |  2 +-
 .../content/docs/ui/internationalization.mdx  | 40 +++++++++++--------
 2 files changed, 25 insertions(+), 17 deletions(-)

diff --git a/apps/docs/app/docs/layout.tsx b/apps/docs/app/docs/layout.tsx
index 7bdbed275..dc1c69a83 100644
--- a/apps/docs/app/docs/layout.tsx
+++ b/apps/docs/app/docs/layout.tsx
@@ -1,4 +1,4 @@
-import { DocsLayout, type DocsLayoutProps } from 'fumadocs-ui/layouts/notebook';
+import { DocsLayout, type DocsLayoutProps } from 'fumadocs-ui/layouts/docs';
 import type { ReactNode } from 'react';
 import { MessageCircle } from 'lucide-react';
 import { baseOptions, linkItems } from '@/app/layout.config';
diff --git a/apps/docs/content/docs/ui/internationalization.mdx b/apps/docs/content/docs/ui/internationalization.mdx
index 1e893357b..195e1e328 100644
--- a/apps/docs/content/docs/ui/internationalization.mdx
+++ b/apps/docs/content/docs/ui/internationalization.mdx
@@ -4,6 +4,13 @@ description: Support multiple languages in your documentation
 icon: Globe
 ---
 
+<Callout title='Before you get started'>
+
+    Fumadocs is not a full-powered i18n library, you can also use other libraries like [next-intl](https://github.com/amannn/next-intl).
+    I18n functionality of Fumadocs works without the built-in middleware.
+
+</Callout>
+
 You can setup i18n using Fumadocs CLI or update the configurations manually.
 
 > Read the [Next.js Docs](https://nextjs.org/docs/app/building-your-application/routing/internationalization) to learn more about implementing I18n in Next.js.
@@ -42,7 +49,7 @@ export const source = loader({
 });
 ```
 
-Update the usages to your source:
+Update the usages to your source to include a locale code:
 
 ```ts
 import { source } from '@/lib/source';
@@ -57,7 +64,8 @@ source.getPage(params.slug, params.lang);
 source.getPages(params.lang);
 ```
 
-See [Source API](/docs/headless/source-api) for other usages.
+Note that without providing a locale code, it uses your default locale instead.
+You can see [Source API](/docs/headless/source-api) for other usages.
 
 ### Middleware
 
@@ -105,20 +113,6 @@ export default function RootLayout({
 }
 ```
 
-### Docs Page
-
-Make sure to update references to `source` and configure Static Site Generation correctly.
-
-```json doc-gen:file
-{
-  "file": "../../examples/i18n/app/[lang]/docs/[[...slug]]/page.tsx",
-  "codeblock": {
-    "lang": "tsx",
-    "meta": "title=\"page.tsx\""
-  }
-}
-```
-
 ### Writing Documents
 
 see [Page Conventions](/docs/ui/page-conventions#internationalization) to learn how to organize your documents.
@@ -171,3 +165,17 @@ export const baseOptions: BaseLayoutProps = {
   i18n: true,
 };
 ```
+
+## Navigation
+
+Fumadocs will only handle i18n navigation for its own layouts (e.g. sidebar components),
+you have to re-create components like `<Link>` from `next/link` and `useParams` hook to auto attend the locale to `href`.
+
+In addition, the [`fumadocs-core/dynamic-link`](/docs/headless/components/link#dynamic-hrefs) component supports linking to dynamic hrefs, including the locale prefix.
+For Markdown/MDX content, you may use it instead of the default anchor (`a`) component:
+
+```mdx title="content.mdx"
+import { DynamicLink } from 'fumadocs-core/dynamic-link';
+
+<DynamicLink href="/[lang]/another-page">This is a link</DynamicLink>
+```