Skip to content

Commit b4bca61

Browse files
alterxyzalterxyz
committed
feat: auto translate
Powered By Dify
1 parent a6647b3 commit b4bca61

9 files changed

Lines changed: 951 additions & 0 deletions

File tree

‎.github/workflows/translate.yml‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
name: Auto Translate Docs
2+
3+
on:
4+
push:
5+
branches-ignore:
6+
- 'main'
7+
8+
jobs:
9+
translate:
10+
runs-on: ubuntu-latest
11+
permissions:
12+
contents: write
13+
steps:
14+
- name: Checkout repository
15+
uses: actions/checkout@v4
16+
with:
17+
fetch-depth: 0 # Fetches all history for git diff
18+
token: ${{ secrets.GITHUB_TOKEN }}
19+
20+
- name: Set up Python
21+
uses: actions/setup-python@v4
22+
with:
23+
python-version: '3.9'
24+
25+
- name: Install dependencies
26+
run: pip install httpx aiofiles python-dotenv
27+
28+
- name: Get changed markdown files
29+
id: changed-files
30+
run: |
31+
# Get the list of changed files between the current and previous commit
32+
# We filter for .md and .mdx files that are inside the language directories
33+
files=$(git diff --name-only ${{ github.event.before }} ${{ github.sha }} | grep -E '^(en|zh-hans|ja-jp|plugin-dev-en|plugin-dev-zh|plugin-dev-ja)/.*(\.md|\.mdx)$' || true)
34+
if [[ -z "$files" ]]; then
35+
echo "No markdown files to translate."
36+
echo "files=" >> $GITHUB_OUTPUT
37+
else
38+
# The script expects absolute paths, but we run it from the root, so relative is fine.
39+
echo "files<<EOF" >> $GITHUB_OUTPUT
40+
echo "$files" >> $GITHUB_OUTPUT
41+
echo "EOF" >> $GITHUB_OUTPUT
42+
fi
43+
44+
- name: Run translation script
45+
if: steps.changed-files.outputs.files
46+
env:
47+
DIFY_API_KEY: ${{ secrets.DIFY_API_KEY }}
48+
run: |
49+
echo "Files to translate:"
50+
echo "${{ steps.changed-files.outputs.files }}"
51+
52+
echo "${{ steps.changed-files.outputs.files }}" | while IFS= read -r file; do
53+
if [[ -n "$file" ]]; then
54+
echo "Translating $file..."
55+
python tools/translate/main.py "$file" "$DIFY_API_KEY"
56+
fi
57+
done
58+
59+
- name: Commit and push changes
60+
run: |
61+
git config --global user.name 'github-actions[bot]'
62+
git config --global user.email 'github-actions[bot]@users.noreply.github.com'
63+
# Check if there are any changes to commit
64+
if [[ -n $(git status --porcelain) ]]; then
65+
git add .
66+
git commit -m "docs: auto-translate documentation"
67+
# Push to the same branch the workflow was triggered from
68+
git push origin HEAD:${{ github.ref_name }}
69+
echo "Translated files have been pushed to the branch."
70+
else
71+
echo "No new translations to commit."
72+
fi

‎tools/translate/.env.example‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
dify_api_key=your_dify_api_key_here

‎tools/translate/.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
.env

