@tuwaio/docs-ui 0.5.7 → 0.6.0

package/dist/index.cjs

@@ -42,8 +42,10 @@ __reExport(index_exports, require("./components/Orb"), module.exports);
 __reExport(index_exports, require("./components/PolicyDocument"), module.exports);
 var import_StarryBackground = __toESM(require("./components/StarryBackground"), 1);
 __reExport(index_exports, require("./components/ThemeSwitcher"), module.exports);
+__reExport(index_exports, require("./docsLabels"), module.exports);
 __reExport(index_exports, require("./i18n"), module.exports);
 __reExport(index_exports, require("./locale"), module.exports);
+__reExport(index_exports, require("./pageMap"), module.exports);
 __reExport(index_exports, require("./policies"), module.exports);
 __reExport(index_exports, require("./preferences"), module.exports);
 __reExport(index_exports, require("./utils"), module.exports);
@@ -58,8 +60,10 @@ __reExport(index_exports, require("./utils"), module.exports);
   ...require("./components/Orb"),
   ...require("./components/PolicyDocument"),
   ...require("./components/ThemeSwitcher"),
+  ...require("./docsLabels"),
   ...require("./i18n"),
   ...require("./locale"),
+  ...require("./pageMap"),
   ...require("./policies"),
   ...require("./preferences"),
   ...require("./utils")

package/dist/index.css

@@ -750,6 +750,9 @@ html {
   .tuwadocs\:z-50 {
     z-index: 50;
   }
+  .tuwadocs\:clear-both {
+    clear: both;
+  }
   .tuwadocs\:mt-1\.5 {
     margin-top: calc(var(--tuwadocs-spacing) * 1.5);
   }

package/dist/index.d.cts

@@ -7,9 +7,12 @@ export { Orb, OrbProps, PackageType } from './components/Orb.cjs';
 export { PolicyDocument, PolicyDocumentProps } from './components/PolicyDocument.cjs';
 export { default as StarryBackground } from './components/StarryBackground.cjs';
 export { ThemeSwitcher, ThemeSwitcherProps } from './components/ThemeSwitcher.cjs';
+export { DocsLabels, docsLabels } from './docsLabels.cjs';
 export { I18nContextValue, I18nKit, I18nProviderProps, LocaleState, LocaleStateOptions, LocaleVariant, createI18n, useLocaleState } from './i18n.cjs';
 export { DEFAULT_LOCALE, LOCALE_STORAGE_KEY, LocaleSignals, TUWA_LOCALES, TuwaLocale, detectLocale, formatLabel, normalizeLocale, policyLanguageOf, resolveClientLocale } from './locale.cjs';
+export { localizePageMap } from './pageMap.cjs';
 export { POLICIES_INDEX_URL, POLICY_DOCUMENT_LABELS, POLICY_LANGUAGES, POLICY_LANGUAGE_NAMES, POLICY_SITE_URL, POLICY_SOURCE, Policy, PolicyContent, PolicyDocumentLabels, PolicyLanguage, PolicySection, PolicySlug, footerPolicies, formatPolicyDate, getPolicyFileUrl, getPolicyPageUrl, loadPolicy, policies, policyLanguageFrom, publishedPolicies } from './policies.cjs';
 export { PREFERENCE_DAYS, PreferenceExpiry, expireStoredPreferences } from './preferences.cjs';
 export { baseFooterLinks, baseNavLinks } from './utils.cjs';
 import 'react';
+import 'nextra';

package/dist/index.d.ts

@@ -7,9 +7,12 @@ export { Orb, OrbProps, PackageType } from './components/Orb.js';
 export { PolicyDocument, PolicyDocumentProps } from './components/PolicyDocument.js';
 export { default as StarryBackground } from './components/StarryBackground.js';
 export { ThemeSwitcher, ThemeSwitcherProps } from './components/ThemeSwitcher.js';
+export { DocsLabels, docsLabels } from './docsLabels.js';
 export { I18nContextValue, I18nKit, I18nProviderProps, LocaleState, LocaleStateOptions, LocaleVariant, createI18n, useLocaleState } from './i18n.js';
 export { DEFAULT_LOCALE, LOCALE_STORAGE_KEY, LocaleSignals, TUWA_LOCALES, TuwaLocale, detectLocale, formatLabel, normalizeLocale, policyLanguageOf, resolveClientLocale } from './locale.js';
+export { localizePageMap } from './pageMap.js';
 export { POLICIES_INDEX_URL, POLICY_DOCUMENT_LABELS, POLICY_LANGUAGES, POLICY_LANGUAGE_NAMES, POLICY_SITE_URL, POLICY_SOURCE, Policy, PolicyContent, PolicyDocumentLabels, PolicyLanguage, PolicySection, PolicySlug, footerPolicies, formatPolicyDate, getPolicyFileUrl, getPolicyPageUrl, loadPolicy, policies, policyLanguageFrom, publishedPolicies } from './policies.js';
 export { PREFERENCE_DAYS, PreferenceExpiry, expireStoredPreferences } from './preferences.js';
 export { baseFooterLinks, baseNavLinks } from './utils.js';
 import 'react';
+import 'nextra';

package/dist/index.js

@@ -7,8 +7,10 @@ export * from "./components/Orb";
 export * from "./components/PolicyDocument";
 import { default as default3 } from "./components/StarryBackground";
 export * from "./components/ThemeSwitcher";
+export * from "./docsLabels";
 export * from "./i18n";
 export * from "./locale";
+export * from "./pageMap";
 export * from "./policies";
 export * from "./preferences";
 export * from "./utils";

package/dist/nextra.cjs

@@ -0,0 +1,26 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+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 __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default"));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var nextra_exports = {};
+module.exports = __toCommonJS(nextra_exports);
+__reExport(nextra_exports, require("./components/DocsLayout"), module.exports);
+__reExport(nextra_exports, require("./components/LocalizedPage"), module.exports);
+__reExport(nextra_exports, require("./docsI18n"), module.exports);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ...require("./components/DocsLayout"),
+  ...require("./components/LocalizedPage"),
+  ...require("./docsI18n")
+});

