@tuwaio/docs-ui 0.5.7 → 0.6.0

package/dist/translationCheck.js

@@ -0,0 +1,157 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { extname, join, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+import { DEFAULT_LOCALE, TUWA_LOCALES } from "./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 (!existsSync(dir)) return [];
+  return readdirSync(dir, { recursive: true, encoding: "utf8" }).filter((file) => [".md", ".mdx"].includes(extname(file))).map((file) => file.split(sep).join("/")).sort();
+}
+const withoutExtension = (file) => file.slice(0, -extname(file).length);
+async function loadNextraSlugger(cwd) {
+  try {
+    const nextra = createRequire(join(cwd, "package.json")).resolve("nextra/package.json");
+    const sluggerPath = createRequire(nextra).resolve("github-slugger");
+    const { default: GithubSlugger } = await import(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 (!existsSync(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 = TUWA_LOCALES.filter((locale) => locale !== DEFAULT_LOCALE);
+  const filesByLocale = new Map(locales.map((locale) => [locale, pageFiles(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) => join(cwd, contentDir, page + ext)).find(existsSync);
+    for (const locale of locales) {
+      const translatedFile = filesByLocale.get(locale)?.find((file) => withoutExtension(file) === page);
+      const shown = join(i18nDir, locale, translatedFile ?? `${page}.mdx`).split(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 ${join(contentDir, page)}.mdx` });
+        continue;
+      }
+      const english = readFileSync(englishFile, "utf8");
+      const translated = readFileSync(join(cwd, i18nDir, locale, translatedFile), "utf8");
+      for (const message of checkTranslation(english, translated, createSlugger)) issues.push({ file: shown, message });
+    }
+  }
+  return { files, issues };
+}
+export {
+  checkSiteTranslations,
+  checkTranslation,
+  extractCodeBlocks,
+  extractHeadings,
+  extractLinks,
+  loadNextraSlugger
+};

package/package.json

@@ -1,15 +1,16 @@
 {
   "name": "@tuwaio/docs-ui",
-  "version": "0.5.7",
+  "version": "0.6.0",
   "private": false,
   "author": "Oleksandr Tkach",
   "license": "Apache-2.0",
-  "description": "Shared UI of the TUWA documentation sites: Nextra navbar and footer, remote logo, theme switcher, background effects, policy pages and styles.",
+  "description": "Shared UI of the TUWA documentation sites: Nextra navbar, footer and layout in English, Ukrainian and Simplified Chinese, remote logo, theme and language switches, background effects, policy pages and styles.",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "bin": {
-    "tuwa-docs-search-index": "./bin/search-index.js"
+    "tuwa-docs-search-index": "./bin/search-index.js",
+    "tuwa-docs-i18n-check": "./bin/i18n-check.js"
   },
   "type": "module",
   "exports": {
@@ -33,6 +34,16 @@
       "import": "./dist/i18n.js",
       "require": "./dist/i18n.cjs"
     },
+    "./nextra": {
+      "types": "./dist/nextra.d.ts",
+      "import": "./dist/nextra.js",
+      "require": "./dist/nextra.cjs"
+    },
+    "./nextra/page": {
+      "types": "./dist/docsPage.d.ts",
+      "import": "./dist/docsPage.js",
+      "require": "./dist/docsPage.cjs"
+    },
     "./dist/index.css": "./dist/index.css",
     "./dist/*": "./dist/*"
   },
@@ -79,6 +90,7 @@
   "peerDependencies": {
     "@heroicons/react": ">=2",
     "next": ">=16.1",
+    "nextra": ">=4.6",
     "nextra-theme-docs": ">=4.6",
     "react": ">=19.2.3"
   },