跳至主要内容

文档工具

文档使用 Docusaurus 构建，并位于 documentation 文件夹中。文档托管在 GitHub Pages 上，不再包含在 Docker 容器镜像中。

文件夹结构​

documentation/
├── docs/              # Documentation markdown files (English source)
│   ├── api-reference/
│   ├── development/
│   ├── installation/
│   ├── migration/
│   ├── release-notes/
│   └── user-guide/
├── i18n/              # Translations (auto-generated by translation workflow)
│   ├── de/            # German
│   ├── es/            # Spanish
│   ├── fr/            # French
│   ├── hi-Latn/       # Hindi (Roman)
│   ├── pt-BR/         # Brazilian Portuguese
│   └── zh-Hans/       # Simplified Chinese
├── src/               # React components and pages
│   ├── components/    # Custom React components
│   ├── css/           # Custom styles
│   └── pages/         # Additional pages (e.g., 404)
├── static/            # Static assets (images, files)
├── docusaurus.config.ts  # Docusaurus configuration
├── sidebars.ts        # Sidebar navigation configuration
└── package.json       # Dependencies and scripts

国际化 (i18n)​

文档使用 Docusaurus 的内置 i18n 系统，英语为默认语言。翻译内容位于 i18n/{locale}/docusaurus-plugin-content-docs/current/，镜像 docs/ 文件夹的结构。

  • 源文件: docs/**/*.md (英语)
  • 翻译文件: i18n/{locale}/docusaurus-plugin-content-docs/current/**/*.md
  • UI 翻译: i18n/{locale}/docusaurus-theme-classic/*.json 和其他 JSON 文件
  • 本地化截图: i18n/{locale}/docusaurus-plugin-content-docs/current/**/assets，由 pnpm take-screenhots 在基目录生成。

pnpm write-translations 命令从 Docusaurus 主题和自定义组件中提取 UI 字符串到 JSON 翻译文件。pnpm translate 脚本（来自 documentation/，委托到仓库根目录）运行 ai-i18n-tools 以翻译 markdown、JSON 和 SVG 文件，按照 ai-i18n-tools.config.json。

important

仅编辑 docs/ 文件和 i18n/en/ 中的源 JSON 文件。i18n/{other-locales}/ 中的翻译 markdown 文件是自动生成的，不应手动编辑。

支持的语言​

区域设置语言目录
en-GB英语（默认）docs/（源）
de德语i18n/de/docusaurus-plugin-content-docs/current/
es西班牙语i18n/es/docusaurus-plugin-content-docs/current/
fr法语i18n/fr/docusaurus-plugin-content-docs/current/
hi-Latn印地语（罗马音）i18n/hi-Latn/docusaurus-plugin-content-docs/current/
pt-BR巴西葡萄牙语i18n/pt-BR/docusaurus-plugin-content-docs/current/
zh-Hans简体中文i18n/zh-Hans/docusaurus-plugin-content-docs/current/

翻译文档​

本文档使用 AI 驱动的翻译系统来翻译内容（Markdown 文件）和 UI 字符串（来自 Docusaurus 和自定义组件）。源内容为英语（docs/），并为德语、法语、西班牙语、巴西葡萄牙语、印地语（罗马音）和简体中文生成了翻译。