package/dist/nextra.d.cts

@@ -0,0 +1,10 @@
+export { DocsLayout, DocsLayoutProps } from './components/DocsLayout.cjs';
+export { LocalizedPage, LocalizedPageProps, LocalizedPageVariant } from './components/LocalizedPage.cjs';
+export { DocsI18nProvider, useDocsI18n } from './docsI18n.cjs';
+import 'react';
+import 'nextra';
+import './locale.cjs';
+import './components/NavBar.cjs';
+import './docsLabels.cjs';
+import './policies.cjs';
+import './i18n.cjs';

package/dist/nextra.d.ts

@@ -0,0 +1,10 @@
+export { DocsLayout, DocsLayoutProps } from './components/DocsLayout.js';
+export { LocalizedPage, LocalizedPageProps, LocalizedPageVariant } from './components/LocalizedPage.js';
+export { DocsI18nProvider, useDocsI18n } from './docsI18n.js';
+import 'react';
+import 'nextra';
+import './locale.js';
+import './components/NavBar.js';
+import './docsLabels.js';
+import './policies.js';
+import './i18n.js';

package/dist/nextra.js

@@ -0,0 +1,3 @@
+export * from "./components/DocsLayout";
+export * from "./components/LocalizedPage";
+export * from "./docsI18n";

package/dist/pageMap.cjs

