# XX 中文文档 本文档使用 AI 翻译 ## 项目流程 ### 首次使用 1. 创建空分支 ```bash git switch --orphan docs ``` 2. 创建 `README.md` ```bash cat > README.md <<EOF # XX 中文文档 本文档使用 AI 翻译 EOF ``` 3. 首次提交 ```bash git add README.md git commit -am init git push origin docs ``` 4. 拉取上游源码 ```bash mkdir -p docsite pushd docsite if [[ -d .git ]]; then git remote set-url upstream https://github.com/xxx/docs.git else git init git remote add upstream https://github.com/xxx/docs.git fi git reset --hard git fetch upstream main git merge upstream/main popd ``` 5. 复制源文档 ```bash cp -r docsite/content . rm -rf docs mv content docs ``` 6. 全量翻译 ```bash aitr ``` 7. 本地测试与构建 ```bash git clone https://github.com/xxx/docs.git docsite cp -r docs_zh/* ./docsite/content cd docsite ``` 8. 启动或构建 ```bash # NodeJS npm install npm run dev # Hugo hugo server ... ``` ### 2. AI 翻译 - 安装 [**CLI**](https://git.jetsung.com/jetsung/ai-translator) 工具 （增量更新直接使用 AI CLI 工具直接对比） ```bash curl -L https://fx4.cn/aitr | bash ``` 1. 设置环境变量 [`config.toml`](config.example.toml) ```bash ... [[providers]] enabled = true name = "grok" api_key = "xxx" base_url = "https://api.x.ai/v1" model = "grok-3" concurrency = 1 # 线程数 rate_delay = 3.0 # 每个请求后等待 1.0 秒（可根据限流调整） ``` 2. AI 翻译 ```bash aitr ```

# 根目录 - 包含需要翻译的 Markdown 文件 root_dir = "./docs" # 输出目录 - 翻译后的文件保存位置 output_dir = "./docs_zh" # 输出模式: "overwrite" (覆盖原文件) 或 "new_folder" (保存到新文件夹) output_mode = "new_folder" # 排除的目录 (逗号分隔) exclude_dir = "node_modules,.git,_build" # 最大 token 数 max_tokens = 99999 # 系统提示词（支持多行，使用 """ 包裹） system_prompt = """ 你是一个专业的技术文档翻译专家。请将以下英文 Markdown 文档翻译成流畅、自然的简体中文。 严格要求： 1. 保留完整的 Markdown 格式，包括标题、列表、表格、代码块、链接、图片等一切结构完全不变。 2. 代码块、命令行、文件名、路径、API 名称、配置文件内容、技术术语等保持原样（不要翻译）。 3. 专有名词（如产品名、框架名、软件名，例如 Traefik、Docker、Kubernetes）保持英文原名。 4. Hugo 短代码和模板语法（如 {{< xxx >}}、{{ xxx }}、{{</ xxx >}} 等所有以 {{ 或 {{< 开头的标签）必须完整保留原样，不翻译、不修改其内部任何内容。 5. 对于 YAML frontmatter（文档开头的 --- 之间的内容）： - 只翻译实际需要本地化的字符串值内容（如 title、description、linkTitle 等字段的值）。 - tags 字段的值（通常为字符串或字符串列表）必须完全保持原英文不变，不进行任何翻译或修改。 - 其他字段（如 keywords 等）按正常规则处理：如果为字符串值则翻译（如 description），如果为列表则视情况保留英文（专有名词不翻译）。 - 严格保留原文档中的所有字段、键名、结构、格式、缩进和所有机制（包括已有的 YAML 锚点 &xxx 和别名 *xxx）。 - 如果原文档中已有锚点定义，则在翻译该锚点对应的字符串值时保留锚点标记（如 &desc）；别名引用（如 *desc）保持原样不变。 - 如果原文档中没有锚点或别名，则翻译后绝对不得新增任何锚点、别名、params 块或其他额外字段。 - 绝对不得添加、删除或修改任何原有字段、锚点、别名或 params 等结构，仅对需要本地化的字符串值进行翻译。 - aliases、keywords、tags 等列表字段的值，按原文档格式保留（保持原有引号使用情况，不统一添加或移除引号）。 - 必须输出且仅输出一次完整的 YAML Front Matter（以 --- 开头，以 --- 结尾）。 - 结尾的 --- 必须独占一行，且在其后必须紧跟一个空行。 - 绝对不要在翻译后的 Front Matter 之前或之后保留原始的英文 Front Matter。 6. 翻译要准确、专业、易懂，技术术语使用业界通用中文表达。 7. 绝对禁止在文档开头或 YAML frontmatter 前后添加任何 Markdown 代码块标记（如 ```markdown 或 ```），保持文档结构的纯净。 8. 绝对禁止自作主张地添加任何原文档中不存在的内容，包括但不限于：完整的语言指南、示例代码、学习资源、最佳实践等。只翻译原文档中已有的内容，不多不少。 9. 只输出翻译后的完整 Markdown 内容，不要添加任何说明、注释或多余文本。 10. Markdown 链接 `[text](url)` 中的 `url` 必须完全保持原样，绝对不要修改、翻译或移除路径中的任何部分。即使是相对路径或绝对路径，也都必须保持原样。 """ [[providers]] name = "grok" api_key = "xxx" base_url = "https://api.x.ai/v1" model = "grok-3" concurrency = 4 # 线程数 rate_delay = 3.0 # 每个请求后等待 1.0 秒（可根据限流调整）

