@tuwaio/docs-ui 0.5.7 → 0.7.0

package/README.md

@@ -13,6 +13,7 @@
 - **Logo:** `RemoteLogo` is an async React Server Component that fetches an SVG (by default the TUWA logo) and renders it as React elements, so it takes `className` and `currentColor`.
 - **Theme switch:** `ThemeSwitcher` is a light/dark switch for any theme state (for example `next-themes`).
 - **Language select:** `LocaleSwitcher` is an accessible glassmorphic select dropdown for switching languages (English, Українська, 简体中文, etc.), styled to match `ThemeSwitcher`. Features zero layout shift, Nova UI Kit animated directional chevron, collision detection with auto-flip (`placement="auto"`), multi-layout Latin typeahead navigation (independent of user OS keyboard language), and an invisible native `<select>` overlay on touch devices (`pointer: coarse`) for native mobile system pickers (iOS wheel, Android sheet). Full WCAG 2.1/2.2 AA/AAA compliance. It renders an invisible placeholder during SSR to avoid hydration shifts.
+- **Three languages (project sites):** `@tuwaio/docs-ui/nextra` and `@tuwaio/docs-ui/nextra/page` turn a Nextra site into an English, Ukrainian and Simplified Chinese site with one URL per page, as on the [docs hub](https://docs.tuwa.io). `DocsLayout` is the Nextra layout with the navbar (the language switch after the links; the theme switch stays in the Nextra sidebar and the mobile menu), the footer, the search, the table of contents, the edit, feedback and last-updated texts and the sidebar titles in the language of the reader (`docsLabels`, `localizePageMap`). `createDocsPage` creates the `[[...mdxPath]]` route: each page is prerendered in English and in the languages it is translated into, and `LocalizedPage` shows the reader's language without a request; pages without a translation (package READMEs, the generated API reference) show English with a note in the reader's language. The language is detected after mount (`tuwa-locale`, then the browser languages and the time zone; no cookie, no request). The `tuwa-docs-i18n-check` command keeps the translations in line with their English pages.
 - **Interface settings for 30 days:** `PreferenceExpiry` is an inline script for the `<head>` of a site's root layout. It forgets the Local Storage values of the given keys (by default `theme`) 30 days after they were written, as the [Cookie Policy](https://tuwa.io/cookie) states, and dates each later write, whatever library writes it (`next-themes`, the `Tabs` of Nextra).
 - **Decoration:** `Orb` (an animated sphere in the brand color of a TUWA project), `StarryBackground` (an animated star field on a canvas) and `NoSSR` (renders its children only on the client).
 - **Policy pages:** `policies` lists the TUWA policies (Terms, Privacy, Cookie, Refund, Security, Data Processing Addendum) with their paths and whether they are in force (`publishedPolicies`; footers use `footerPolicies`). `loadPolicy` loads the text of a policy in a language, and `PolicyDocument` renders it with the date of the version, a Download PDF button, a language switch (English, Українська) when the policy is translated, anchored sections (the same anchors in every language) and a list of sections. The texts and PDFs come from [`TuwaIO/workflows/docs`](https://github.com/TuwaIO/workflows/tree/main/docs). Code that needs only the list or `loadPolicy` (footers, sitemaps, route handlers) imports them from `@tuwaio/docs-ui/policies`, which has no React, Next.js or Nextra imports.
@@ -27,7 +28,7 @@
 pnpm add @tuwaio/docs-ui next nextra nextra-theme-docs react react-dom @heroicons/react
 ```
 
-`nextra-theme-docs` (and its peer `nextra`) is needed by `Navbar` and `Footer`, `next` by `RemoteLogo` (a Server Component that uses the `fetch` cache of Next.js) and `@heroicons/react` by `ThemeSwitcher`.
+`nextra-theme-docs` is needed by `Navbar`, `Footer` and `DocsLayout`, `nextra` by `DocsLayout`, `LocalizedPage` and `createDocsPage`, `next` by `RemoteLogo` (a Server Component that uses the `fetch` cache of Next.js) and `createDocsPage`, and `@heroicons/react` by `ThemeSwitcher`.
 
 Import the stylesheet after the Nextra theme:
 
@@ -122,6 +123,95 @@ export function PolicyLinks() {
 
 Sections have stable anchors (`/refund#how-to-request-a-refund`), so hints and FAQ answers can link to a section.
 
+### Languages of a project site
+
+A TUWA project site (Orbit, SIWX, Satellite Connect, Pulsar, SDK) in English, Ukrainian and Simplified Chinese. The root layout renders `DocsLayout` around the page and keeps the language for 30 days:
+
+```tsx
+import { PreferenceExpiry, SiteLogo } from '@tuwaio/docs-ui';
+import { DocsLayout } from '@tuwaio/docs-ui/nextra';
+import { Head } from 'nextra/components';
+import { getPageMap } from 'nextra/page-map';
+import type { ReactNode } from 'react';
+
+const logo = <SiteLogo width={126} height={40} />;
+
+export default async function RootLayout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en" dir="ltr" suppressHydrationWarning>
+      <Head>
+        <PreferenceExpiry keys={['theme', 'tuwa-locale']} />
+      </Head>
+      <body>
+        <DocsLayout
+          logo={logo}
+          pageMap={await getPageMap()}
+          docsRepositoryBase="https://github.com/TuwaIO/pulsar-core/tree/main/apps/docs"
+          sidebarTitles={{ uk: { 'EVM Trackers Standalone': 'EVM-трекери окремо' } }}
+        >
+          {children}
+        </DocsLayout>
+      </body>
+    </html>
+  );
+}
+```
+
+`src/app/[[...mdxPath]]/page.tsx` renders every page of `src/content` with its translations:
+
+```tsx
+import { createDocsPage } from '@tuwaio/docs-ui/nextra/page';
+
+import { localizedPages } from '@/i18n/pages';
+
+const { generateStaticParams, generateMetadata, Page } = createDocsPage({ localizedPages });
+
+export { generateMetadata, generateStaticParams };
+export default Page;
+```
+
+The translations are MDX files with the path of their English page under `src/i18n/<language>` (`src/i18n/uk/index.mdx` translates `src/content/index.mdx`), listed by route in `src/i18n/pages.ts`:
+
+```ts
+import type { LocalizedPageLoaders } from '@tuwaio/docs-ui/nextra/page';
+
+export const localizedPages: Record<string, LocalizedPageLoaders> = {
+  '/': {
+    uk: () => import('./uk/index.mdx'),
+    'zh-CN': () => import('./zh-CN/index.mdx'),
+  },
+};
+```
+
+TypeScript types the imported MDX files with a declaration next to it (`src/i18n/mdx.d.ts`):
+
+```ts
+declare module '*.mdx' {
+  import type { EvaluateResult } from 'nextra';
+
+  const MDXContent: EvaluateResult['default'];
+  export default MDXContent;
+  export const toc: EvaluateResult['toc'];
+  export const metadata: EvaluateResult['metadata'];
+  export const sourceCode: EvaluateResult['sourceCode'];
+}
+```
+
+A translation keeps the structure of its English page: the same code blocks in the same order, the same heading levels with the English heading ids written as `## Встановлення [#-installation]` (so anchors work in every language) and the same links. `tuwa-docs-i18n-check`, run from the docs app, checks it and that every translated page exists in every language (it gives headings their ids with the `github-slugger` of the site's `nextra` and fails when that cannot be loaded); add it to the build and to the pre-commit hook:
+
+```json
+{
+  "scripts": {
+    "build": "tuwa-docs-i18n-check && next build && pnpm postbuild",
+    "i18n:check": "tuwa-docs-i18n-check"
+  }
+}
+```
+
+Client components inside `DocsLayout` read the language and the interface texts with `useDocsI18n()`.
+
+`NextraDocsLayout` is the same layout without state: the language, its texts (`docsLabels[locale]`) and the page map come from props. The docs hub renders it with its own dictionaries and translates its sidebar by route with `localizePageMap(pageMap, {}, { routes })`.
+
 ### Search index
 
 Run the command after `next build`. It uses the `pagefind` package of the site, so add it to the site's dependencies:
@@ -144,11 +234,11 @@ It writes the index to `public/_pagefind` (keep that directory in `.gitignore`)
 
 ## 🗄️ Browser Storage
 
-`LocaleSwitcher` and `ThemeSwitcher` store nothing; they only call `onSelect` / `onToggle`, and the site keeps the choice. `PreferenceExpiry` stores `<key>:expires` (the time in epoch milliseconds) next to each key it is given, removes both once that time has passed, and wraps `Storage.prototype.setItem` on the page to date later writes of those keys.
+`LocaleSwitcher` and `ThemeSwitcher` store nothing; they only call `onSelect` / `onToggle`, and the site keeps the choice. `DocsLayout`, `useLocaleState` and the providers of `createI18n` save the language the reader picks to `tuwa-locale` (`en`, `uk` or `zh-CN`) and read it on the next visit; list the key in `PreferenceExpiry` to forget it after 30 days. `PreferenceExpiry` stores `<key>:expires` (the time in epoch milliseconds) next to each key it is given, removes both once that time has passed, and wraps `Storage.prototype.setItem` on the page to date later writes of those keys.
 
 ## 🌐 External Services
 
-`RemoteLogo` requests its `url` on the server (by default `tuwa.io/brand/logo_v2.svg`), cached by Next.js for 24 hours. `loadPolicy` requests `raw.githubusercontent.com/TuwaIO/workflows/main/docs/<slug>.json` (a translation: `docs/<language>/<slug>.json`, and the English file when it does not exist) on the server, cached by Next.js for an hour by default. The Download PDF button of `PolicyDocument` links to the PDF on the same host; the browser requests it only when it is clicked. The other components send no requests.
+`RemoteLogo` requests its `url` on the server (by default `tuwa.io/brand/logo_v2.svg`), cached by Next.js for 24 hours. `loadPolicy` requests `raw.githubusercontent.com/TuwaIO/workflows/main/docs/<slug>.json` (a translation: `docs/<language>/<slug>.json`, and the English file when it does not exist) on the server, cached by Next.js for an hour by default. The Download PDF button of `PolicyDocument` links to the PDF on the same host; the browser requests it only when it is clicked. `createDocsPage` and `LocalizedPage` send no requests: the translations are part of the page. The other components send no requests.
 
 ---
 

package/bin/i18n-check.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+// `tuwa-docs-i18n-check`: checks the translated pages of a TUWA documentation site (src/i18n/<locale>) against their
+// English pages (src/content), run from the docs app (see README)
+import { checkSiteTranslations } from '../dist/translationCheck.js';
+
+checkSiteTranslations().then(
+  ({ files, issues }) => {
+    for (const { file, message } of issues) console.error(`${file}: ${message}`);
+    if (issues.length > 0) {
+      console.error(`Translations: ${issues.length} problem(s) in ${files} translated page(s)`);
+      process.exit(1);
+    }
+    console.log(`Translations: ${files} translated page(s) match their English pages`);
+  },
+  (error) => {
+    console.error(error instanceof Error ? error.message : error);
+    process.exit(1);
+  },
+);

package/dist/components/DocsLayout.cjs

@@ -0,0 +1,105 @@
+"use strict";
+"use client";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var DocsLayout_exports = {};
+__export(DocsLayout_exports, {
+  DocsLayout: () => DocsLayout,
+  NextraDocsLayout: () => NextraDocsLayout
+});
+module.exports = __toCommonJS(DocsLayout_exports);
+var import_jsx_runtime = require("react/jsx-runtime");
+var import_components = require("nextra/components");
+var import_nextra_theme_docs = require("nextra-theme-docs");
+var import_react = require("react");
+var import_docsI18n = require("../docsI18n");
+var import_locale = require("../locale");
+var import_pageMap = require("../pageMap");
+var import_Footer = require("./Footer");
+var import_LocaleSwitcher = require("./LocaleSwitcher");
+var import_NavBar = require("./NavBar");
+function NextraDocsLayout({
+  logo,
+  links,
+  footerLinks,
+  pageMap,
+  docsRepositoryBase,
+  locale,
+  onLocaleChange,
+  labels,
+  sidebar,
+  children
+}) {
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+    import_nextra_theme_docs.Layout,
+    {
+      navbar: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_NavBar.Navbar, { logo, links, children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+        import_LocaleSwitcher.LocaleSwitcher,
+        {
+          locale,
+          onSelect: (code) => {
+            const picked = (0, import_locale.normalizeLocale)(code);
+            if (picked) onLocaleChange(picked);
+          },
+          ariaLabel: labels.selectLanguage
+        }
+      ) }),
+      footer: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_Footer.Footer, { logo, links: footerLinks, labels: labels.footer, policyLanguage: (0, import_locale.policyLanguageOf)(locale) }),
+      pageMap,
+      docsRepositoryBase,
+      navigation: { prev: true, next: true },
+      ...sidebar && { sidebar },
+      editLink: labels.nextra.editThisPage,
+      feedback: { content: labels.nextra.feedback },
+      lastUpdated: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_nextra_theme_docs.LastUpdated, { locale, children: labels.nextra.lastUpdated }),
+      toc: { title: labels.nextra.onThisPage, backToTop: labels.nextra.scrollToTop },
+      themeSwitch: {
+        light: labels.nextra.themeLight,
+        dark: labels.nextra.themeDark,
+        system: labels.nextra.themeSystem
+      },
+      search: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+        import_components.Search,
+        {
+          placeholder: labels.nextra.searchPlaceholder,
+          emptyResult: labels.nextra.searchEmpty,
+          errorText: labels.nextra.searchError,
+          loading: labels.nextra.searchLoading
+        }
+      ),
+      children
+    }
+  );
+}
+function LocalizedLayout({ pageMap, sidebarTitles, ...props }) {
+  const { locale, setLocale, t } = (0, import_docsI18n.useDocsI18n)();
+  const siteTitles = locale === "en" ? void 0 : sidebarTitles?.[locale];
+  const localizedPageMap = (0, import_react.useMemo)(
+    () => (0, import_pageMap.localizePageMap)(pageMap, { ...t.sidebar, ...siteTitles }),
+    [pageMap, t.sidebar, siteTitles]
+  );
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(NextraDocsLayout, { ...props, pageMap: localizedPageMap, locale, onLocaleChange: setLocale, labels: t });
+}
+function DocsLayout({ initialLocale, ...props }) {
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_docsI18n.DocsI18nProvider, { initialLocale, children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(LocalizedLayout, { ...props }) });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DocsLayout,
+  NextraDocsLayout
+});