‎tools/translate/README.md‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
# Automatic Document Translation
2+
3+
Multi-language document auto-translation system based on GitHub Actions and Dify AI, supporting English, Chinese, and Japanese trilingual translation.
4+
5+
> **Other Languages**: [中文](README.md) | [日本語](README_JA.md)
6+
7+
## How It Works
8+
9+
1. **Trigger Condition**: Automatically runs when pushing to non-main branches
10+
2. **Smart Detection**: Automatically identifies modified `.md/.mdx` files and determines source language
11+
3. **Translation Logic**:
12+
- ✅ Translates new documents to other languages
13+
- ❌ Skips existing translation files (avoids overwriting manual edits)
14+
4. **Auto Commit**: Translation results are automatically pushed to the current branch
15+
16+
## System Features
17+
18+
- 🌐 **Multi-language Support**: Configuration-based language mapping, theoretically supports any language extension
19+
- 📚 **Terminology Consistency**: Built-in professional terminology database, LLM intelligently follows terminology to ensure unified technical vocabulary translation
20+
- 🔄 **Concurrent Processing**: Smart concurrency control, translates multiple target languages simultaneously
21+
- 🛡️ **Fault Tolerance**: 3-retry mechanism with exponential backoff strategy
22+
- ⚡ **Incremental Translation**: Only processes changed files, avoids redundant work
23+
- 🧠 **High-Performance Models**: Uses high-performance LLM models to ensure translation quality
24+
25+
## Usage
26+
27+
### For Document Writers
28+
29+
1. Write/modify documents in any language directory
30+
2. Push to branch (non-main)
31+
3. Wait 0.5-1 minute for automatic translation completion
32+
4. **View Translation Results**:
33+
- Create Pull Request for local viewing and subsequent editing
34+
- Or view Actions push commit details on GitHub to directly review translation quality
35+
36+
### Supported Language Directories
37+
38+
- **General Documentation**: `en/` ↔ `zh-hans/` ↔ `ja-jp/`
39+
- **Plugin Development Documentation**: `plugin-dev-en/` ↔ `plugin-dev-zh/` ↔ `plugin-dev-ja/`
40+
41+
Note: System architecture supports extending more languages, just modify configuration files
42+
43+
## Important Notes
44+
45+
- System only translates new documents, won't overwrite existing translations
46+
- To update existing translations, manually delete target files then retrigger
47+
- Terminology translation follows professional vocabulary in `termbase_i18n.md`, LLM has intelligent terminology recognition capabilities
48+
- Translation quality depends on configured high-performance models, recommend using high-performance base models in Dify Studio
49+
50+
### System Configuration
51+
52+
#### Terminology Database
53+
54+
Edit `tools/translate/termbase_i18n.md` to update professional terminology translation reference table.
55+
56+
#### Translation Model
57+
58+
Visit Dify Studio to adjust translation prompts or change base models.
59+
60+
---
61+
62+
## 🔧 Development and Deployment Configuration
63+
64+
### Local Development Environment
65+
66+
#### 1. Create Virtual Environment
67+
68+
```bash
69+
# Create virtual environment
70+
python -m venv venv
71+
72+
# Activate virtual environment
73+
# macOS/Linux:
74+
source venv/bin/activate
75+
# Windows:
76+
# venv\Scripts\activate
77+
```
78+
79+
#### 2. Install Dependencies
80+
81+
```bash
82+
pip install -r tools/translate/requirements.txt
83+
```
84+
85+
#### 3. Configure API Key
86+
87+
Create `.env` file in `tools/translate/` directory:
88+
89+
```bash
90+
DIFY_API_KEY=your_dify_api_key_here
91+
```
92+
93+
#### 4. Run Translation
94+
95+
```bash
96+
# Interactive mode (recommended for beginners)
97+
python tools/translate/main.py
98+
99+
# Command line mode (specify file)
100+
python tools/translate/main.py path/to/file.mdx [DIFY_API_KEY]
101+
```
102+
103+
> **Tip**: Right-click in IDE and select "Copy Relative Path" to use as parameter
104+
105+
### Deploy to Other Repositories
106+
107+
1. **Copy Files**:
108+
- `.github/workflows/translate.yml`
109+
- `tools/translate/` entire directory
110+
111+
2. **Configure GitHub Secrets**:
112+
- Repository Settings → Secrets and variables → Actions
113+
- Add `DIFY_API_KEY` secret
114+
115+
3. **Test**: Modify documents in branch to verify automatic translation functionality
116+
117+
### Technical Details
118+
119+
- Concurrent translation limited to 2 tasks to avoid excessive API pressure
120+
- Supports `.md` and `.mdx` file formats
121+
- Based on Dify API workflow mode
122+
123+
## TODO
124+
125+
- [ ] Support updating existing translations