@@ -0,0 +1,55 @@
+"use strict";
+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 pageMap_exports = {};
+__export(pageMap_exports, {
+  localizePageMap: () => localizePageMap
+});
+module.exports = __toCommonJS(pageMap_exports);
+function localizeMetaValue(value, titles) {
+  if (typeof value === "string") return titles[value] ?? value;
+  if (value && typeof value === "object" && typeof value.title === "string") {
+    const translated = titles[value.title];
+    return translated ? { ...value, title: translated } : value;
+  }
+  return value;
+}
+function localizePageMap(pageMap, titles) {
+  if (Object.keys(titles).length === 0) return pageMap;
+  return pageMap.map((item) => {
+    if ("data" in item) {
+      const data = Object.fromEntries(
+        Object.entries(item.data).map(([key, value]) => [key, localizeMetaValue(value, titles)])
+      );
+      return { ...item, data };
+    }
+    const copy = { ...item };
+    const title = item.title;
+    if (typeof title === "string" && titles[title]) copy.title = titles[title];
+    if ("frontMatter" in item && item.frontMatter && typeof item.frontMatter.title === "string") {
+      const title2 = titles[item.frontMatter.title];
+      if (title2) copy.frontMatter = { ...item.frontMatter, title: title2 };
+    }
+    if ("children" in item && Array.isArray(item.children)) copy.children = localizePageMap(item.children, titles);
+    return copy;
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  localizePageMap
+});

package/dist/pageMap.d.cts

@@ -0,0 +1,20 @@
+import { PageMapItem } from 'nextra';
+
+/**
+ * Translates the titles of a Nextra page map: the sidebar, the top-level menu, the breadcrumbs and the previous / next
+ * links all read them. Titles are matched by their English text (the `_meta` titles, the `title` of each item and the
+ * front matter `title`), so a site lists each English title once, whatever the page; titles without a translation,
+ * such as package names, stay as they are. The page map is not modified: changed items are copied.
+ *
+ * @example
+ * ```ts
+ * localizePageMap(pageMap, { Introduction: 'Вступ', Packages: 'Пакети' });
+ * ```
+ *
+ * @param pageMap - The page map of the site, the result of `getPageMap()` of `nextra/page-map`.
+ * @param titles - Translated titles by English title.
+ * @returns The page map with translated titles.
+ */
+declare function localizePageMap(pageMap: PageMapItem[], titles: Readonly<Record<string, string>>): PageMapItem[];
+
+export { localizePageMap };

package/dist/pageMap.d.ts

@@ -0,0 +1,20 @@
+import { PageMapItem } from 'nextra';
+
+/**
+ * Translates the titles of a Nextra page map: the sidebar, the top-level menu, the breadcrumbs and the previous / next
+ * links all read them. Titles are matched by their English text (the `_meta` titles, the `title` of each item and the
+ * front matter `title`), so a site lists each English title once, whatever the page; titles without a translation,
+ * such as package names, stay as they are. The page map is not modified: changed items are copied.
+ *
+ * @example
+ * ```ts
+ * localizePageMap(pageMap, { Introduction: 'Вступ', Packages: 'Пакети' });
+ * ```
+ *
+ * @param pageMap - The page map of the site, the result of `getPageMap()` of `nextra/page-map`.
+ * @param titles - Translated titles by English title.
+ * @returns The page map with translated titles.
+ */
+declare function localizePageMap(pageMap: PageMapItem[], titles: Readonly<Record<string, string>>): PageMapItem[];
+
+export { localizePageMap };

package/dist/pageMap.js

@@ -0,0 +1,31 @@
+function localizeMetaValue(value, titles) {
+  if (typeof value === "string") return titles[value] ?? value;
+  if (value && typeof value === "object" && typeof value.title === "string") {
+    const translated = titles[value.title];
+    return translated ? { ...value, title: translated } : value;
+  }
+  return value;
+}
+function localizePageMap(pageMap, titles) {
+  if (Object.keys(titles).length === 0) return pageMap;
+  return pageMap.map((item) => {
+    if ("data" in item) {
+      const data = Object.fromEntries(
+        Object.entries(item.data).map(([key, value]) => [key, localizeMetaValue(value, titles)])
+      );
+      return { ...item, data };
+    }
+    const copy = { ...item };
+    const title = item.title;
+    if (typeof title === "string" && titles[title]) copy.title = titles[title];
+    if ("frontMatter" in item && item.frontMatter && typeof item.frontMatter.title === "string") {
+      const title2 = titles[item.frontMatter.title];
+      if (title2) copy.frontMatter = { ...item.frontMatter, title: title2 };
+    }
+    if ("children" in item && Array.isArray(item.children)) copy.children = localizePageMap(item.children, titles);
+    return copy;
+  });
+}
+export {
+  localizePageMap
+};

package/dist/translationCheck.cjs

@@ -0,0 +1,186 @@
+"use strict";
+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 translationCheck_exports = {};
+__export(translationCheck_exports, {
+  checkSiteTranslations: () => checkSiteTranslations,
+  checkTranslation: () => checkTranslation,
+  extractCodeBlocks: () => extractCodeBlocks,
+  extractHeadings: () => extractHeadings,
+  extractLinks: () => extractLinks,
+  loadNextraSlugger: () => loadNextraSlugger
+});
+module.exports = __toCommonJS(translationCheck_exports);
+var import_node_fs = require("node:fs");
+var import_node_module = require("node:module");
+var import_node_path = require("node:path");
+var import_node_url = require("node:url");
+var import_locale = require("./locale.js");
+const FENCE_RE = /^ {0,3}(`{3,}|~{3,})/;
+function splitFences(source) {
+  const blocks = [];
+  const prose = [];
+  let block = null;
+  let fence = "";
+  for (const line of source.split("\n")) {
+    if (block) {
+      block.push(line);
+      if (line.trim().startsWith(fence) && line.trim().replace(/[`~]/g, "") === "") {
+        blocks.push(block.join("\n"));
+        block = null;
+      }
+      continue;
+    }
+    const open = FENCE_RE.exec(line);
+    if (open) {
+      fence = open[1];
+      block = [line];
+    } else {
+      prose.push(line);
+    }
+  }
+  if (block) blocks.push(block.join("\n"));
+  return { blocks, prose: prose.join("\n") };
+}
+function extractCodeBlocks(source) {
+  return splitFences(source).blocks;
+}
+function plainText(markdown) {
+  return markdown.replace(/!?\[([^\]]*)\]\([^)]*\)/g, "$1").replace(/(\*\*|__)(.+?)\1/g, "$2").replace(/(\*|_)(.+?)\1/g, "$2").replace(/`([^`]*)`/g, "$1").trim();
+}
+function extractHeadings(source) {
+  const headings = [];
+  for (const line of splitFences(source).prose.split("\n")) {
+    const match = /^ {0,3}(#{1,6})\s+(.+?)\s*#*\s*$/.exec(line);
+    if (!match) continue;
+    const custom = /\s*\[#([^\]]+)\]\s*$/.exec(match[2]);
+    const text = plainText(custom ? match[2].slice(0, custom.index) : match[2]);
+    headings.push({ depth: match[1].length, text, ...custom && { customId: custom[1] } });
+  }
+  return headings;
+}
+function extractLinks(source) {
+  const prose = splitFences(source).prose.replace(/`[^`\n]*`/g, "");
+  const targets = [];
+  for (const match of prose.matchAll(/\]\(\s*<?([^)\s>]+)>?(?:\s+"[^"]*")?\s*\)|\b(?:href|src)=["']([^"']+)["']/g)) {
+    targets.push(match[1] ?? match[2]);
+  }
+  return targets;
+}
+function headingIds(headings, createSlugger) {
+  const slug = createSlugger();
+  return headings.filter((heading) => heading.depth > 1).map((heading) => slug(heading.customId ?? heading.text));
+}
+const sorted = (values) => [...values].sort();
+function checkTranslation(english, translated, createSlugger) {
+  const issues = [];
+  const englishBlocks = extractCodeBlocks(english);
+  const translatedBlocks = extractCodeBlocks(translated);
+  if (englishBlocks.length !== translatedBlocks.length) {
+    issues.push(`has ${translatedBlocks.length} code blocks, the English page ${englishBlocks.length}`);
+  } else {
+    englishBlocks.forEach((block, index) => {
+      if (block !== translatedBlocks[index]) issues.push(`code block ${index + 1} differs from the English one`);
+    });
+  }
+  const englishHeadings = extractHeadings(english);
+  const translatedHeadings = extractHeadings(translated);
+  const levels = (headings) => headings.map((heading) => "#".repeat(heading.depth)).join(" ");
+  if (levels(englishHeadings) !== levels(translatedHeadings)) {
+    issues.push(`heading levels "${levels(translatedHeadings)}" differ from the English "${levels(englishHeadings)}"`);
+  } else if (createSlugger) {
+    const englishIds = headingIds(englishHeadings, createSlugger);
+    const translatedIds = headingIds(translatedHeadings, createSlugger);
+    englishIds.forEach((id, index) => {
+      if (id !== translatedIds[index]) {
+        issues.push(
+          `heading "${translatedHeadings.filter((h) => h.depth > 1)[index].text}" has the id "${translatedIds[index]}", the English one "${id}" (add [#${id}])`
+        );
+      }
+    });
+  }
+  const englishLinks = sorted(extractLinks(english));
+  const translatedLinks = sorted(extractLinks(translated));
+  const missing = englishLinks.filter((link) => !translatedLinks.includes(link));
+  const extra = translatedLinks.filter((link) => !englishLinks.includes(link));
+  if (missing.length || extra.length || englishLinks.length !== translatedLinks.length) {
+    issues.push(
+      `links differ from the English page (missing: ${missing.join(", ") || "none"}; not in English: ${extra.join(", ") || "none"}; ${translatedLinks.length} vs ${englishLinks.length})`
+    );
+  }
+  return issues;
+}
+function pageFiles(dir) {
+  if (!(0, import_node_fs.existsSync)(dir)) return [];
+  return (0, import_node_fs.readdirSync)(dir, { recursive: true, encoding: "utf8" }).filter((file) => [".md", ".mdx"].includes((0, import_node_path.extname)(file))).map((file) => file.split(import_node_path.sep).join("/")).sort();
+}
+const withoutExtension = (file) => file.slice(0, -(0, import_node_path.extname)(file).length);
+async function loadNextraSlugger(cwd) {
+  try {
+    const nextra = (0, import_node_module.createRequire)((0, import_node_path.join)(cwd, "package.json")).resolve("nextra/package.json");
+    const sluggerPath = (0, import_node_module.createRequire)(nextra).resolve("github-slugger");
+    const { default: GithubSlugger } = await import((0, import_node_url.pathToFileURL)(sluggerPath).href);
+    return () => {
+      const slugger = new GithubSlugger();
+      return (text) => slugger.slug(text);
+    };
+  } catch {
+    return void 0;
+  }
+}
+async function checkSiteTranslations(options = {}) {
+  const { cwd = process.cwd(), contentDir = "src/content", i18nDir = "src/i18n" } = options;
+  if (!(0, import_node_fs.existsSync)((0, import_node_path.join)(cwd, contentDir))) {
+    throw new Error(`No ${contentDir} in ${cwd}: run the check from the docs app of the site`);
+  }
+  const createSlugger = options.createSlugger ?? await loadNextraSlugger(cwd);
+  const locales = import_locale.TUWA_LOCALES.filter((locale) => locale !== import_locale.DEFAULT_LOCALE);
+  const filesByLocale = new Map(locales.map((locale) => [locale, pageFiles((0, import_node_path.join)(cwd, i18nDir, locale))]));
+  const pages = [...new Set([...filesByLocale.values()].flat().map(withoutExtension))].sort();
+  const issues = [];
+  let files = 0;
+  for (const page of pages) {
+    const englishFile = [".mdx", ".md"].map((ext) => (0, import_node_path.join)(cwd, contentDir, page + ext)).find(import_node_fs.existsSync);
+    for (const locale of locales) {
+      const translatedFile = filesByLocale.get(locale)?.find((file) => withoutExtension(file) === page);
+      const shown = (0, import_node_path.join)(i18nDir, locale, translatedFile ?? `${page}.mdx`).split(import_node_path.sep).join("/");
+      if (!translatedFile) {
+        issues.push({ file: shown, message: "is missing: every translated page exists in every language" });
+        continue;
+      }
+      files += 1;
+      if (!englishFile) {
+        issues.push({ file: shown, message: `has no English page ${(0, import_node_path.join)(contentDir, page)}.mdx` });
+        continue;
+      }
+      const english = (0, import_node_fs.readFileSync)(englishFile, "utf8");
+      const translated = (0, import_node_fs.readFileSync)((0, import_node_path.join)(cwd, i18nDir, locale, translatedFile), "utf8");
+      for (const message of checkTranslation(english, translated, createSlugger)) issues.push({ file: shown, message });
+    }
+  }
+  return { files, issues };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  checkSiteTranslations,
+  checkTranslation,
+  extractCodeBlocks,
+  extractHeadings,
+  extractLinks,
+  loadNextraSlugger
+});

