# Python .venv/ build/ docsite/ translated/ tmp/ **.log **.txt !commit.txt aitr.toml config.toml

# 中文文档 本文档使用 AI 翻译 ## 项目流程 ### 首次使用 1. 创建空分支 ```bash git switch --orphan docs ``` 2. 首次提交 ```bash git add README.md git commit -am init git push origin docs ``` 3. 拉取上游源码 ```bash mkdir -p docsite git remote add upstream https://github.com/xxx/docs.git git reset --hard git fetch upstream main git merge upstream/main git rev-parse --short HEAD > ../commit.txt popd ``` 4. 复制源文档 ```bash rm -rf docs # cp -r docsite/docs . cp -r docsite/content . mv content docs ``` 5. 全量翻译 ```bash aitr ``` 6. 本地测试与构建 ```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 ```

# 教程 本项目使用的教程 ## 初始化项目 1. 创建空分支 ```bash # 新项目 git init git branch -m docs ``` ```bash # 已存在的项目，创建空分支 git switch --orphan docs ``` 2. 将本项目的文件下载至创建的翻译项目 ```bash curl -fsSL https://fx4.cn/gendocs | bash ``` 3. 更新上游项目链接 ```bash GIT_DOCS=含.git结尾的项目地址 sed -i "s#https://github.com/xxx/docs.git#${GIT_DOCS}#g" *.* sed -i "s#https://github.com/xxx/docs.git#${GIT_DOCS}#g" .github/workflows/docs.yml ``` 4. 设置项目地址 ```bash # 新项目 git remote add origin <https 或 git 地址> ``` ```bash # 已存在的项目 git remote set-url origin <https 或 git 地址> ```