‎tools/translate/README_CN.md‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
# 自动翻译文档
2+
3+
基于 GitHub Actions 和 Dify AI 的文档自动翻译系统，支持英文、中文、日文三语互译。
4+
5+
> **其他语言**: [English](README_EN.md) | [日本語](README_JA.md)
6+
7+
## 工作原理
8+
9+
1. **触发条件**: 推送到非 main 分支时自动运行
10+
2. **智能检测**: 自动识别修改的 `.md/.mdx` 文件并判断源语言
11+
3. **翻译逻辑**:
12+
- ✅ 翻译新增文档到其他语言
13+
- ❌ 跳过已存在的翻译文件（避免覆盖手动修改）
14+
4. **自动提交**: 翻译结果自动推送到当前分支
15+
16+
## 系统特性
17+
18+
- 🌐 **多语言支持**: 基于配置的语言映射，理论上支持任意语言扩展
19+
- 📚 **术语表一致性**: 内置专业术语库，LLM 智能遵循术语表确保技术词汇翻译统一
20+
- 🔄 **并发处理**: 智能并发控制，同时翻译多个目标语言
21+
- 🛡️ **容错机制**: 3 次重试机制，指数退避策略
22+
- ⚡ **增量翻译**: 只处理变更文件，避免重复工作
23+
- 🧠 **高性能模型**: 使用性能较强的 LLM 模型确保翻译质量
24+
25+
## 使用方法
26+
27+
### 文档编写者
28+
29+
1. 在任意语言目录下编写/修改文档
30+
2. 推送到分支（非 main）
31+
3. 等待 0.5-1 分钟自动翻译完成
32+
4. **查看翻译结果**:
33+
- 创建 Pull Request 进行本地查看和后续编辑
34+
- 或在 GitHub 查看 Actions 推送的 commit 详情，直接审查翻译质量
35+
36+
### 支持的语言目录
37+
38+
- **通用文档**: `en/` ↔ `zh-hans/` ↔ `ja-jp/`
39+
- **插件开发文档**: `plugin-dev-en/` ↔ `plugin-dev-zh/` ↔ `plugin-dev-ja/`
40+
41+
注：系统架构支持扩展更多语言，只需修改配置文件
42+
43+
## 注意事项
44+
45+
- 系统只翻译新文档，不会覆盖已存在的翻译
46+
- 如需更新现有翻译，请手动删除目标文件后重新触发
47+
- 术语翻译遵循 `termbase_i18n.md` 中的专业词汇表，LLM 具备智能术语识别能力
48+
- 翻译质量依赖于配置的高性能模型，建议在 Dify Studio 中使用性能较强的基座模型
49+
50+
### 系统配置
51+
52+
#### 术语表
53+
54+
编辑 `tools/translate/termbase_i18n.md` 更新专业术语翻译对照表。
55+
56+
#### 翻译模型
57+
58+
访问 Dify Studio 调整翻译 prompt 或更换基座模型。
59+
60+
---
61+
62+
---
63+
64+
---
65+
66+
## 🔧 开发和部署配置
67+
68+
### 本地开发环境
69+
70+
#### 1. 创建虚拟环境
71+
72+
```bash
73+
# 创建虚拟环境
74+
python -m venv venv
75+
76+
# 激活虚拟环境
77+
# macOS/Linux:
78+
source venv/bin/activate
79+
# Windows:
80+
# venv\Scripts\activate
81+
```
82+
83+
#### 2. 安装依赖
84+
85+
```bash
86+
pip install -r tools/translate/requirements.txt
87+
```
88+
89+
#### 3. 配置 API 密钥
90+
91+
在 `tools/translate/` 目录下创建 `.env` 文件：
92+
93+
```bash
94+
DIFY_API_KEY=your_dify_api_key_here
95+
```
96+
97+
#### 4. 运行翻译
98+
99+
```bash
100+
# 交互模式（推荐新手使用）
101+
python tools/translate/main.py
102+
103+
# 命令行模式（指定文件）
104+
python tools/translate/main.py path/to/file.mdx [DIFY_API_KEY]
105+
```
106+
107+
> **提示**: 在 IDE 中右键选择"复制相对路径"作为参数传入
108+
109+
### 部署到其他仓库
110+
111+
1. **复制文件**:
112+
113+
- `.github/workflows/translate.yml`
114+
- `tools/translate/` 整个目录
115+
116+
2. **配置 GitHub Secrets**:
117+
118+
- Repository Settings → Secrets and variables → Actions
119+
- 添加 `DIFY_API_KEY` 密钥
120+
121+
3. **测试**: 在分支中修改文档，验证自动翻译功能
122+
123+
### 技术细节
124+
125+
- 并发翻译限制为 2 个任务，避免 API 压力过大
126+
- 支持 `.md` 和 `.mdx` 文件格式
127+
- 基于 Dify API 的 workflow 模式
128+
129+
## TODO
130+
131+
- [ ] 支持更新现有翻译

0 commit comments

Comments
 (0)