package/dist/components/DocsLayout.d.cts

@@ -0,0 +1,93 @@
+import * as react from 'react';
+import { ReactNode, ComponentProps } from 'react';
+import { PageMapItem } from 'nextra';
+import { Layout } from 'nextra-theme-docs';
+import { DocsLabels } from '../docsLabels.cjs';
+import { TuwaLocale } from '../locale.cjs';
+import { SocialLink } from './NavBar.cjs';
+import '../policies.cjs';
+
+/**
+ * Props of {@link DocsLayout}.
+ */
+interface DocsLayoutProps {
+    /** Logo of the site, for example `SiteLogo`; rendered in the navbar and the footer. */
+    logo: ReactNode;
+    /** External links of the navbar (default: `baseNavLinks`). */
+    links?: SocialLink[];
+    /** External links of the footer (default: `baseFooterLinks`). */
+    footerLinks?: SocialLink[];
+    /** The page map of the site, the result of `getPageMap()` of `nextra/page-map`. */
+    pageMap: PageMapItem[];
+    /** URL of the docs app in the repository, for the edit links (`https://github.com/TuwaIO/<repo>/tree/main/apps/docs`). */
+    docsRepositoryBase: string;
+    /**
+     * Sidebar titles of the site's own pages, by language and English title (for example `{ uk: { 'EVM Trackers
+     * Standalone': '…' } }`). `Introduction`, `Packages`, `Guides` and `Overview` are translated already.
+     */
+    sidebarTitles?: Partial<Record<Exclude<TuwaLocale, 'en'>, Record<string, string>>>;
+    /** Fixed language (tests, previews): detection and the stored choice are skipped. */
+    initialLocale?: TuwaLocale;
+    /** The page and anything rendered next to it, such as a top loading bar. */
+    children: ReactNode;
+}
+/**
+ * Props of {@link NextraDocsLayout}.
+ */
+interface NextraDocsLayoutProps {
+    /** Logo of the site, for example `SiteLogo`; rendered in the navbar and the footer. */
+    logo: ReactNode;
+    /** External links of the navbar (default: `baseNavLinks`). */
+    links?: SocialLink[];
+    /** External links of the footer (default: `baseFooterLinks`). */
+    footerLinks?: SocialLink[];
+    /** The page map, already in the language of the reader (`localizePageMap`); passed to Nextra as it is. */
+    pageMap: PageMapItem[];
+    /** URL of the docs app in the repository, for the edit links. */
+    docsRepositoryBase: string;
+    /** The language of the reader, shown in the language switch and used for the dates and the policy links. */
+    locale: TuwaLocale;
+    /**
+     * Called with the language the reader picks in the switch.
+     *
+     * @param locale - The picked language.
+     */
+    onLocaleChange: (locale: TuwaLocale) => void;
+    /** The interface texts of that language, `docsLabels[locale]`. */
+    labels: DocsLabels;
+    /** Options of the Nextra sidebar (the `sidebar` prop of its `Layout`), for example `{ defaultMenuCollapseLevel: 1 }`. */
+    sidebar?: ComponentProps<typeof Layout>['sidebar'];
+    /** The page and anything rendered next to it. */
+    children: ReactNode;
+}
+/**
+ * The Nextra `Layout` of a TUWA documentation site in a given language: the docs-ui {@link Navbar} with the language
+ * switch after the links (the theme switch stays in the Nextra sidebar and the mobile menu), the {@link Footer}, the
+ * search, the table of contents, the edit, feedback and last-updated texts and the theme switch options from
+ * `labels`. It keeps no state: {@link DocsLayout} renders it with the language of its provider, and the docs hub with
+ * its own dictionaries, so every site words and wires its chrome the same way.
+ *
+ * @param props - See {@link NextraDocsLayoutProps}.
+ * @returns The layout.
+ */
+declare function NextraDocsLayout({ logo, links, footerLinks, pageMap, docsRepositoryBase, locale, onLocaleChange, labels, sidebar, children, }: NextraDocsLayoutProps): react.JSX.Element;
+/**
+ * The layout of a TUWA project documentation site in three languages (English, Ukrainian, Simplified Chinese):
+ * {@link NextraDocsLayout} (the Nextra `Layout` with the docs-ui {@link Navbar}, the language switch after the links,
+ * the theme switch in the Nextra sidebar and the mobile menu, the {@link Footer}, the search, the table of contents,
+ * the edit, feedback and last-updated texts) and the sidebar titles in the language of the reader. Render it in the
+ * `<body>` of the root layout, around the page; pages rendered with `createDocsPage` (`@tuwaio/docs-ui/nextra/page`)
+ * switch to their translation.
+ *
+ * The URL never changes with the language. The server renders English; after mount the language is read from
+ * `tuwa-locale` in Local Storage, then the browser languages and the time zone (no cookie, no request), and a pick in
+ * the switch is saved to `tuwa-locale` (add the key to `PreferenceExpiry`, so it is forgotten after 30 days) and sets
+ * `<html lang>`.
+ *
+ * @param props - See {@link DocsLayoutProps}.
+ * @returns The layout.
+ */
+declare function DocsLayout({ initialLocale, ...props }: DocsLayoutProps): react.JSX.Element;
+
+export { DocsLayout, NextraDocsLayout };
+export type { DocsLayoutProps, NextraDocsLayoutProps };