#!/usr/bin/env bash #============================================================ # File: deploy.sh # Description: 部署 # URL: # Author: Jetsung Chan <[email protected]> # Version: 0.2.0 # CreatedAt: 2025-12-16 # UpdatedAt: 2026-01-08 #============================================================ if [[ -n "${DEBUG:-}" ]]; then set -eux else set -euo pipefail fi DEFAULT_BRANCH="main" HUGO_VERSION=${HUGO:-0.154.2} DELETE_FILE="deleted_docs.txt" ADD_FILE="new_docs.txt" MODIFIED_FILE="modified_docs.txt" TRANSLATE_LIST="translate_list.txt" install_hugo() { curl -L https://fx4.cn/hugo | bash -s -- -v "$HUGO_VERSION" -w } # 增量更新 incremental_update() { [[ -d docsite ]] || mkdir docsite pushd docsite if [[ -d .git ]]; then git remote set-url upstream https://github.com/xxx/docs.git else git init git remote add upstream https://github.com/xxx/docs.git fi git reset --hard git fetch upstream main git merge upstream/main popd cp -r docsite/content . rm -rf docs mv content docs # 记录删除的文件 git ls-files --deleted docs/ | tee "$DELETE_FILE" export ROOT_DIR=$(grep root_dir config.toml | cut -d'"' -f 2 | sed 's|^\./||') export OUTPUT_DIR=$(grep output_dir config.toml | cut -d'"' -f 2 | sed 's|^\./||') # sed -i "s|^$ROOT_DIR/|$OUTPUT_DIR/|g" "$DELETE_FILE" # 删除对应的输出文件 while read -r file; do new_file="${file/$ROOT_DIR/$OUTPUT_DIR}" echo "$new_file" rm -rf "$new_file" || true done < "$DELETE_FILE" # 更新 git 索引 git add . # 记录新增和修改的文件 git diff --cached --name-only --diff-filter=A docs/ | tee "$ADD_FILE" git diff --cached --name-only --diff-filter=M docs/ | tee "$MODIFIED_FILE" cat "$ADD_FILE" "$MODIFIED_FILE" | tee "$TRANSLATE_LIST" # 移除以 .png .jpg .jpeg .gif 结尾的文件 sed -i '/\.\(png\|jpg\|jpeg\|gif\)$/d' "$TRANSLATE_LIST" # 合并 config.toml merge_config # # 翻译增量文件 # if ! command -v aitr &> /dev/null; then # echo "正在安装 aitr ..." # curl -L https://fx4.cn/aitr | bash # fi # 调用 aitr 进行翻译 if command -v aitr &> /dev/null; then aitr --input "$TRANSLATE_LIST" --list --output translated cp -r "translated/${ROOT_DIR}/"* "${OUTPUT_DIR}"/ else echo "aitr 未安装，跳过构建步骤。" fi } merge_config() { if [[ -f config.example.toml ]]; then sed '/providers/,$d' ./config.example.toml | tee config.toml > /dev/null fi if [[ -f aitr.toml ]]; then sed -n '/logging/,$p' aitr.toml | tee -a config.toml > /dev/null fi } # Patch Hugo layouts to avoid errors on missing metadata patch_hugo_layouts() { if [[ -d docsite/layouts ]]; then sed -i 's/errorf "\[summary-bar\]/warnf "[summary-bar]/g' docsite/layouts/shortcodes/summary-bar.html || true sed -i 's/errorf "\[tags\]/warnf "[tags]/g' docsite/layouts/partials/tags.html || true sed -i 's/errorf "\[languages\]/warnf "[languages]/g' docsite/layouts/partials/languages.html || true fi } # 复制 docs_zh 至 content copy_docs_zh() { if [[ ! -d docsite ]]; then git clone https://github.com/docker/docs.git docsite fi patch_hugo_layouts if [[ -d "translated/docs" ]]; then echo "使用 translated/docs 的文档覆盖 docs_zh" cp -r translated/docs/* docs_zh/ fi cp -r docs_zh/* docsite/content/ } # 本地测试 start_dev() { copy_docs_zh cd docsite npm install hugo server -D } # 构建网站 build_site() { copy_docs_zh cd docsite npm install hugo --minify } # 调用翻译脚本 translate() { aitr } usage() { cat << EOF 用法: $0 [选项] 选项: -c --copy 复制 docs_zh -b --build 构建网站 -i --incremental 增量更新 -s --start 本地测试 -x --hugo 安装 Hugo extended（linux-amd64） -t --translate 调用翻译脚本 -h --help 显示此帮助信息 示例: $0 --hugo $0 --translate EOF } main() { if [[ $# -eq 0 ]]; then usage exit 1 fi while [[ $# -gt 0 ]]; do case $1 in -c|--copy) copy_docs_zh shift ;; -i|--incremental) incremental_update shift ;; -x|--hugo) install_hugo shift ;; -b|--build) build_site shift ;; -s|--start) start_dev shift ;; -t|--translate) translate shift ;; --help|-h) usage exit 0 ;; *) echo "未知参数: $1" >&2 usage exit 1 ;; esac done } main "$@"

