@tuwaio/docs-ui 0.5.7 → 0.6.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,93 @@ 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; 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()`.
+
 ### 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 +232,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,82 @@
+"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
+});
+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 LocalizedLayout({
+  logo,
+  links,
+  footerLinks,
+  pageMap,
+  docsRepositoryBase,
+  sidebarTitles,
+  children
+}) {
+  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)(
+    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: setLocale, ariaLabel: t.selectLanguage }) }),
+      footer: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_Footer.Footer, { logo, links: footerLinks, labels: t.footer, policyLanguage: (0, import_locale.policyLanguageOf)(locale) }),
+      pageMap: localizedPageMap,
+      docsRepositoryBase,
+      navigation: { prev: true, next: true },
+      editLink: t.nextra.editThisPage,
+      feedback: { content: t.nextra.feedback },
+      lastUpdated: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_nextra_theme_docs.LastUpdated, { locale, children: t.nextra.lastUpdated }),
+      toc: { title: t.nextra.onThisPage, backToTop: t.nextra.scrollToTop },
+      themeSwitch: { light: t.nextra.themeLight, dark: t.nextra.themeDark, system: t.nextra.themeSystem },
+      search: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+        import_components.Search,
+        {
+          placeholder: t.nextra.searchPlaceholder,
+          emptyResult: t.nextra.searchEmpty,
+          errorText: t.nextra.searchError,
+          loading: t.nextra.searchLoading
+        }
+      ),
+      children
+    }
+  );
+}
+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
+});

package/dist/components/DocsLayout.d.cts

@@ -0,0 +1,50 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { PageMapItem } from 'nextra';
+import { TuwaLocale } from '../locale.cjs';
+import { SocialLink } from './NavBar.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;
+}
+/**
+ * The layout of a TUWA project documentation site in three languages (English, Ukrainian, Simplified Chinese): the
+ * Nextra `Layout` with the docs-ui {@link Navbar} (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 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 };
+export type { DocsLayoutProps };

package/dist/components/DocsLayout.d.ts

@@ -0,0 +1,50 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { PageMapItem } from 'nextra';
+import { TuwaLocale } from '../locale.js';
+import { SocialLink } from './NavBar.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;
+}
+/**
+ * The layout of a TUWA project documentation site in three languages (English, Ukrainian, Simplified Chinese): the
+ * Nextra `Layout` with the docs-ui {@link Navbar} (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 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 };
+export type { DocsLayoutProps };

package/dist/components/DocsLayout.js

@@ -0,0 +1,58 @@
+"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 { policyLanguageOf } from "../locale";
+import { localizePageMap } from "../pageMap";
+import { Footer } from "./Footer";
+import { LocaleSwitcher } from "./LocaleSwitcher";
+import { Navbar } from "./NavBar";
+function LocalizedLayout({
+  logo,
+  links,
+  footerLinks,
+  pageMap,
+  docsRepositoryBase,
+  sidebarTitles,
+  children
+}) {
+  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(
+    Layout,
+    {
+      navbar: /* @__PURE__ */ jsx(Navbar, { logo, links, children: /* @__PURE__ */ jsx(LocaleSwitcher, { locale, onSelect: setLocale, ariaLabel: t.selectLanguage }) }),
+      footer: /* @__PURE__ */ jsx(Footer, { logo, links: footerLinks, labels: t.footer, policyLanguage: policyLanguageOf(locale) }),
+      pageMap: localizedPageMap,
+      docsRepositoryBase,
+      navigation: { prev: true, next: true },
+      editLink: t.nextra.editThisPage,
+      feedback: { content: t.nextra.feedback },
+      lastUpdated: /* @__PURE__ */ jsx(LastUpdated, { locale, children: t.nextra.lastUpdated }),
+      toc: { title: t.nextra.onThisPage, backToTop: t.nextra.scrollToTop },
+      themeSwitch: { light: t.nextra.themeLight, dark: t.nextra.themeDark, system: t.nextra.themeSystem },
+      search: /* @__PURE__ */ jsx(
+        Search,
+        {
+          placeholder: t.nextra.searchPlaceholder,
+          emptyResult: t.nextra.searchEmpty,
+          errorText: t.nextra.searchError,
+          loading: t.nextra.searchLoading
+        }
+      ),
+      children
+    }
+  );
+}
+function DocsLayout({ initialLocale, ...props }) {
+  return /* @__PURE__ */ jsx(DocsI18nProvider, { initialLocale, children: /* @__PURE__ */ jsx(LocalizedLayout, { ...props }) });
+}
+export {
+  DocsLayout
+};

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
+});

package/dist/components/LocalizedPage.d.cts

@@ -0,0 +1,37 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { Heading, $NextraMetadata } from 'nextra';
+import { TuwaLocale } from '../locale.cjs';
+
+/** One language of a page: the rendered MDX and what the Nextra page wrapper needs. */
+interface LocalizedPageVariant {
+    /** The rendered MDX content. */
+    content: ReactNode;
+    /** The table of contents of the MDX file (its `toc` export). */
+    toc: Heading[];
+    /** The metadata of the MDX file (its `metadata` export): the title, the file of the edit link, the last change. */
+    metadata: $NextraMetadata;
+    /** The source of the MDX file (its `sourceCode` export), for the copy-page button. */
+    sourceCode?: string;
+}
+/** Props of {@link LocalizedPage}. */
+interface LocalizedPageProps {
+    /** The page in English (the server renders it) and in the languages it is translated into. */
+    variants: Partial<Record<TuwaLocale, LocalizedPageVariant>> & {
+        en: LocalizedPageVariant;
+    };
+}
+/**
+ * A page of a TUWA documentation site in the language of the reader, inside the Nextra page wrapper (sidebar, table of
+ * contents, breadcrumbs, pagination). All variants come prerendered from the server, so switching the language makes no
+ * request and the URL stays the same; the server HTML and the search index hold English. A page without a translation
+ * in the active language (package READMEs and the generated API reference) shows English with a short note in that
+ * language. Must be rendered inside {@link DocsLayout}; `createDocsPage` (`@tuwaio/docs-ui/nextra/page`) renders it.
+ *
+ * @param props - See {@link LocalizedPageProps}.
+ * @returns The page.
+ */
+declare function LocalizedPage({ variants }: LocalizedPageProps): react.JSX.Element;
+
+export { LocalizedPage };
+export type { LocalizedPageProps, LocalizedPageVariant };

package/dist/components/LocalizedPage.d.ts

@@ -0,0 +1,37 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { Heading, $NextraMetadata } from 'nextra';
+import { TuwaLocale } from '../locale.js';
+
+/** One language of a page: the rendered MDX and what the Nextra page wrapper needs. */
+interface LocalizedPageVariant {
+    /** The rendered MDX content. */
+    content: ReactNode;
+    /** The table of contents of the MDX file (its `toc` export). */
+    toc: Heading[];
+    /** The metadata of the MDX file (its `metadata` export): the title, the file of the edit link, the last change. */
+    metadata: $NextraMetadata;
+    /** The source of the MDX file (its `sourceCode` export), for the copy-page button. */
+    sourceCode?: string;
+}
+/** Props of {@link LocalizedPage}. */
+interface LocalizedPageProps {
+    /** The page in English (the server renders it) and in the languages it is translated into. */
+    variants: Partial<Record<TuwaLocale, LocalizedPageVariant>> & {
+        en: LocalizedPageVariant;
+    };
+}
+/**
+ * A page of a TUWA documentation site in the language of the reader, inside the Nextra page wrapper (sidebar, table of
+ * contents, breadcrumbs, pagination). All variants come prerendered from the server, so switching the language makes no
+ * request and the URL stays the same; the server HTML and the search index hold English. A page without a translation
+ * in the active language (package READMEs and the generated API reference) shows English with a short note in that
+ * language. Must be rendered inside {@link DocsLayout}; `createDocsPage` (`@tuwaio/docs-ui/nextra/page`) renders it.
+ *
+ * @param props - See {@link LocalizedPageProps}.
+ * @returns The page.
+ */
+declare function LocalizedPage({ variants }: LocalizedPageProps): react.JSX.Element;
+
+export { LocalizedPage };
+export type { LocalizedPageProps, LocalizedPageVariant };

package/dist/components/LocalizedPage.js

@@ -0,0 +1,18 @@
+"use client";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { Callout } from "nextra/components";
+import { useMDXComponents } from "nextra-theme-docs";
+import { useDocsI18n } from "../docsI18n";
+function LocalizedPage({ variants }) {
+  const { locale, t } = useDocsI18n();
+  const Wrapper = useMDXComponents().wrapper;
+  const translated = variants[locale];
+  const page = translated ?? variants.en;
+  return /* @__PURE__ */ jsxs(Wrapper, { toc: page.toc, metadata: page.metadata, sourceCode: page.sourceCode, children: [
+    !translated && /* @__PURE__ */ jsx("div", { className: "tuwadocs:clear-both", children: /* @__PURE__ */ jsx(Callout, { type: "info", children: t.englishOnly }) }),
+    page.content
+  ] });
+}
+export {
+  LocalizedPage
+};

package/dist/docsI18n.cjs

@@ -0,0 +1,33 @@
+"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 docsI18n_exports = {};
+__export(docsI18n_exports, {
+  DocsI18nProvider: () => DocsI18nProvider,
+  useDocsI18n: () => useDocsI18n
+});
+module.exports = __toCommonJS(docsI18n_exports);
+var import_docsLabels = require("./docsLabels");
+var import_i18n = require("./i18n");
+const { I18nProvider: DocsI18nProvider, useI18n: useDocsI18n } = (0, import_i18n.createI18n)(import_docsLabels.docsLabels);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DocsI18nProvider,
+  useDocsI18n
+});

package/dist/docsI18n.d.cts

@@ -0,0 +1,16 @@
+import { DocsLabels } from './docsLabels.cjs';
+import * as react from 'react';
+import { I18nProviderProps, I18nContextValue } from './i18n.cjs';
+import './locale.cjs';
+import './policies.cjs';
+
+/**
+ * The i18n kit of the TUWA documentation sites, on {@link docsLabels}: `DocsI18nProvider` provides the language of the
+ * reader and the interface texts, `useDocsI18n` reads them (outside the provider: English and a no-op setter).
+ * `DocsLayout` renders the provider, so a site's client components inside the layout call `useDocsI18n` directly.
+ * The language is detected after mount and kept under `tuwa-locale` in Local Storage (list it in `PreferenceExpiry`).
+ */
+declare const DocsI18nProvider: react.ComponentType<I18nProviderProps>;
+declare const useDocsI18n: () => I18nContextValue<DocsLabels>;
+
+export { DocsI18nProvider, useDocsI18n };

package/dist/docsI18n.d.ts

@@ -0,0 +1,16 @@
+import { DocsLabels } from './docsLabels.js';
+import * as react from 'react';
+import { I18nProviderProps, I18nContextValue } from './i18n.js';
+import './locale.js';
+import './policies.js';
+
+/**
+ * The i18n kit of the TUWA documentation sites, on {@link docsLabels}: `DocsI18nProvider` provides the language of the
+ * reader and the interface texts, `useDocsI18n` reads them (outside the provider: English and a no-op setter).
+ * `DocsLayout` renders the provider, so a site's client components inside the layout call `useDocsI18n` directly.
+ * The language is detected after mount and kept under `tuwa-locale` in Local Storage (list it in `PreferenceExpiry`).
+ */
+declare const DocsI18nProvider: react.ComponentType<I18nProviderProps>;
+declare const useDocsI18n: () => I18nContextValue<DocsLabels>;
+
+export { DocsI18nProvider, useDocsI18n };

package/dist/docsI18n.js

@@ -0,0 +1,8 @@
+"use client";
+import { docsLabels } from "./docsLabels";
+import { createI18n } from "./i18n";
+const { I18nProvider: DocsI18nProvider, useI18n: useDocsI18n } = createI18n(docsLabels);
+export {
+  DocsI18nProvider,
+  useDocsI18n
+};