package/dist/components/DocsLayout.d.ts

@@ -0,0 +1,93 @@
+import * as react from 'react';
+import { ReactNode, ComponentProps } from 'react';
+import { PageMapItem } from 'nextra';
+import { Layout } from 'nextra-theme-docs';
+import { DocsLabels } from '../docsLabels.js';
+import { TuwaLocale } from '../locale.js';
+import { SocialLink } from './NavBar.js';
+import '../policies.js';
+
+/**
+ * Props of {@link DocsLayout}.
+ */
+interface DocsLayoutProps {
+    /** Logo of the site, for example `SiteLogo`; rendered in the navbar and the footer. */
+    logo: ReactNode;
+    /** External links of the navbar (default: `baseNavLinks`). */
+    links?: SocialLink[];
+    /** External links of the footer (default: `baseFooterLinks`). */
+    footerLinks?: SocialLink[];
+    /** The page map of the site, the result of `getPageMap()` of `nextra/page-map`. */
+    pageMap: PageMapItem[];
+    /** URL of the docs app in the repository, for the edit links (`https://github.com/TuwaIO/<repo>/tree/main/apps/docs`). */
+    docsRepositoryBase: string;
+    /**
+     * Sidebar titles of the site's own pages, by language and English title (for example `{ uk: { 'EVM Trackers
+     * Standalone': '…' } }`). `Introduction`, `Packages`, `Guides` and `Overview` are translated already.
+     */
+    sidebarTitles?: Partial<Record<Exclude<TuwaLocale, 'en'>, Record<string, string>>>;
+    /** Fixed language (tests, previews): detection and the stored choice are skipped. */
+    initialLocale?: TuwaLocale;
+    /** The page and anything rendered next to it, such as a top loading bar. */
+    children: ReactNode;
+}
+/**
+ * Props of {@link NextraDocsLayout}.
+ */
+interface NextraDocsLayoutProps {
+    /** Logo of the site, for example `SiteLogo`; rendered in the navbar and the footer. */
+    logo: ReactNode;
+    /** External links of the navbar (default: `baseNavLinks`). */
+    links?: SocialLink[];
+    /** External links of the footer (default: `baseFooterLinks`). */
+    footerLinks?: SocialLink[];
+    /** The page map, already in the language of the reader (`localizePageMap`); passed to Nextra as it is. */
+    pageMap: PageMapItem[];
+    /** URL of the docs app in the repository, for the edit links. */
+    docsRepositoryBase: string;
+    /** The language of the reader, shown in the language switch and used for the dates and the policy links. */
+    locale: TuwaLocale;
+    /**
+     * Called with the language the reader picks in the switch.
+     *
+     * @param locale - The picked language.
+     */
+    onLocaleChange: (locale: TuwaLocale) => void;
+    /** The interface texts of that language, `docsLabels[locale]`. */
+    labels: DocsLabels;
+    /** Options of the Nextra sidebar (the `sidebar` prop of its `Layout`), for example `{ defaultMenuCollapseLevel: 1 }`. */
+    sidebar?: ComponentProps<typeof Layout>['sidebar'];
+    /** The page and anything rendered next to it. */
+    children: ReactNode;
+}
+/**
+ * The Nextra `Layout` of a TUWA documentation site in a given language: the docs-ui {@link Navbar} with the language
+ * switch after the links (the theme switch stays in the Nextra sidebar and the mobile menu), the {@link Footer}, the
+ * search, the table of contents, the edit, feedback and last-updated texts and the theme switch options from
+ * `labels`. It keeps no state: {@link DocsLayout} renders it with the language of its provider, and the docs hub with
+ * its own dictionaries, so every site words and wires its chrome the same way.
+ *
+ * @param props - See {@link NextraDocsLayoutProps}.
+ * @returns The layout.
+ */
+declare function NextraDocsLayout({ logo, links, footerLinks, pageMap, docsRepositoryBase, locale, onLocaleChange, labels, sidebar, children, }: NextraDocsLayoutProps): react.JSX.Element;
+/**
+ * The layout of a TUWA project documentation site in three languages (English, Ukrainian, Simplified Chinese):
+ * {@link NextraDocsLayout} (the Nextra `Layout` with the docs-ui {@link Navbar}, the language switch after the links,
+ * the theme switch in the Nextra sidebar and the mobile menu, the {@link Footer}, the search, the table of contents,
+ * the edit, feedback and last-updated texts) and the sidebar titles in the language of the reader. Render it in the
+ * `<body>` of the root layout, around the page; pages rendered with `createDocsPage` (`@tuwaio/docs-ui/nextra/page`)
+ * switch to their translation.
+ *
+ * The URL never changes with the language. The server renders English; after mount the language is read from
+ * `tuwa-locale` in Local Storage, then the browser languages and the time zone (no cookie, no request), and a pick in
+ * the switch is saved to `tuwa-locale` (add the key to `PreferenceExpiry`, so it is forgotten after 30 days) and sets
+ * `<html lang>`.
+ *
+ * @param props - See {@link DocsLayoutProps}.
+ * @returns The layout.
+ */
+declare function DocsLayout({ initialLocale, ...props }: DocsLayoutProps): react.JSX.Element;
+
+export { DocsLayout, NextraDocsLayout };
+export type { DocsLayoutProps, NextraDocsLayoutProps };

