React Router | Hanzo Docs

Setup

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

app/lib/i18n.ts

import { defineI18n } from '@hanzo/docs/core/i18n';

export const i18n = defineI18n({
  defaultLanguage: 'en',
  languages: ['cn', 'en'],
});

See available options for i18n config.

Routing

Add :lang prefix to all your pages.

app/routes.ts

import { route, type RouteConfig } from '@react-router/dev/routes';

export default [
  route(':lang', 'routes/home.tsx'),
  route(':lang/docs/*', 'docs/page.tsx'),
  route('api/search', 'docs/search.ts'),
] satisfies RouteConfig;

Make locale optional

You can also use :lang? prefix, and update the i18n config:

app/lib/i18n.ts

app/routes.ts

import { defineI18n } from '@hanzo/docs/core/i18n';

export const i18n = defineI18n({
  defaultLanguage: 'en',
  languages: ['cn', 'en'],
  hideLocale: 'default-locale',
});

import { route, type RouteConfig } from '@react-router/dev/routes';

export default [
  route(':lang?', 'routes/home.tsx'),
  route(':lang?/docs/*', 'docs/page.tsx'),
  route('api/search', 'docs/search.ts'),
] satisfies RouteConfig;

Pages

Provide UI translations and other config to <RootProvider />, the English translations are used as fallbacks.

app/root.tsx

import { Links, Meta, Scripts, ScrollRestoration, useParams } from 'react-router';
import { RootProvider } from '@hanzo/docs/ui/provider/base';
import { ReactRouterProvider } from '@hanzo/docs-core/framework/react-router';
import { defineI18nUI } from '@hanzo/docs-ui/i18n';
import { i18n } from '@/lib/i18n';
import './app.css';

const { provider } = defineI18nUI(i18n, {
  translations: {
    en: {
      displayName: 'English',
    },
    cn: {
      displayName: 'Chinese',
      search: '搜尋文檔',
    },
  },
});

export function Layout({ children }: { children: React.ReactNode }) {
  const { lang = i18n.defaultLanguage } = useParams();

  return (
    <html lang="en" suppressHydrationWarning>
      <head>
        <meta charSet="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <Meta />
        <Links />
      </head>
      <body className="flex flex-col min-h-screen">
        <ReactRouterProvider>
          <RootProvider
            i18n={provider(lang)}
          >
            {children}
          </RootProvider>
        </ReactRouterProvider>
        <ScrollRestoration />
        <Scripts />
      </body>
    </html>
  );
}

Pass Locale

Add locale parameter to baseOptions() and include i18n in props:

app/lib/layout.shared.tsx

import { i18n } from '@/lib/i18n';
import type { BaseLayoutProps } from '@hanzo/docs/ui/layouts/shared';

export function baseOptions(locale: string): BaseLayoutProps {
  return {
    i18n,
    // different props based on `locale`
  };
}

Pass the locale to Hanzo Docs in your pages and layouts.

app/lib/source.ts

Home Layout

Docs Page

import { i18n } from '@/lib/i18n';
import { loader } from '@hanzo/docs/core/source';

export const source = loader({
  i18n,
  // other options
});

app/routes/home.tsx

import type { Route } from './+types/home';
import { HomeLayout } from '@hanzo/docs/ui/layouts/home';
import { baseOptions } from '@/lib/layout.shared';

export default function Home({ params }: Route.ComponentProps) {
  return (
    <HomeLayout {...baseOptions(params.lang)}></HomeLayout>
  );
}

app/docs/page.tsx

import type { Route } from './+types/page';
import { DocsLayout } from '@hanzo/docs/ui/layouts/docs';
import { source } from '@/lib/source';
import type * as PageTree from '@hanzo/docs/core/page-tree';
import { baseOptions } from '@/lib/layout.shared';

export async function loader({ params }: Route.LoaderArgs) {
  const slugs = params['*'].split('/').filter((v) => v.length > 0);
  const page = source.getPage(slugs);
  const page = source.getPage(slugs, params.lang);
  if (!page) throw new Response('Not found', { status: 404 });

  return {
    path: page.path,
    tree: source.getPageTree(),
    tree: source.getPageTree(params.lang),
  };
}

export default function Page({ loaderData, params }: Route.ComponentProps) {
  const { tree, path } = loaderData;

  return (
    <DocsLayout
      {...baseOptions(params.lang)}
      tree={tree as PageTree.Root}
    ></DocsLayout>
  );
}

Search

Configure i18n on your search solution.

Built-in Search (Orama): See Internationalization.
Cloud Solutions (e.g. Algolia): They usually have official support for multilingual.

Writing Documents

See i18n routing to learn how to create pages for specific locales.

Hanzo Docs only handles navigation for its own layouts (e.g. sidebar). For other places, you can use the useParams hook to get the locale from url.

import { Link, useParams } from 'react-router';

const { lang } = useParams();

<Link to={`/${lang}/about`}>About Us</Link>;

In addition, the @hanzo/docs-core/dynamic-link component supports dynamic hrefs, you can use it to attend the locale prefix. It is useful for Markdown/MDX content.

content.mdx

import { DynamicLink } from '@hanzo/docs/core/dynamic-link';

<DynamicLink href="/[lang]/another-page">This is a link</DynamicLink>