跳转到主要内容

文档工具

文档使用 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/            # Hindi
│   ├── pt-BR/         # Brazilian Portuguese
│   └── zh-Hans/       # Simplified Chinese
├── src/               # React components and pages
│   ├── components/    # Custom React components
│   ├── css/           # Custom styles
│   ├── landing/       # Homepage HTML + CSS (English source; locale copies in landing/i18n/)
│   ├── pages/         # Additional pages (homepage shell, 404)
│   └── theme/         # Swizzled theme (navbar)
├── 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 命令将 UI 字符串（来自 Docusaurus 主题和自定义组件）提取到 JSON 翻译文件中。pnpm translate 脚本（来自 documentation/，委托给代码仓库根目录）运行 ai-i18n-tools，按照 ai-i18n-tools.config.json 翻译 markdown、JSON、SVG 和落地页 HTML。

文档主页是由 src/pages/index.tsx 包裹的 src/landing/landing.html。如需修改文案，请编辑该 HTML 文件；各语言区域的副本位于 src/landing/i18n/ 下，由 pnpm i18n:translate:docs 生成。

important

请仅编辑 docs/ 中的文件、落地页源文件 src/landing/landing.html 和 i18n/en-GB/ 中的源 JSON 文件。i18n/{other-locales}/ 下已翻译的 markdown 和 src/landing/i18n/ 下的落地页副本均为生成内容，请勿手动编辑。

支持的语言环境​

语言环境语言目录
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印地语i18n/hi/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/ 和 src/locales/templates/（按配置）。
  3. 构建：pnpm build 在 documentation/build/ 下为所有语言环境生成静态 HTML。

运行翻译​

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

CLI 标志由 ai-i18n-tools 定义；从仓库根目录运行 pnpm exec ai-i18n-tools --help 或查看 翻译工作流程。

手动翻译覆盖​

编辑 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/duplistatus/ 上可用（或下一个可用端口）。/duplistatus/ 路径与 GitHub Pages baseUrl 和应用内帮助按钮链接匹配。

构建​

为生产构建文档站点：

cd documentation
pnpm build

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

服务生产构建​

在本地预览生产构建：

cd documentation
pnpm serve

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

其他有用命令​

  • pnpm clear - 清除 Docusaurus 缓存
  • pnpm typecheck - 运行 TypeScript 类型检查
  • pnpm write-heading-ids - 使用 Docusaurus MDX 注释语法将显式 {/* #id */} 标题锚点写入 markdown（从 documentation/ 运行以在翻译间保持稳定的链接）。CLI 会跳过 h1 标题，Docusaurus 将其用作侧边栏标签。

生成 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 文档 URL（https://wsj-br.github.io/duplistatus/...）
  • 将图像路径从 /img/ 转换为 documentation/static/img/ 以兼容 GitHub
  • 移除迁移重要块并添加迁移信息部分，包含指向 Docusaurus 文档的链接
  • 使用 doctoc 生成目录
  • 生成具有 Docker Hub 兼容格式的 README_dockerhub.md（将图像和链接转换为绝对 URL，将 GitHub 警报转换为基于表情符号的格式）
  • 从 documentation/docs/release-notes/VERSION.md 生成 GitHub 发布说明（RELEASE_NOTES_github_VERSION.md）（将链接和图像转换为绝对 URL）

更新 Docker Hub 的 README​

脚本 generate-readme-from-intro.sh 自动使用 Docker Hub 兼容格式生成 README_dockerhub.md。它：

  • 将 README.md 复制到 README_dockerhub.md
  • 将相对图像路径转换为绝对 GitHub 原始 URL
  • 将相对文档链接转换为绝对 GitHub blob URL
  • 将 GitHub 风格的警报（[!NOTE]、[!WARNING] 等）转换为基于表情符号的格式，以更好地兼容 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 文档 URL（https://wsj-br.github.io/duplistatus/...）
  • 将图像路径转换为 GitHub 原始 URL（https://raw.githubusercontent.com/wsj-br/duplistatus/main/documentation/static/img/...），以便在发布描述中正确显示
  • 处理带有 ../ 前缀的相对路径
  • 保持绝对 URL（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）。

此脚本自动为文档目的截取应用程序的屏幕截图。它：

  • 在环境和健康检查后运行 pnpm exec playwright install，以便 Playwright 浏览器存在
  • 启动无头浏览器（Playwright Chromium）
  • 以管理员和普通用户身份登录
  • 浏览各个页面（仪表板、服务器详情、设置等）
  • 在不同视口大小下截取屏幕截图
  • 将屏幕截图保存到 documentation/static/assets/（英文）或 documentation/i18n/{locale}/docusaurus-plugin-content-docs/current/assets（其他语言环境）

要求：

  • 开发服务器必须在 http://localhost:8666 上运行
  • 必须设置环境变量，请将这些添加到您的 .env 文件或导出它们：
    • ADMIN_PASSWORD：管理员账户密码
    • USER_PASSWORD：普通用户账户密码

选项： --locale 将屏幕截图限制为一个或多个语言环境（逗号分隔）。如果省略，则捕获所有语言环境。有效语言环境：en-GB、de、fr、es、pt-BR、hi、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 翻译、缓存管理），请参见翻译工作流程。

源文件​

  • 文档内容：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

始终在至少默认英文区域设置和其他一个区域设置中测试更改，以确保翻译正确显示。