From b87a4f0abeeb70bd2b10a41e9bc504267deaaa2b Mon Sep 17 00:00:00 2001
From: Alter-xyz <88554920+alterxyz@users.noreply.github.com>
Date: Mon, 21 Jul 2025 14:41:23 +0800
Subject: [PATCH] docs: translate readme

---
 tools/translate/README.md    | 124 +++++++++++++++++++++++++++++++++
 tools/translate/README_CN.md | 131 +++++++++++++++++++++++++++++++++++
 tools/translate/README_JA.md | 125 +++++++++++++++++++++++++++++++++
 3 files changed, 380 insertions(+)
 create mode 100644 tools/translate/README_CN.md
 create mode 100644 tools/translate/README_JA.md

diff --git a/tools/translate/README.md b/tools/translate/README.md
index 8b137891..169cc72d 100644
--- a/tools/translate/README.md
+++ b/tools/translate/README.md
@@ -1 +1,125 @@
+# Automatic Document Translation
 
+Multi-language document auto-translation system based on GitHub Actions and Dify AI, supporting English, Chinese, and Japanese trilingual translation.
+
+> **Other Languages**: [中文](README.md) | [日本語](README_JA.md)
+
+## How It Works
+
+1. **Trigger Condition**: Automatically runs when pushing to non-main branches
+2. **Smart Detection**: Automatically identifies modified `.md/.mdx` files and determines source language
+3. **Translation Logic**:
+    - ✅ Translates new documents to other languages
+    - ❌ Skips existing translation files (avoids overwriting manual edits)
+4. **Auto Commit**: Translation results are automatically pushed to the current branch
+
+## System Features
+
+- 🌐 **Multi-language Support**: Configuration-based language mapping, theoretically supports any language extension
+- 📚 **Terminology Consistency**: Built-in professional terminology database, LLM intelligently follows terminology to ensure unified technical vocabulary translation
+- 🔄 **Concurrent Processing**: Smart concurrency control, translates multiple target languages simultaneously
+- 🛡️ **Fault Tolerance**: 3-retry mechanism with exponential backoff strategy
+- ⚡ **Incremental Translation**: Only processes changed files, avoids redundant work
+- 🧠 **High-Performance Models**: Uses high-performance LLM models to ensure translation quality
+
+## Usage
+
+### For Document Writers
+
+1. Write/modify documents in any language directory
+2. Push to branch (non-main)
+3. Wait 0.5-1 minute for automatic translation completion
+4. **View Translation Results**:
+    - Create Pull Request for local viewing and subsequent editing
+    - Or view Actions push commit details on GitHub to directly review translation quality
+
+### Supported Language Directories
+
+- **General Documentation**: `en/` ↔ `zh-hans/` ↔ `ja-jp/`
+- **Plugin Development Documentation**: `plugin-dev-en/` ↔ `plugin-dev-zh/` ↔ `plugin-dev-ja/`
+
+Note: System architecture supports extending more languages, just modify configuration files
+
+## Important Notes
+
+- System only translates new documents, won't overwrite existing translations
+- To update existing translations, manually delete target files then retrigger
+- Terminology translation follows professional vocabulary in `termbase_i18n.md`, LLM has intelligent terminology recognition capabilities
+- Translation quality depends on configured high-performance models, recommend using high-performance base models in Dify Studio
+
+### System Configuration
+
+#### Terminology Database
+
+Edit `tools/translate/termbase_i18n.md` to update professional terminology translation reference table.
+
+#### Translation Model
+
+Visit Dify Studio to adjust translation prompts or change base models.
+
+---
+
+## 🔧 Development and Deployment Configuration
+
+### Local Development Environment
+
+#### 1. Create Virtual Environment
+
+```bash
+# Create virtual environment
+python -m venv venv
+
+# Activate virtual environment
+# macOS/Linux:
+source venv/bin/activate
+# Windows:
+# venv\Scripts\activate
+```
+
+#### 2. Install Dependencies
+
+```bash
+pip install -r tools/translate/requirements.txt
+```
+
+#### 3. Configure API Key
+
+Create `.env` file in `tools/translate/` directory:
+
+```bash
+DIFY_API_KEY=your_dify_api_key_here
+```
+
+#### 4. Run Translation
+
+```bash
+# Interactive mode (recommended for beginners)
+python tools/translate/main.py
+
+# Command line mode (specify file)
+python tools/translate/main.py path/to/file.mdx [DIFY_API_KEY]
+```
+
+> **Tip**: Right-click in IDE and select "Copy Relative Path" to use as parameter
+
+### Deploy to Other Repositories
+
+1. **Copy Files**:
+    - `.github/workflows/translate.yml`
+    - `tools/translate/` entire directory
+
+2. **Configure GitHub Secrets**:
+    - Repository Settings → Secrets and variables → Actions
+    - Add `DIFY_API_KEY` secret
+
+3. **Test**: Modify documents in branch to verify automatic translation functionality
+
+### Technical Details
+
+- Concurrent translation limited to 2 tasks to avoid excessive API pressure
+- Supports `.md` and `.mdx` file formats
+- Based on Dify API workflow mode
+
+## TODO
+
+- [ ] Support updating existing translations
diff --git a/tools/translate/README_CN.md b/tools/translate/README_CN.md
new file mode 100644
index 00000000..b7ff2352
--- /dev/null
+++ b/tools/translate/README_CN.md
@@ -0,0 +1,131 @@
+# 自动翻译文档
+
+基于 GitHub Actions 和 Dify AI 的文档自动翻译系统，支持英文、中文、日文三语互译。
+
+> **其他语言**: [English](README_EN.md) | [日本語](README_JA.md)
+
+## 工作原理
+
+1. **触发条件**: 推送到非 main 分支时自动运行
+2. **智能检测**: 自动识别修改的 `.md/.mdx` 文件并判断源语言
+3. **翻译逻辑**:
+    - ✅ 翻译新增文档到其他语言
+    - ❌ 跳过已存在的翻译文件（避免覆盖手动修改）
+4. **自动提交**: 翻译结果自动推送到当前分支
+
+## 系统特性
+
+- 🌐 **多语言支持**: 基于配置的语言映射，理论上支持任意语言扩展
+- 📚 **术语表一致性**: 内置专业术语库，LLM 智能遵循术语表确保技术词汇翻译统一
+- 🔄 **并发处理**: 智能并发控制，同时翻译多个目标语言
+- 🛡️ **容错机制**: 3 次重试机制，指数退避策略
+- ⚡ **增量翻译**: 只处理变更文件，避免重复工作
+- 🧠 **高性能模型**: 使用性能较强的 LLM 模型确保翻译质量
+
+## 使用方法
+
+### 文档编写者
+
+1. 在任意语言目录下编写/修改文档
+2. 推送到分支（非 main）
+3. 等待 0.5-1 分钟自动翻译完成
+4. **查看翻译结果**:
+    - 创建 Pull Request 进行本地查看和后续编辑
+    - 或在 GitHub 查看 Actions 推送的 commit 详情，直接审查翻译质量
+
+### 支持的语言目录
+
+- **通用文档**: `en/` ↔ `zh-hans/` ↔ `ja-jp/`
+- **插件开发文档**: `plugin-dev-en/` ↔ `plugin-dev-zh/` ↔ `plugin-dev-ja/`
+
+注：系统架构支持扩展更多语言，只需修改配置文件
+
+## 注意事项
+
+- 系统只翻译新文档，不会覆盖已存在的翻译
+- 如需更新现有翻译，请手动删除目标文件后重新触发
+- 术语翻译遵循 `termbase_i18n.md` 中的专业词汇表，LLM 具备智能术语识别能力
+- 翻译质量依赖于配置的高性能模型，建议在 Dify Studio 中使用性能较强的基座模型
+
+### 系统配置
+
+#### 术语表
+
+编辑 `tools/translate/termbase_i18n.md` 更新专业术语翻译对照表。
+
+#### 翻译模型
+
+访问 Dify Studio 调整翻译 prompt 或更换基座模型。
+
+---
+
+---
+
+---
+
+## 🔧 开发和部署配置
+
+### 本地开发环境
+
+#### 1. 创建虚拟环境
+
+```bash
+# 创建虚拟环境
+python -m venv venv
+
+# 激活虚拟环境
+# macOS/Linux:
+source venv/bin/activate
+# Windows:
+# venv\Scripts\activate
+```
+
+#### 2. 安装依赖
+
+```bash
+pip install -r tools/translate/requirements.txt
+```
+
+#### 3. 配置 API 密钥
+
+在 `tools/translate/` 目录下创建 `.env` 文件：
+
+```bash
+DIFY_API_KEY=your_dify_api_key_here
+```
+
+#### 4. 运行翻译
+
+```bash
+# 交互模式（推荐新手使用）
+python tools/translate/main.py
+
+# 命令行模式（指定文件）
+python tools/translate/main.py path/to/file.mdx [DIFY_API_KEY]
+```
+
+> **提示**: 在 IDE 中右键选择"复制相对路径"作为参数传入
+
+### 部署到其他仓库
+
+1. **复制文件**:
+
+    - `.github/workflows/translate.yml`
+    - `tools/translate/` 整个目录
+
+2. **配置 GitHub Secrets**:
+
+    - Repository Settings → Secrets and variables → Actions
+    - 添加 `DIFY_API_KEY` 密钥
+
+3. **测试**: 在分支中修改文档，验证自动翻译功能
+
+### 技术细节
+
+- 并发翻译限制为 2 个任务，避免 API 压力过大
+- 支持 `.md` 和 `.mdx` 文件格式
+- 基于 Dify API 的 workflow 模式
+
+## TODO
+
+- [ ] 支持更新现有翻译
diff --git a/tools/translate/README_JA.md b/tools/translate/README_JA.md
new file mode 100644
index 00000000..92a2595b
--- /dev/null
+++ b/tools/translate/README_JA.md
@@ -0,0 +1,125 @@
+# 自動ドキュメント翻訳
+
+GitHub Actions と Dify AI に基づく多言語ドキュメント自動翻訳システム。英語、中国語、日本語の三言語相互翻訳をサポートします。
+
+> **他の言語**: [中文](README.md) | [English](README_EN.md)
+
+## 動作原理
+
+1. **トリガー条件**: main以外のブランチにプッシュすると自動実行
+2. **スマート検出**: 変更された `.md/.mdx` ファイルを自動識別し、元言語を判定
+3. **翻訳ロジック**:
+    - ✅ 新規ドキュメントを他の言語に翻訳
+    - ❌ 既存の翻訳ファイルはスキップ（手動編集の上書きを回避）
+4. **自動コミット**: 翻訳結果を現在のブランチに自動プッシュ
+
+## システム特徴
+
+- 🌐 **多言語サポート**: 設定ベースの言語マッピング、理論的には任意の言語拡張をサポート
+- 📚 **用語の一貫性**: 内蔵専門用語データベース、LLMが用語表を賢く遵守し技術用語翻訳の統一を確保
+- 🔄 **並行処理**: スマート並行制御、複数のターゲット言語を同時翻訳
+- 🛡️ **フォールトトレランス**: 3回再試行メカニズム、指数バックオフ戦略
+- ⚡ **増分翻訳**: 変更ファイルのみ処理、重複作業を回避
+- 🧠 **高性能モデル**: 高性能LLMモデルを使用し翻訳品質を確保
+
+## 使用方法
+
+### ドキュメント作成者向け
+
+1. 任意の言語ディレクトリでドキュメントを作成/修正
+2. ブランチ（main以外）にプッシュ
+3. 0.5-1分待って自動翻訳完了
+4. **翻訳結果の確認**:
+    - Pull Requestを作成してローカル確認と後続編集
+    - またはGitHubでActionsプッシュコミット詳細を確認し、翻訳品質を直接レビュー
+
+### サポート言語ディレクトリ
+
+- **一般ドキュメント**: `en/` ↔ `zh-hans/` ↔ `ja-jp/`
+- **プラグイン開発ドキュメント**: `plugin-dev-en/` ↔ `plugin-dev-zh/` ↔ `plugin-dev-ja/`
+
+注：システムアーキテクチャはより多くの言語拡張をサポート、設定ファイルの修正のみで可能
+
+## 注意事項
+
+- システムは新規ドキュメントのみ翻訳、既存翻訳は上書きしません
+- 既存翻訳を更新する場合、対象ファイルを手動削除してから再トリガー
+- 用語翻訳は `termbase_i18n.md` の専門用語表に従い、LLMはスマート用語認識機能を持つ
+- 翻訳品質は設定された高性能モデルに依存、Dify Studioで高性能ベースモデル使用を推奨
+
+### システム設定
+
+#### 用語データベース
+
+`tools/translate/termbase_i18n.md` を編集して専門用語翻訳対照表を更新。
+
+#### 翻訳モデル
+
+Dify Studio で翻訳プロンプトの調整やベースモデルの変更。
+
+---
+
+## 🔧 開発とデプロイ設定
+
+### ローカル開発環境
+
+#### 1. 仮想環境作成
+
+```bash
+# 仮想環境作成
+python -m venv venv
+
+# 仮想環境アクティベート
+# macOS/Linux:
+source venv/bin/activate
+# Windows:
+# venv\Scripts\activate
+```
+
+#### 2. 依存関係インストール
+
+```bash
+pip install -r tools/translate/requirements.txt
+```
+
+#### 3. APIキー設定
+
+`tools/translate/` ディレクトリに `.env` ファイルを作成：
+
+```bash
+DIFY_API_KEY=your_dify_api_key_here
+```
+
+#### 4. 翻訳実行
+
+```bash
+# インタラクティブモード（初心者推奨）
+python tools/translate/main.py
+
+# コマンドラインモード（ファイル指定）
+python tools/translate/main.py path/to/file.mdx [DIFY_API_KEY]
+```
+
+> **ヒント**: IDEで右クリック「相対パスをコピー」をパラメータとして使用
+
+### 他のリポジトリへのデプロイ
+
+1. **ファイルコピー**:
+    - `.github/workflows/translate.yml`
+    - `tools/translate/` ディレクトリ全体
+
+2. **GitHub Secrets設定**:
+    - Repository Settings → Secrets and variables → Actions
+    - `DIFY_API_KEY` シークレットを追加
+
+3. **テスト**: ブランチでドキュメント修正し、自動翻訳機能を検証
+
+### 技術詳細
+
+- 並行翻訳は2タスクに制限、過度なAPI圧迫を回避
+- `.md` と `.mdx` ファイル形式をサポート
+- Dify API ワークフローモードベース
+
+## TODO
+
+- [ ] 既存翻訳の更新サポート