package/dist/translationCheck.d.cts

@@ -0,0 +1,89 @@
+/** A heading of a Markdown or MDX page (levels 1 to 6), outside code blocks. */
+interface MarkdownHeading {
+    /** The level: 1 for `#`, 2 for `##`. */
+    depth: number;
+    /** The text without Markdown syntax and without the custom id. */
+    text: string;
+    /** The id written as `[#id]` at the end of the heading, as Nextra reads it. */
+    customId?: string;
+}
+/** Turns a heading text into an id the way Nextra does (`github-slugger`, one instance per page). */
+type HeadingSlugger = () => (text: string) => string;
+/** A problem of a translated page. */
+interface TranslationIssue {
+    /** The translated file, relative to the docs app. */
+    file: string;
+    /** What does not match the English page. */
+    message: string;
+}
+/**
+ * The fenced code blocks of a Markdown or MDX page, in order, each with its opening line (language and meta) and its
+ * closing fence.
+ *
+ * @param source - The page source.
+ * @returns The code blocks.
+ */
+declare function extractCodeBlocks(source: string): string[];
+/**
+ * The headings of a Markdown or MDX page, outside code blocks.
+ *
+ * @param source - The page source.
+ * @returns The headings, in order.
+ */
+declare function extractHeadings(source: string): MarkdownHeading[];
+/**
+ * The link and image targets of a Markdown or MDX page outside code blocks: `[text](url)`, `href="url"` and
+ * `src="url"`.
+ *
+ * @param source - The page source.
+ * @returns The targets, in order.
+ */
+declare function extractLinks(source: string): string[];
+/**
+ * Compares a translated page with its English page. A translation keeps the structure of the English page so readers
+ * of every language get the same page: the same code blocks in the same order (examples are never translated), the
+ * same heading levels with the English heading ids (written as `[#id]`, so anchors work in every language) and the
+ * same links.
+ *
+ * @param english - The source of the English page.
+ * @param translated - The source of the translation.
+ * @param createSlugger - Creates the heading id function of a page (`() => { const s = new GithubSlugger(); return (text) => s.slug(text); }`);
+ *   without it the ids are not compared.
+ * @returns What does not match, empty when the translation keeps the structure.
+ */
+declare function checkTranslation(english: string, translated: string, createSlugger?: HeadingSlugger): string[];
+/**
+ * Loads the heading slugger of Nextra (`github-slugger`, a dependency of `nextra`) from the site, so the check gives
+ * headings the ids the site gives them.
+ *
+ * @param cwd - The docs app, whose `node_modules` has `nextra`.
+ * @returns The slugger factory, or `undefined` when `nextra` or `github-slugger` cannot be found.
+ */
+declare function loadNextraSlugger(cwd: string): Promise<HeadingSlugger | undefined>;
+/** Options of {@link checkSiteTranslations}. */
+interface CheckSiteTranslationsOptions {
+    /** The docs app (default: the working directory). */
+    cwd?: string;
+    /** The English pages, relative to `cwd` (default: `src/content`). */
+    contentDir?: string;
+    /** The translations, one folder per language, relative to `cwd` (default: `src/i18n`). */
+    i18nDir?: string;
+    /** The heading slugger (default: {@link loadNextraSlugger}). */
+    createSlugger?: HeadingSlugger;
+}
+/**
+ * Checks the translated pages of a documentation site: `<i18nDir>/<locale>/<path>.mdx` translates
+ * `<contentDir>/<path>.mdx` (or the generated `.md`). Every translated page must exist in every language and keep the
+ * structure of its English page ({@link checkTranslation}). Reads files only.
+ *
+ * @param options - See {@link CheckSiteTranslationsOptions}.
+ * @returns The number of translated files and the issues found.
+ * @throws When `contentDir` does not exist (the check runs from the wrong directory).
+ */
+declare function checkSiteTranslations(options?: CheckSiteTranslationsOptions): Promise<{
+    files: number;
+    issues: TranslationIssue[];
+}>;
+
+export { checkSiteTranslations, checkTranslation, extractCodeBlocks, extractHeadings, extractLinks, loadNextraSlugger };
+export type { CheckSiteTranslationsOptions, HeadingSlugger, MarkdownHeading, TranslationIssue };