package/dist/components/DocsLayout.js

@@ -0,0 +1,80 @@
+"use client";
+import { jsx } from "react/jsx-runtime";
+import { Search } from "nextra/components";
+import { LastUpdated, Layout } from "nextra-theme-docs";
+import { useMemo } from "react";
+import { DocsI18nProvider, useDocsI18n } from "../docsI18n";
+import { normalizeLocale, policyLanguageOf } from "../locale";
+import { localizePageMap } from "../pageMap";
+import { Footer } from "./Footer";
+import { LocaleSwitcher } from "./LocaleSwitcher";
+import { Navbar } from "./NavBar";
+function NextraDocsLayout({
+  logo,
+  links,
+  footerLinks,
+  pageMap,
+  docsRepositoryBase,
+  locale,
+  onLocaleChange,
+  labels,
+  sidebar,
+  children
+}) {
+  return /* @__PURE__ */ jsx(
+    Layout,
+    {
+      navbar: /* @__PURE__ */ jsx(Navbar, { logo, links, children: /* @__PURE__ */ jsx(
+        LocaleSwitcher,
+        {
+          locale,
+          onSelect: (code) => {
+            const picked = normalizeLocale(code);
+            if (picked) onLocaleChange(picked);
+          },
+          ariaLabel: labels.selectLanguage
+        }
+      ) }),
+      footer: /* @__PURE__ */ jsx(Footer, { logo, links: footerLinks, labels: labels.footer, policyLanguage: policyLanguageOf(locale) }),
+      pageMap,
+      docsRepositoryBase,
+      navigation: { prev: true, next: true },
+      ...sidebar && { sidebar },
+      editLink: labels.nextra.editThisPage,
+      feedback: { content: labels.nextra.feedback },
+      lastUpdated: /* @__PURE__ */ jsx(LastUpdated, { locale, children: labels.nextra.lastUpdated }),
+      toc: { title: labels.nextra.onThisPage, backToTop: labels.nextra.scrollToTop },
+      themeSwitch: {
+        light: labels.nextra.themeLight,
+        dark: labels.nextra.themeDark,
+        system: labels.nextra.themeSystem
+      },
+      search: /* @__PURE__ */ jsx(
+        Search,
+        {
+          placeholder: labels.nextra.searchPlaceholder,
+          emptyResult: labels.nextra.searchEmpty,
+          errorText: labels.nextra.searchError,
+          loading: labels.nextra.searchLoading
+        }
+      ),
+      children
+    }
+  );
+}
+function LocalizedLayout({ pageMap, sidebarTitles, ...props }) {
+  const { locale, setLocale, t } = useDocsI18n();
+  const siteTitles = locale === "en" ? void 0 : sidebarTitles?.[locale];
+  const localizedPageMap = useMemo(
+    () => localizePageMap(pageMap, { ...t.sidebar, ...siteTitles }),
+    [pageMap, t.sidebar, siteTitles]
+  );
+  return /* @__PURE__ */ jsx(NextraDocsLayout, { ...props, pageMap: localizedPageMap, locale, onLocaleChange: setLocale, labels: t });
+}
+function DocsLayout({ initialLocale, ...props }) {
+  return /* @__PURE__ */ jsx(DocsI18nProvider, { initialLocale, children: /* @__PURE__ */ jsx(LocalizedLayout, { ...props }) });
+}
+export {
+  DocsLayout,
+  NextraDocsLayout
+};