翻译工作原理​

  1. Docusaurus UI 字符串: pnpm write-translations 提取主题/自定义字符串到 i18n/en/*.json。
  2. AI 翻译 (OpenRouter；配置在 ai-i18n-tools.config.json 中的仓库根目录): 从 documentation/，pnpm translate 运行根 i18n:translate 脚本（UI 字符串、SVG 和 Docusaurus markdown/JSON）到 documentation/i18n/ 和 src/locales/，如配置所示。
  3. 构建: pnpm build 为所有语言生成静态 HTML 文件，位于 documentation/build/ 下。

运行翻译​

cd documentation
pnpm translate          # Same as repo root: i18n:translate (ui + svg + docs)
pnpm translate:docs
pnpm translate:svg
pnpm translate:ui
pnpm translate:status

CLI 标志由 ai-i18n-tools 定义；从仓库根目录运行 pnpm exec ai-i18n-tools --help 或参阅 Translation Workflow。

手动翻译覆盖​

编辑 documentation/glossary-user.csv（并可选地清除仓库根目录下 .translation-cache/ 中的过期条目），然后重新运行相关的 pnpm translate:* 命令。

常用命令​

所有命令都应从 documentation 目录运行:

开发​

使用热重载为特定语言启动开发服务器:

cd documentation
pnpm start:en    # English (default)
pnpm start:fr    # French
pnpm start:de    # German
pnpm start:es    # Spanish
pnpm start:pt-br # Brazilian Portuguese

该网站将在 http://localhost:3000（或下一个可用端口）上可用。

构建​

为生产环境构建文档网站:

cd documentation
pnpm build

这会在 documentation/build 目录中生成静态 HTML 文件。

预览生产环境构建​

本地预览生产环境构建:

cd documentation
pnpm serve

这会从 documentation/build 目录提供构建的网站。

其他有用命令​

  • pnpm clear - 清除 Docusaurus 缓存
  • pnpm typecheck - 运行 TypeScript 类型检查
  • pnpm write-heading-ids - 使用 Docusaurus 规则将显式 {#id} 标题锚点写入 markdown（从 documentation/ 运行以实现跨翻译的稳定链接）

生成 README.md​

项目的 README.md 文件会自动从 documentation/docs/intro.md 生成，以保持 GitHub 仓库 README 与 Docusaurus 文档同步。

要生成或更新 README.md 文件:

./scripts/generate-readme-from-intro.sh

此脚本:

  • 从 package.json 中提取当前版本并添加版本徽章
  • 从 documentation/docs/intro.md 复制内容
  • 将 Docusaurus 告知（注释、提示、警告等）转换为 GitHub 风格的警报
  • 将所有相对 Docusaurus 链接转换为绝对 GitHub 文档 URLs (https://wsj-br.github.io/duplistatus/...)
  • 将图像路径从 /img/ 转换为 documentation/static/img/ 以适应 GitHub
  • 删除迁移 IMPORTANT 块并添加一个迁移信息部分，包含一个链接到 Docusaurus 文档
  • 使用 doctoc 生成目录
  • 生成 README_dockerhub.md，具有 Docker Hub 兼容的格式（将图像和链接转换为绝对 URLs，将 GitHub 警报转换为基于 emoji 的格式）
  • 生成 GitHub 发布说明（RELEASE_NOTES_github_VERSION.md）从 documentation/docs/release-notes/VERSION.md（将链接和图像转换为绝对 URLs）

更新 README 以适应 Docker Hub​

generate-readme-from-intro.sh 脚本自动生成 README_dockerhub.md，具有 Docker Hub 兼容的格式。它:

  • 将 README.md 复制到 README_dockerhub.md
  • 将相对图像路径转换为绝对 GitHub raw URLs
  • 将相对文档链接转换为绝对 GitHub blob URLs
  • 将 GitHub 风格的警报（[!NOTE]、[!WARNING] 等）转换为基于 emoji 的格式，以适应 Docker Hub 的兼容性
  • 确保所有图像和链接在 Docker Hub 上正常工作

生成 GitHub 发布说明​

generate-readme-from-intro.sh 脚本自动生成 GitHub 发布说明。当运行时，它:

  • 从 documentation/docs/release-notes/VERSION.md 读取发布说明（其中 VERSION 从 package.json 中提取）
  • 将标题从 "# Version xxxx" 改为 "# Release Notes - Version xxxxx"
  • 将相对 markdown 链接转换为绝对 GitHub 文档 URLs（https://wsj-br.github.io/duplistatus/...）
  • 将图像路径转换为 GitHub raw URLs（https://raw.githubusercontent.com/wsj-br/duplistatus/main/documentation/static/img/...）以适应发布描述的正确显示
  • 处理具有 ../ 前缀的相对路径
  • 保留绝对 URLs（http:// 和 https://）不变
  • 在项目根目录中创建 RELEASE_NOTES_github_VERSION.md

示例:

# This will generate both README.md and RELEASE_NOTES_github_VERSION.md
./scripts/generate-readme-from-intro.sh

生成的发布说明文件可以直接复制并粘贴到 GitHub 发布描述中。全部 链接和图像将在 GitHub 发布上下文中正确工作。

为文档截取屏幕​

pnpm take-screenshots

或者直接运行：pnpm take-screenshots（如果需要环境变量，请使用 --env-file=.env）。

此脚本会自动为应用程序截屏以用于文档目的。它将：

  • 启动一个无头浏览器（Playwright Chromium）
  • 以管理员和普通用户身份登录
  • 浏览各种页面（仪表板、服务器详细信息、设置等）
  • 在不同的视口大小下截取屏幕截图
  • 将屏幕截图保存到 documentation/static/assets/（英语）或 documentation/i18n/{locale}/docusaurus-plugin-content-docs/current/assets（其他语言）

要求:

  • 开发服务器必须在 http://localhost:8666 上运行
  • 必须安装 Playwright Chromium 浏览器（运行一次 pnpm take-screenshots:install，它会运行 playwright install chromium）
  • 必须设置环境变量，将它们添加到您的 .env 文件或导出它们：
    • ADMIN_PASSWORD: 管理员账户的密码
    • USER_PASSWORD: 普通用户账户的密码

选项： --locale 将截图限制为一个或多个区域设置（以逗号分隔）。如果省略，则捕获所有区域设置。有效的区域设置：en-GB、de、fr、es、pt-BR、hi-Latn、zh-Hans。使用 -h 或 --help 打印用法。

示例:

export ADMIN_PASSWORD="your-admin-password"
export USER_PASSWORD="your-user-password"
pnpm take-screenshots
# All locales (default):
pnpm take-screenshots
# Single locale:
pnpm take-screenshots --locale en-GB
# Multiple locales:
pnpm take-screenshots --locale en-GB,de,pt-BR

部署文档​

要将文档部署到 GitHub Pages，您需要生成一个 GitHub 个人访问令牌。请前往 GitHub 个人访问令牌 并创建一个具有 repo 范围的新令牌。

何时您拥有令牌时，将其存储在 Git 凭证存储中（例如，使用 git config credential.helper store 或系统的凭证管理器）。

然后，为了将文档部署到 GitHub Pages，请在 documentation 目录中运行以下命令：

pnpm run deploy

这将构建文档并将其推送到存储库的 gh-pages 分支，并且文档将在 https://wsj-br.github.io/duplistatus/ 中可用。

与文档合作​

有关完整的翻译工作流程（词汇管理、AI 翻译、缓存管理），请参阅 Translation Workflow。

源文件​

  • 文档内容：documentation/docs/ 中的英文 markdown 文件
  • UI 翻译：documentation/i18n/en/ 中的英文 JSON 文件（由 pnpm write-translations 自动生成）
  • 侧边栏导航：documentation/sidebars.ts
  • Docusaurus 配置：documentation/docusaurus.config.ts
  • 自定义 React 组件：documentation/src/components/
  • 静态资产：documentation/static/
  • 主页：documentation/docs/intro.md （用于生成 README.md）

添加新组件​

  1. 在 documentation/src/components/ 中创建您的 React 组件
  2. 从 documentation/src/theme/MDXComponents.js 导出它以使其在 MDX 中可用
  3. 如果组件包含可翻译的 UI 字符串，请运行 pnpm write-translations 以提取它们
  4. 运行 pnpm translate 以将新字符串翻译为所有语言

添加新文档页面​

  1. 在 documentation/docs/ 中（或子目录中）创建一个新 .md 文件
  2. 在 documentation/sidebars.ts 中将其添加到侧边栏
  3. 运行 pnpm write-translations 以更新翻译文件结构
  4. 运行 pnpm write-heading-ids 以生成标题 ID（锚点）
  5. 运行 pnpm translate 以将新页面翻译为所有语言
  6. 构建和测试：pnpm build

静态资产​

  • 图像：将其放在 documentation/static/img/ 中，并在 markdown 中使用 /img/filename.png 引用
  • 下载/PDF：将其放在 documentation/static/ 中，并使用 /filename.pdf 引用
  • 每个语言的资产：如果资产需要为特定语言（例如，截图），请将其放在 documentation/i18n/{locale}/docusaurus-plugin-content-docs/current/assets/ 中

构建和测试​

cd documentation
pnpm build            # Builds all locales
pnpm serve            # Preview the built site locally
pnpm start:en         # Development server for English
pnpm start:pt-br      # Development server for Portuguese

始终在默认英语语言环境和至少一个其他语言环境中测试您的更改，以确保翻译正确显示。