Internationalization

Read the Next.js Docs to learn more about implementing I18n in Next.js.

Auto Setup

Initialize i18n with CLI.

npx styledsea init i18n

Setup

Define the i18n configurations in a file, we will import it with @/ilb/i18n in this guide.

lib/i18n.ts

import type { I18nConfig } from 'styledsea-docs-core/i18n';
 
export const i18n: I18nConfig = {
  defaultLanguage: 'en',
  languages: ['en', 'cn'],
};

Change your current source configurations.

lib/source.ts

import { i18n } from '@/lib/i18n';
import { loader } from 'styledsea-docs-core/source';
 
export const source = loader({
  i18n,
  // other options
});

Update the usages to your source:

import { source } from '@/lib/source';
 
// get page tree
source.pageTree[params.lang];
 
// get page
source.getPage(params.slug, params.lang);
 
// get pages
source.getPages(params.lang);

Middleware

Create a middleware that redirects users to appropriate locale.

middleware.ts

import { createI18nMiddleware } from 'styledsea-docs-core/i18n';
import { i18n } from '@/lib/i18n';
 
export default createI18nMiddleware(i18n);
 
export const config = {
  // Matcher ignoring `/_next/` and `/api/`
  matcher: ['/((?!api|_next/static|_next/image|favicon.ico).*)'],
};

See Middleware for customisable options.

Root Layout

Create a dynamic route /app/[lang], and move all special files from /app to the folder.

A I18nProvider is needed for localization. Wrap the root provider inside your I18n provider.

import { RootProvider } from 'styledsea-docs-interface/provider';
import { I18nProvider } from 'styledsea-docs-interface/i18n';
 
export default function RootLayout({
  params,
  children,
}: {
  params: { lang: string };
  children: React.ReactNode;
}) {
  return (
    <html lang={params.lang}>
      <body>
        <I18nProvider locale={params.lang}>
          <RootProvider>{children}</RootProvider>
        </I18nProvider>
      </body>
    </html>
  );
}

Docs Page

Make sure to update references to source and configure Static Site Generation correctly.

page.tsx

import { source } from '@/lib/source';
import {
  DocsPage,
  DocsBody,
  DocsTitle,
  DocsDescription,
} from 'styledsea-docs-interface/page';
import { notFound } from 'next/navigation';
import defaultMdxComponents from 'styledsea-docs-interface/mdx';
import { withImage } from '@/lib/metadata';
 
export default async function Page({
  params,
}: {
  params: { lang: string; slug?: string[] };
}) {
  const page = source.getPage(params.slug, params.lang);
  if (!page) notFound();
 
  const MDX = page.data.body;
 
  return (
    <DocsPage toc={page.data.toc}>
      <DocsTitle>{page.data.title}</DocsTitle>
      <DocsDescription>{page.data.description}</DocsDescription>
      <DocsBody>
        <MDX components={{ ...defaultMdxComponents }} />
      </DocsBody>
    </DocsPage>
  );
}
 
export async function generateStaticParams() {
  return source.generateParams();
}
 
export function generateMetadata({
  params,
}: {
  params: { lang: string; slug?: string[] };
}) {
  const page = source.getPage(params.slug, params.lang);
  if (!page) notFound();
 
  return withImage(page.slugs, {
    title: page.data.title,
    description: page.data.description,
  });
}

Writing Documents

see Page Conventions to learn how to organize your documents.

Search

Configure i18n on your search solution.

For Flexsearch, you don't need further changes if you're using the createFromSource shortcut. See Search I18n.

Adding Translations

We only provide English translation by default, you have to pass your translations to the provider.

import { I18nProvider } from 'styledsea-docs-interface/i18n';
 
<I18nProvider
  locales={[
    {
      name: 'English',
      locale: 'en',
    },
    {
      name: 'Chinese',
      locale: 'cn',
    },
  ]}
  translations={
    {
      cn: {
        search: 'Translated Content',
      },
    }[locale]
  }
  // other props
/>;

To allow users changing their language, enable i18n on your layouts.

app/layout.config.tsx

import type { BaseLayoutProps } from 'styledsea-docs-interface/layouts/shared';
 
export const baseOptions: BaseLayoutProps = {
  i18n: true,
};