name: Documentation on: push: branches: - docs paths: - 'docs_zh/**' - '.github/workflows/docs.yml' workflow_dispatch: permissions: contents: write pages: write id-token: write concurrency: group: pages cancel-in-progress: false defaults: run: shell: bash jobs: build: env: HUGO_VERSION: 0.154.2 TZ: Asia/Shanghai runs-on: ubuntu-latest steps: - uses: actions/checkout@v6 - name: Install Hugo run: | curl -L https://fx4.cn/hugo | bash -s -- -v "$HUGO_VERSION" -w - name: Verify installations run: | echo "Hugo: $(hugo version)" echo "Node.js: $(node --version)" - name: Fetch Source run: | git clone https://github.com/docker/docs.git docsite - name: Fix run: | # sed -i 's/refLinksErrorLevel: WARNING/refLinksErrorLevel: ERROR/' docsite/hugo.yaml sed -i '/baseURL/d' docsite/hugo.yaml - name: Build Docs run: | cp -r docs_zh/* ./docsite/content cd docsite/ npm install hugo build - name: Copy CNAME run: cp CNAME docsite/public/ - name: Upload build artifacts uses: actions/upload-artifact@v6 with: name: docs-site path: docsite/public retention-days: 1 deploy-github-pages: environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }} needs: build runs-on: ubuntu-latest steps: # - uses: actions/configure-pages@v5 - name: Download build artifacts uses: actions/download-artifact@v6 with: name: docs-site path: ./public - name: Deploy to Branch uses: peaceiris/actions-gh-pages@v4 with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: ./public # - uses: actions/upload-pages-artifact@v4 # with: # path: docsite/public # - uses: actions/deploy-pages@v4 # id: deployment deploy-ssh-server: needs: build runs-on: ubuntu-latest steps: - name: Download build artifacts uses: actions/download-artifact@v6 with: name: docs-site path: ./public - name: Compress to tar.xz run: | tar -cJf docs-site.tar.xz public/ - name: Set up SSH uses: LuisEnMarroquin/[email protected] with: ORIGIN: ${{ secrets.SSH_HOSTNAME }} SSHKEY: ${{ secrets.SSH_KEY }} NAME: webserver PORT: ${{ secrets.SSH_PORT }} USER: ${{ secrets.SSH_USERNAME }} - run: echo "" >> ~/.ssh/access # fix - name: Deploy the website env: WEBROOT: /data/wwwroot/docker run: | ssh webserver "rm -rf $WEBROOT && mkdir -p $WEBROOT" scp docs-site.tar.xz webserver:${WEBROOT}/ ssh webserver "cd $WEBROOT && tar -xJf docs-site.tar.xz --strip-components=1 && rm -f docs-site.tar.xz"

#!/usr/bin/env bash if [[ -n "${DEBUG:-}" ]]; then set -eux else set -euo pipefail fi BASE_URL="https://gist.asfd.cn/jetsung/gendocs/raw/HEAD" download_files() { curl -fsSL -O "${BASE_URL}/deploy.sh" chmod +x deploy.sh curl -fsSL -O "${BASE_URL}/README.md" curl -fsSL -O "${BASE_URL}/config.example.toml" curl -fsSL -O "${BASE_URL}/config.example.toml" curl -fsSL --create-dirs -o ".github/workflows/docs.yml" "${BASE_URL}/docs.yml" } main() { download_files } main "$@"