# 根目录 - 包含需要翻译的 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 # 大文件拆分阈值 (单位：字符) max_chunk_size = 8192 # 系统提示词（支持多行，使用 """ 包裹） 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-27 #============================================================ if [[ -n "${DEBUG:-}" ]]; then set -eux else set -euo pipefail fi DEFAULT_BRANCH="${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" UPSTREAM_URL="${UPSTREAM_URL:-}" UPSTREAM_NAME="upstream" # 命令行参数 CUSTOM_BRANCH="" CUSTOM_UPSTREAM="" install_hugo() { echo "======================================" echo "📦 开始安装 Hugo" echo "======================================" echo "→ 目标版本: $HUGO_VERSION" echo "→ 正在下载并安装..." curl -L https://fx4.cn/hugo | bash -s -- -v "$HUGO_VERSION" -w echo "✓ Hugo 安装完成" hugo version echo "======================================" } setup_config() { echo "======================================" echo "⚙️ 开始设置配置文件" echo "======================================" if [[ -f config.example.toml ]]; then echo "→ 从 config.example.toml 提取基础配置..." sed '/providers/,$d' ./config.example.toml | tee config.toml > /dev/null echo "✓ 基础配置提取完成" else echo "⚠️ config.example.toml 不存在，跳过基础配置" fi if [[ -f aitr.toml ]]; then echo "→ 从 aitr.toml 追加日志配置..." sed -n '/logging/,$p' aitr.toml | tee -a config.toml > /dev/null echo "✓ 日志配置追加完成" else echo "⚠️ aitr.toml 不存在，跳过日志配置" fi echo "✓ 配置文件设置完成" echo "======================================" } sync_source() { echo "======================================" echo "📚 开始同步源文档" echo "======================================" echo "→ 准备工作目录..." [[ -d docsite ]] || mkdir docsite pushd docsite > /dev/null if [[ ! -d .git ]]; then echo "→ 初始化 git 仓库..." git init echo "→ 添加 upstream remote: ${UPSTREAM_URL}" git remote add "${UPSTREAM_NAME}" "${UPSTREAM_URL}" else # 检查是否已经存在 upstream if ! git remote get-url "${UPSTREAM_NAME}" >/dev/null 2>&1; then echo "→ 添加 upstream remote..." git remote add "${UPSTREAM_NAME}" "${UPSTREAM_URL}" else current_url=$(git remote get-url "${UPSTREAM_NAME}") if [[ "${current_url}" != "${UPSTREAM_URL}" ]]; then echo "→ 更新 upstream URL" echo " 旧 URL: ${current_url}" echo " 新 URL: ${UPSTREAM_URL}" git remote set-url "${UPSTREAM_NAME}" "${UPSTREAM_URL}" fi fi fi echo "→ 正在拉取最新代码..." echo " 分支: $DEFAULT_BRANCH" echo " Remote: ${UPSTREAM_NAME}" git reset --hard git fetch "${UPSTREAM_NAME}" "${DEFAULT_BRANCH}" git merge "${UPSTREAM_NAME}"/"${DEFAULT_BRANCH}" COMMIT_SHA=$(git rev-parse --short HEAD) echo "$COMMIT_SHA" > ../commit.txt echo "✓ 代码同步完成 (commit: $COMMIT_SHA)" popd > /dev/null echo "→ 清理旧文档目录..." rm -rf docs echo "→ 复制源文档..." if [[ -d docsite/content ]]; then cp -r docsite/content . mv content docs echo "✓ 已从 docsite/content 复制文档" elif [[ -d docsite/docs ]]; then cp -r docsite/docs . echo "✓ 已从 docsite/docs 复制文档" else echo "❌ docsite 目录下没有 content 或 docs 目录，无法同步文档。" >&2 exit 1 fi echo "✓ 源文档同步完成" echo "======================================" } # 增量更新 update_incremental() { echo "======================================" echo "🔄 开始增量更新流程" echo "======================================" if [[ -z "$UPSTREAM_URL" ]]; then echo "❌ UPSTREAM_URL 未设置，无法进行增量更新。" >&2 exit 1 fi echo "→ 步骤 1/6: 同步源文档" sync_source # 记录删除的文件 echo "→ 步骤 2/6: 检测已删除的文件" echo " 正在扫描已删除的文档..." git ls-files --deleted docs/ | tee "$DELETE_FILE" ROOT_DIR=$(grep root_dir config.toml | cut -d'"' -f 2 | sed 's|^\./||') export ROOT_DIR OUTPUT_DIR=$(grep output_dir config.toml | cut -d'"' -f 2 | sed 's|^\./||') export OUTPUT_DIR echo " 根目录: $ROOT_DIR" echo " 输出目录: $OUTPUT_DIR" # sed -i "s|^$ROOT_DIR/|$OUTPUT_DIR/|g" "$DELETE_FILE" # 删除对应的输出文件 echo " 正在清理对应的输出文件..." while read -r file; do new_file="${file/$ROOT_DIR/$OUTPUT_DIR}" echo " 删除: $new_file" rm -rf "$new_file" || true done < "$DELETE_FILE" echo "✓ 已清理删除的文件" # 更新 git 索引 echo "→ 步骤 3/6: 更新 git 索引" git add . # 记录新增和修改的文件 echo " 正在检测新增的文件..." git diff --cached --name-only --diff-filter=A docs/ | tee "$ADD_FILE" echo " 正在检测修改的文件..." git diff --cached --name-only --diff-filter=M docs/ | tee "$MODIFIED_FILE" echo "→ 步骤 4/6: 生成待翻译文件列表" cat "$ADD_FILE" "$MODIFIED_FILE" | tee "$TRANSLATE_LIST" # 移除以 .png .jpg .jpeg .gif .svg 结尾的文件 echo " 过滤图片文件..." sed -i '/\.\(png\|jpg\|jpeg\|gif\|svg\)$/d' "$TRANSLATE_LIST" echo "✓ 已生成待翻译文件列表: $TRANSLATE_LIST" echo "→ 步骤 5/6: 设置配置文件" setup_config # # 翻译增量文件 # if ! command -v aitr &> /dev/null; then # echo "正在安装 aitr ..." # curl -L https://fx4.cn/aitr | bash # fi # 调用 aitr 进行翻译 echo "→ 步骤 6/6: 执行翻译" if command -v aitr &> /dev/null; then echo " 正在调用 aitr 翻译文件..." aitr --input "$TRANSLATE_LIST" --list --output translated echo " 正在复制翻译结果到输出目录..." cp -r "translated/${ROOT_DIR}/"* "${OUTPUT_DIR}"/ echo "✓ 翻译完成" else echo "⚠️ aitr 未安装，跳过翻译步骤。" fi echo "======================================" echo "✓ 增量更新完成" echo "======================================" } # 部署 docs_zh 到 docsite deploy_docs_zh() { echo "======================================" echo "📋 开始部署 docs_zh 到 docsite" echo "======================================" if [[ ! -d docsite ]]; then if [[ -z "$UPSTREAM_URL" ]]; then echo "❌ UPSTREAM_URL 未设置，无法克隆文档站点。" >&2 exit 1 fi echo "→ docsite 目录不存在，正在克隆..." git clone "$UPSTREAM_URL" docsite echo "✓ 克隆完成" fi if [[ -d "translated/docs" ]]; then echo "→ 检测到 translated/docs，正在覆盖 docs_zh..." cp -r translated/docs/* docs_zh/ echo "✓ 已覆盖 docs_zh" fi if [[ ! -d docs_zh ]]; then echo "❌ docs_zh 目录不存在，无法部署。" >&2 exit 1 fi echo "→ 正在部署 docs_zh 到 docsite..." if [[ -d docsite/content ]]; then cp -r docs_zh/* ./docsite/content/ echo "✓ 已部署到 docsite/content/" elif [[ -d docsite/docs ]]; then cp -r docs_zh/* ./docsite/docs/ echo "✓ 已部署到 docsite/docs/" else echo "❌ docsite 目录下没有 content 或 docs 目录，无法部署。" >&2 exit 1 fi echo "======================================" echo "✓ 文档部署完成" echo "======================================" } # 调用翻译脚本 translate() { echo "======================================" echo "🌐 开始执行翻译" echo "======================================" if ! command -v aitr &> /dev/null; then echo "❌ aitr 未安装，请先安装 aitr。" >&2 exit 1 fi echo "→ 正在调用 aitr 翻译工具..." aitr echo "======================================" echo "✓ 翻译完成" echo "======================================" } usage() { cat << EOF 用法: $0 [选项] 选项: -d --deploy 部署 docs_zh 到 docsite -c --config 设置配置文件 -s --sync 同步源文档 -u --update 增量更新（同步+翻译） -t --translate 执行翻译 -b --branch 指定分支 (默认: main) -U --upstream 指定上游 URL -h --help 显示此帮助信息 示例: $0 --translate $0 --update $0 --sync --branch develop $0 --update --upstream https://github.com/user/repo.git EOF } main() { echo "======================================" echo "🚀 部署脚本启动" echo "======================================" if [[ $# -eq 0 ]]; then echo "❌ 未指定任何操作" >&2 usage exit 1 fi # 先解析所有参数 local actions=() while [[ $# -gt 0 ]]; do case $1 in -b|--branch) CUSTOM_BRANCH="$2" shift 2 ;; -U|--upstream) CUSTOM_UPSTREAM="$2" shift 2 ;; -d|--deploy) actions+=("deploy") shift ;; -c|--config) actions+=("config") shift ;; -s|--sync) actions+=("sync") shift ;; -u|--update) actions+=("update") shift ;; -t|--translate) actions+=("translate") shift ;; --help|-h) usage exit 0 ;; *) echo "❌ 未知参数: $1" >&2 usage exit 1 ;; esac done # 应用自定义参数 if [[ -n "$CUSTOM_BRANCH" ]]; then DEFAULT_BRANCH="$CUSTOM_BRANCH" fi if [[ -n "$CUSTOM_UPSTREAM" ]]; then UPSTREAM_URL="$CUSTOM_UPSTREAM" fi echo "当前分支: $DEFAULT_BRANCH" echo "Hugo 版本: $HUGO_VERSION" if [[ -n "$UPSTREAM_URL" ]]; then echo "Upstream URL: $UPSTREAM_URL" else echo "Upstream URL: (未设置)" fi echo "======================================" # 执行操作 for action in "${actions[@]}"; do case $action in deploy) echo "→ 执行操作: 部署 docs_zh" deploy_docs_zh ;; config) echo "→ 执行操作: 设置配置文件" setup_config ;; sync) echo "→ 执行操作: 同步源文档" sync_source ;; update) echo "→ 执行操作: 增量更新" update_incremental ;; translate) echo "→ 执行操作: 执行翻译" translate ;; esac done echo "======================================" echo "✓ 部署脚本执行完成" echo "======================================" } 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/xxx/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 README.md "${BASE_URL}/DOCS.md" curl -fsSL -O "${BASE_URL}/config.example.toml" curl -fsSL -O "${BASE_URL}/config.example.toml" curl -fsSL -O "${BASE_URL}/.gitignore" curl -fsSL --create-dirs -o ".github/workflows/docs.yml" "${BASE_URL}/docs.yml" } main() { download_files if [[ ! -f CNAME ]]; then echo "" > CNAME fi } main "$@"