mirror of
https://github.com/hanzo-docs/docs.git
synced 2026-10-26 10:55:57 +00:00
Docs: Update i18n sections
This commit is contained in:
fuma-nama
@@ -8,42 +8,63 @@ icon: Globe
|
||||
|
||||
## Setup
|
||||
|
||||
Define all supported languages in a file.
|
||||
Define the i18n configurations in a file, we will import it with `@/i18n` in this guide.
|
||||
|
||||
```ts title="i18n.ts"
|
||||
export const defaultLanguage = 'en';
|
||||
export const languages = ['en', 'cn'];
|
||||
```json doc-gen:file
|
||||
{
|
||||
"file": "../../examples/i18n/i18n.ts",
|
||||
"codeblock": {
|
||||
"lang": "ts",
|
||||
"meta": "title=\"i18n.ts\""
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Source API
|
||||
|
||||
Change your current source configurations.
|
||||
|
||||
```ts title="source.ts"
|
||||
import { languages } from '@/i18n';
|
||||
import { i18n } from '@/i18n';
|
||||
import { loader } from 'fumadocs-core/source';
|
||||
|
||||
export const { getPage, getPages, pageTree } = loader({
|
||||
languages,
|
||||
...
|
||||
export const { getPage, getPages, pageTree, getLanguages } = loader({
|
||||
i18n,
|
||||
// other options
|
||||
});
|
||||
```
|
||||
|
||||
Create the middleware that redirects users when missing locale.
|
||||
Update the usages to your source:
|
||||
|
||||
```ts title="middleware.ts"
|
||||
import { defaultLanguage, languages } from '@/i18n';
|
||||
import { createI18nMiddleware } from 'fumadocs-core/middleware';
|
||||
```ts
|
||||
import { getPage, getPages, pageTree } from '@/app/source';
|
||||
|
||||
export default createI18nMiddleware({
|
||||
languages,
|
||||
defaultLanguage,
|
||||
});
|
||||
// get page tree
|
||||
pageTree[params.lang];
|
||||
|
||||
export const config = {
|
||||
// Matcher ignoring `/_next/` and `/api/`
|
||||
matcher: ['/((?!api|_next/static|_next/image|favicon.ico).*)'],
|
||||
};
|
||||
// get page
|
||||
getPage(params.slug, params.lang);
|
||||
|
||||
// get pages
|
||||
getPages(params.lang);
|
||||
```
|
||||
|
||||
### Middleware
|
||||
|
||||
Create a middleware that redirects users to appropriate locale.
|
||||
|
||||
```json doc-gen:file
|
||||
{
|
||||
"file": "../../examples/i18n/middleware.ts",
|
||||
"codeblock": {
|
||||
"lang": "ts",
|
||||
"meta": "title=\"middleware.ts\""
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Root Layout
|
||||
|
||||
Create a dynamic route `/app/[lang]`, and move all special files to
|
||||
the folder.
|
||||
|
||||
@@ -96,6 +117,23 @@ export default function RootLayout({
|
||||
|
||||
</UIOnly>
|
||||
|
||||
### Docs Page
|
||||
|
||||
Make sure to configure **Static Generation** correctly for your pages.
|
||||
|
||||
The `generateStaticParams` function should return an item for every page in different languages.
|
||||
On Fumadocs UI, it looks like:
|
||||
|
||||
```json doc-gen:file
|
||||
{
|
||||
"file": "../../examples/i18n/app/[lang]/[[...slug]]/page.tsx",
|
||||
"codeblock": {
|
||||
"lang": "tsx",
|
||||
"meta": "title=\"page.tsx\""
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Writing Documents
|
||||
|
||||
<UIOnly>
|
||||
@@ -114,47 +152,11 @@ export default function RootLayout({
|
||||
|
||||
Configure i18n on your search solution. For Flexsearch, see [Setup I18n](/docs/headless/search/flexsearch#internationalization).
|
||||
|
||||
### Get Pages
|
||||
## Configurations
|
||||
|
||||
To get the pages of a specific language, use the utilities exported from
|
||||
`source.ts`.
|
||||
You can also customise the i18n middleware from `i18n.ts`.
|
||||
|
||||
```ts
|
||||
import { getPage, getPages, pageTree } from '@/app/source';
|
||||
|
||||
// get page tree
|
||||
pageTree[params.lang];
|
||||
|
||||
// get page
|
||||
getPage(params.slug, params.lang);
|
||||
|
||||
// get pages
|
||||
getPages(params.lang);
|
||||
```
|
||||
|
||||
### Static Generation
|
||||
|
||||
Generate parameters for every language and page.
|
||||
|
||||
```tsx
|
||||
import { getPages } from '@/app/source';
|
||||
import { languages } from '@/i18n';
|
||||
|
||||
export async function generateStaticParams() {
|
||||
return languages.flatMap((lang) =>
|
||||
getPages(lang)!.map((page) => ({
|
||||
slug: page.slug,
|
||||
lang,
|
||||
})),
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### Middleware Options
|
||||
|
||||
You can also customise the I18n middleware.
|
||||
|
||||
#### Hide Locale Prefix
|
||||
### Hide Locale Prefix
|
||||
|
||||
To hide the locale prefix, for example, use `/` instead of `/en` where `en` is the default locale, use the `hideLocale` option.
|
||||
|
||||
@@ -167,21 +169,20 @@ To hide the locale prefix, for example, use `/` instead of `/en` where `en` is t
|
||||
> It uses `NextResponse.rewrite` under the hood.
|
||||
|
||||
```ts
|
||||
import { defaultLanguage, languages } from '@/i18n';
|
||||
import { createI18nMiddleware } from 'fumadocs-core/middleware';
|
||||
import type { I18nConfig } from 'fumadocs-core/i18n';
|
||||
|
||||
export default createI18nMiddleware({
|
||||
languages,
|
||||
defaultLanguage,
|
||||
export const i18n: I18nConfig = {
|
||||
defaultLanguage: 'en',
|
||||
languages: ['en', 'cn'],
|
||||
hideLocale: 'default-locale',
|
||||
});
|
||||
};
|
||||
```
|
||||
|
||||
<UIOnly>
|
||||
|
||||
### Adding Translations
|
||||
|
||||
We only provide english translation by default, you have to pass your translations to the provider.
|
||||
We only provide English translation by default, you have to pass your translations to the provider.
|
||||
|
||||
```tsx
|
||||
import { I18nProvider } from 'fumadocs-ui/i18n';
|
||||
|
||||
@@ -123,31 +123,21 @@ with Fumadocs UI later.
|
||||
|
||||
Use `createI18nSearchAPI` for i18n functionality.
|
||||
|
||||
<div className='steps'>
|
||||
<div className='steps [&_h4]:step'>
|
||||
|
||||
<div className='step'>
|
||||
<h4>Update the route handler</h4>
|
||||
|
||||
Update the route handler.
|
||||
|
||||
```ts title="api/search/route.ts"
|
||||
import { languages } from '@/i18n';
|
||||
import { getPages } from '@/source';
|
||||
import { createI18nSearchAPI } from 'fumadocs-core/search/server';
|
||||
|
||||
export const { GET } = createI18nSearchAPI('advanced', {
|
||||
indexes: languages.map((lang) => {
|
||||
const pages = getPages(lang)!.map((page) => ({
|
||||
...
|
||||
}));
|
||||
|
||||
return [lang, pages];
|
||||
}),
|
||||
});
|
||||
```json doc-gen:file
|
||||
{
|
||||
"file": "../../examples/i18n/app/api/search/route.ts",
|
||||
"codeblock": {
|
||||
"lang": "ts",
|
||||
"meta": "title=\"app/api/search/route.ts\""
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
<div className='step'>
|
||||
<h4>Update search client</h4>
|
||||
|
||||
Add `locale` to search dialog, this will only allow pages with specified
|
||||
|
||||
@@ -168,8 +158,6 @@ function Dialog() {
|
||||
|
||||
</div>
|
||||
|
||||
</div>
|
||||
|
||||
## Search Client
|
||||
|
||||
`useDocsSearch` is a hook that combines debounce value and [`useSWR`](https://swr.vercel.app).
|
||||
|
||||
@@ -14,10 +14,7 @@ export default async function Page({
|
||||
params: { lang: string; slug?: string[] };
|
||||
}) {
|
||||
const page = getPage(params.slug, params.lang);
|
||||
|
||||
if (page == null) {
|
||||
notFound();
|
||||
}
|
||||
if (!page) notFound();
|
||||
|
||||
const MDX = page.data.exports.default;
|
||||
|
||||
@@ -47,8 +44,7 @@ export function generateMetadata({
|
||||
params: { lang: string; slug?: string[] };
|
||||
}) {
|
||||
const page = getPage(params.slug, params.lang);
|
||||
|
||||
if (page == null) notFound();
|
||||
if (!page) notFound();
|
||||
|
||||
return {
|
||||
title: page.data.title,
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
import { I18nConfig } from 'fumadocs-core/i18n';
|
||||
import type { I18nConfig } from 'fumadocs-core/i18n';
|
||||
|
||||
export const i18n: I18nConfig = {
|
||||
defaultLanguage: 'en',
|
||||
|
||||
Reference in New Issue
Block a user