package/dist/components/Footer.cjs

@@ -82,12 +82,7 @@ function Footer({ links, logo, labels, policyLanguage = "en" }) {
           }
         )
       ] }),
-      /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { className: "tuwadocs:flex tuwadocs:flex-wrap tuwadocs:items-center tuwadocs:justify-center tuwadocs:gap-3 tuwadocs:mt-4 tuwadocs:pt-4 tuwa-footer-border", children: /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { className: "tuwa-footer-copyright", children: [
-        "\xA9 2025 - ",
-        (/* @__PURE__ */ new Date()).getFullYear(),
-        " TUWA. ",
-        labels?.copyright ?? "All rights reserved."
-      ] }) })
+      /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { className: "tuwadocs:flex tuwadocs:flex-wrap tuwadocs:items-center tuwadocs:justify-center tuwadocs:gap-3 tuwadocs:mt-4 tuwadocs:pt-4 tuwa-footer-border", children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { className: "tuwa-footer-copyright", suppressHydrationWarning: true, children: `\xA9 2025 - ${(/* @__PURE__ */ new Date()).getFullYear()} TUWA. ${labels?.copyright ?? "All rights reserved."}` }) })
     ] })
   ] }) });
 }

package/dist/components/Footer.d.cts

@@ -31,8 +31,9 @@ interface FooterProps extends NavProps {
 /**
  * The footer of a TUWA documentation site: the `Footer` of `nextra-theme-docs` with the logo, external links, the
  * TUWA description and the license on the left, links to the policies in force on tuwa.io (`footerPolicies`) and to
- * the list of all policies on the docs hub on the right, and the copyright line (the current year is read on render)
- * centered below; on narrow screens everything is centered. Render it in the `footer` prop of the Nextra `Layout`.
+ * the list of all policies on the docs hub on the right, and the copyright line (the current year is read on render;
+ * while a prerendered page hydrates, the year of its HTML stays without a hydration error) centered below; on narrow
+ * screens everything is centered. Render it in the `footer` prop of the Nextra `Layout`.
  *
  * @param props - See {@link FooterProps}.
  * @returns The footer.

package/dist/components/Footer.d.ts

@@ -31,8 +31,9 @@ interface FooterProps extends NavProps {
 /**
  * The footer of a TUWA documentation site: the `Footer` of `nextra-theme-docs` with the logo, external links, the
  * TUWA description and the license on the left, links to the policies in force on tuwa.io (`footerPolicies`) and to
- * the list of all policies on the docs hub on the right, and the copyright line (the current year is read on render)
- * centered below; on narrow screens everything is centered. Render it in the `footer` prop of the Nextra `Layout`.
+ * the list of all policies on the docs hub on the right, and the copyright line (the current year is read on render;
+ * while a prerendered page hydrates, the year of its HTML stays without a hydration error) centered below; on narrow
+ * screens everything is centered. Render it in the `footer` prop of the Nextra `Layout`.
  *
  * @param props - See {@link FooterProps}.
  * @returns The footer.

package/dist/components/Footer.js

@@ -63,12 +63,7 @@ function Footer({ links, logo, labels, policyLanguage = "en" }) {
           }
         )
       ] }),
-      /* @__PURE__ */ jsx("div", { className: "tuwadocs:flex tuwadocs:flex-wrap tuwadocs:items-center tuwadocs:justify-center tuwadocs:gap-3 tuwadocs:mt-4 tuwadocs:pt-4 tuwa-footer-border", children: /* @__PURE__ */ jsxs("div", { className: "tuwa-footer-copyright", children: [
-        "\xA9 2025 - ",
-        (/* @__PURE__ */ new Date()).getFullYear(),
-        " TUWA. ",
-        labels?.copyright ?? "All rights reserved."
-      ] }) })
+      /* @__PURE__ */ jsx("div", { className: "tuwadocs:flex tuwadocs:flex-wrap tuwadocs:items-center tuwadocs:justify-center tuwadocs:gap-3 tuwadocs:mt-4 tuwadocs:pt-4 tuwa-footer-border", children: /* @__PURE__ */ jsx("div", { className: "tuwa-footer-copyright", suppressHydrationWarning: true, children: `\xA9 2025 - ${(/* @__PURE__ */ new Date()).getFullYear()} TUWA. ${labels?.copyright ?? "All rights reserved."}` }) })
     ] })
   ] }) });
 }

package/dist/components/LocalizedPage.cjs

@@ -0,0 +1,42 @@
+"use strict";
+"use client";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var LocalizedPage_exports = {};
+__export(LocalizedPage_exports, {
+  LocalizedPage: () => LocalizedPage
+});
+module.exports = __toCommonJS(LocalizedPage_exports);
+var import_jsx_runtime = require("react/jsx-runtime");
+var import_components = require("nextra/components");
+var import_nextra_theme_docs = require("nextra-theme-docs");
+var import_docsI18n = require("../docsI18n");
+function LocalizedPage({ variants }) {
+  const { locale, t } = (0, import_docsI18n.useDocsI18n)();
+  const Wrapper = (0, import_nextra_theme_docs.useMDXComponents)().wrapper;
+  const translated = variants[locale];
+  const page = translated ?? variants.en;
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(Wrapper, { toc: page.toc, metadata: page.metadata, sourceCode: page.sourceCode, children: [
+    !translated && /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { className: "tuwadocs:clear-both", children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_components.Callout, { type: "info", children: t.englishOnly }) }),
+    page.content
+  ] });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  LocalizedPage
+});