package/dist/translationCheck.d.ts

@@ -0,0 +1,89 @@
+/** A heading of a Markdown or MDX page (levels 1 to 6), outside code blocks. */
+interface MarkdownHeading {
+    /** The level: 1 for `#`, 2 for `##`. */
+    depth: number;
+    /** The text without Markdown syntax and without the custom id. */
+    text: string;
+    /** The id written as `[#id]` at the end of the heading, as Nextra reads it. */
+    customId?: string;
+}
+/** Turns a heading text into an id the way Nextra does (`github-slugger`, one instance per page). */
+type HeadingSlugger = () => (text: string) => string;
+/** A problem of a translated page. */
+interface TranslationIssue {
+    /** The translated file, relative to the docs app. */
+    file: string;
+    /** What does not match the English page. */
+    message: string;
+}
+/**
+ * The fenced code blocks of a Markdown or MDX page, in order, each with its opening line (language and meta) and its
+ * closing fence.
+ *
+ * @param source - The page source.
+ * @returns The code blocks.
+ */
+declare function extractCodeBlocks(source: string): string[];
+/**
+ * The headings of a Markdown or MDX page, outside code blocks.
+ *
+ * @param source - The page source.
+ * @returns The headings, in order.
+ */
+declare function extractHeadings(source: string): MarkdownHeading[];
+/**
+ * The link and image targets of a Markdown or MDX page outside code blocks: `[text](url)`, `href="url"` and
+ * `src="url"`.
+ *
+ * @param source - The page source.
+ * @returns The targets, in order.
+ */
+declare function extractLinks(source: string): string[];
+/**
+ * Compares a translated page with its English page. A translation keeps the structure of the English page so readers
+ * of every language get the same page: the same code blocks in the same order (examples are never translated), the
+ * same heading levels with the English heading ids (written as `[#id]`, so anchors work in every language) and the
+ * same links.
+ *
+ * @param english - The source of the English page.
+ * @param translated - The source of the translation.
+ * @param createSlugger - Creates the heading id function of a page (`() => { const s = new GithubSlugger(); return (text) => s.slug(text); }`);
+ *   without it the ids are not compared.
+ * @returns What does not match, empty when the translation keeps the structure.
+ */
+declare function checkTranslation(english: string, translated: string, createSlugger?: HeadingSlugger): string[];
+/**
+ * Loads the heading slugger of Nextra (`github-slugger`, a dependency of `nextra`) from the site, so the check gives
+ * headings the ids the site gives them.
+ *
+ * @param cwd - The docs app, whose `node_modules` has `nextra`.
+ * @returns The slugger factory, or `undefined` when `nextra` or `github-slugger` cannot be found.
+ */
+declare function loadNextraSlugger(cwd: string): Promise<HeadingSlugger | undefined>;
+/** Options of {@link checkSiteTranslations}. */
+interface CheckSiteTranslationsOptions {
+    /** The docs app (default: the working directory). */
+    cwd?: string;
+    /** The English pages, relative to `cwd` (default: `src/content`). */
+    contentDir?: string;
+    /** The translations, one folder per language, relative to `cwd` (default: `src/i18n`). */
+    i18nDir?: string;
+    /** The heading slugger (default: {@link loadNextraSlugger}). */
+    createSlugger?: HeadingSlugger;
+}
+/**
+ * Checks the translated pages of a documentation site: `<i18nDir>/<locale>/<path>.mdx` translates
+ * `<contentDir>/<path>.mdx` (or the generated `.md`). Every translated page must exist in every language and keep the
+ * structure of its English page ({@link checkTranslation}). Reads files only.
+ *
+ * @param options - See {@link CheckSiteTranslationsOptions}.
+ * @returns The number of translated files and the issues found.
+ * @throws When `contentDir` does not exist (the check runs from the wrong directory).
+ */
+declare function checkSiteTranslations(options?: CheckSiteTranslationsOptions): Promise<{
+    files: number;
+    issues: TranslationIssue[];
+}>;
+
+export { checkSiteTranslations, checkTranslation, extractCodeBlocks, extractHeadings, extractLinks, loadNextraSlugger };
+export type { CheckSiteTranslationsOptions, HeadingSlugger, MarkdownHeading, TranslationIssue };