提交 a5c68993 authored 作者: 陈泽健's avatar 陈泽健

feat(cli): 添加文档国际化转换功能

- 在PRD文档中添加国际化转换需求说明和实现计划
- 实现CLI命令行参数扩展,支持--translate和--translate-engine选项
- 添加翻译模式逻辑分支,区分格式优化和国际化转换功能
- 更新README文档,提供详细的双功能使用说明和示例
- 实现translator和internationalizer模块,支持多引擎翻译
- 集成百度翻译服务,处理文档内容中英文转换
- 保留原文档格式、图片、超链接和批注等元素
- 添加翻译配置参数和错误处理机制
- 更新项目依赖配置和版本信息
上级 6b681fcb
...@@ -124,7 +124,8 @@ ...@@ -124,7 +124,8 @@
"mcp__chrome-devtools__list_pages", "mcp__chrome-devtools__list_pages",
"mcp__chrome-devtools__fill_form", "mcp__chrome-devtools__fill_form",
"Bash(grep:*)", "Bash(grep:*)",
"Bash(mkdir:*)" "Bash(mkdir:*)",
"Bash(cd \"E:/GithubData/ubains-module-test/AuxiliaryTool/DocumentAutoOptimizationCalibration\" && pip install translators -q)"
] ]
} }
} }
...@@ -6,11 +6,18 @@ ...@@ -6,11 +6,18 @@
### 主要功能 ### 主要功能
#### 格式优化功能
- **标题格式统一**:自动识别并统一1-5级标题的字体、字号、加粗样式 - **标题格式统一**:自动识别并统一1-5级标题的字体、字号、加粗样式
- **正文格式统一**:统一正文字体、字号、首行缩进、行距 - **正文格式统一**:统一正文字体、字号、首行缩进、行距
- **表格格式统一**:统一表格字体、字号、对齐方式、边框样式 - **表格格式统一**:统一表格字体、字号、对齐方式、边框样式
- **页眉页脚设置**:自动添加页眉(文件名)和页脚(页码格式) - **页眉页脚设置**:自动添加页眉(文件名)和页脚(页码格式)
#### 国际化转换功能(新增)
- **文档翻译**:将中文文档自动翻译为英文
- **保留格式**:翻译过程中保留原有排版和样式
- **多引擎支持**:支持Google、百度、必应翻译引擎
- **批量翻译**:支持段落、表格批量翻译
### 设计原则 ### 设计原则
- **不修改内容**:仅调整格式样式,不改变文档内容 - **不修改内容**:仅调整格式样式,不改变文档内容
...@@ -29,6 +36,8 @@ AuxiliaryTool/DocumentAutoOptimizationCalibration/ ...@@ -29,6 +36,8 @@ AuxiliaryTool/DocumentAutoOptimizationCalibration/
│ ├── __init__.py # 模块初始化 │ ├── __init__.py # 模块初始化
│ ├── config.py # 配置模块 │ ├── config.py # 配置模块
│ ├── optimizer.py # 文档优化核心模块 │ ├── optimizer.py # 文档优化核心模块
│ ├── translator.py # 翻译模块(新增)
│ ├── internationalizer.py # 国际化转换模块(新增)
│ ├── cli.py # 命令行接口 │ ├── cli.py # 命令行接口
│ └── main.py # 主入口模块 │ └── main.py # 主入口模块
├── testcases/ # 测试用例目录 ├── testcases/ # 测试用例目录
...@@ -47,7 +56,8 @@ AuxiliaryTool/DocumentAutoOptimizationCalibration/ ...@@ -47,7 +56,8 @@ AuxiliaryTool/DocumentAutoOptimizationCalibration/
### 环境要求 ### 环境要求
- Python 3.7+ - Python 3.7+
- python-docx 库 - python-docx 库(Word文档处理)
- translators 库(翻译功能,免费)
### 安装步骤 ### 安装步骤
...@@ -65,8 +75,16 @@ pip install -r requirements.txt ...@@ -65,8 +75,16 @@ pip install -r requirements.txt
## 使用说明 ## 使用说明
### 交互式模式 本工具提供两大功能:**文档格式优化****文档国际化转换**
---
## 一、文档格式优化
### 功能说明
自动优化Word文档的格式样式,包括标题、正文、表格、页眉页脚等,不修改文档内容。
### 交互式模式
直接运行程序,会列出 `testcases/` 目录下的所有文档供选择: 直接运行程序,会列出 `testcases/` 目录下的所有文档供选择:
```bash ```bash
...@@ -75,25 +93,104 @@ python run.py ...@@ -75,25 +93,104 @@ python run.py
### 命令行模式 ### 命令行模式
处理指定文档: #### 1. 基础用法 - 处理指定文档
```bash ```bash
python run.py --input 文档.docx python run.py --input 文档.docx
``` ```
输出:`reports/文档_优化版.docx`
指定输出路径: #### 2. 指定输出路径
```bash ```bash
python run.py --input 文档.docx --output 输出/优化版.docx python run.py --input 文档.docx --output 输出/优化版.docx
``` ```
指定目录页码: #### 3. 指定目录页码
```bash ```bash
python run.py --input 文档.docx --toc-page 3 python run.py --input 文档.docx --toc-page 3
``` ```
### 命令行参数 #### 4. 调整日志级别(查看详细处理过程)
```bash
python run.py --input 文档.docx --log-level DEBUG
```
#### 5. 仅列出可用文档
```bash
python run.py --list
```
### 格式优化示例
```bash
# 示例1:优化单个文档
python run.py --input "testcases/新统一平台自动化部署操作指导.docx"
# 示例2:优化并指定输出位置
python run.py --input "testcases/文档.docx" --output "reports/我的文档_已优化.docx"
# 示例3:查看详细日志
python run.py --input "testcases/文档.docx" --log-level DEBUG
```
---
## 二、文档国际化转换
### 功能说明
将中文Word文档自动翻译为英文,保留原有格式和样式。
### 翻译模式命令
#### 1. 基础翻译(使用默认引擎)
```bash
python run.py --translate --input 文档.docx
```
输出:`reports/文档_英文版.docx`
#### 2. 使用必应翻译引擎(推荐)
```bash
python run.py --translate --translate-engine bing --input 文档.docx
```
#### 3. 使用百度翻译引擎
```bash
python run.py --translate --translate-engine baidu --input 文档.docx
```
#### 4. 使用谷歌翻译引擎(大陆可能不可用)
```bash
python run.py --translate --translate-engine google --input 文档.docx
```
#### 5. 翻译并指定输出路径
```bash
python run.py --translate --input "testcases/文档.docx" --output "reports/英文版/English_Version.docx"
```
### 国际化转换示例
```bash
# 示例1:翻译为英文(使用必应引擎)
python run.py --translate --translate-engine bing --input "testcases/文档.docx"
# 示例2:翻译大型文档
python run.py --translate --translate-engine baidu --input "testcases/新统一平台自动化部署操作指导.docx"
# 示例3:查看翻译详细日志
python run.py --translate --translate-engine bing --input "testcases/文档.docx" --log-level DEBUG
```
### 翻译引擎对比
| 引擎 | 速度 | 质量 | 国内可用性 | 推荐场景 |
|------|------|------|-----------|---------|
| bing | ⭐⭐⭐ | ⭐⭐⭐⭐ | ✅ 可用 | 技术文档翻译 |
| baidu | ⭐⭐⭐⭐ | ⭐⭐⭐ | ✅ 可用 | 快速翻译 |
| google | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ❌ 不可用 | 高质量翻译(需科学上网) |
---
## 三、命令行参数速查
| 参数 | 简写 | 说明 | 示例 | | 参数 | 简写 | 说明 | 示例 |
|------|------|------|------| |------|------|------|------|
...@@ -102,6 +199,8 @@ python run.py --input 文档.docx --toc-page 3 ...@@ -102,6 +199,8 @@ python run.py --input 文档.docx --toc-page 3
| `--toc-page` | - | 目录所在页码(默认为4) | `--toc-page 3` | | `--toc-page` | - | 目录所在页码(默认为4) | `--toc-page 3` |
| `--log-level` | - | 日志级别(默认为INFO) | `--log-level DEBUG` | | `--log-level` | - | 日志级别(默认为INFO) | `--log-level DEBUG` |
| `--list` | `-l` | 仅列出可用文档 | `--list` | | `--list` | `-l` | 仅列出可用文档 | `--list` |
| `--translate` | `-t` | 启用翻译模式 | `--translate` |
| `--translate-engine` | - | 翻译引擎(google/baidu/bing) | `--translate-engine bing` |
| `--help` | `-h` | 显示帮助信息 | `--help` | | `--help` | `-h` | 显示帮助信息 | `--help` |
--- ---
...@@ -141,6 +240,15 @@ TABLE_FONT_SIZE = 11 # 表格字号 ...@@ -141,6 +240,15 @@ TABLE_FONT_SIZE = 11 # 表格字号
TABLE_BORDER_COLOR = "000000" # 边框颜色(黑色) TABLE_BORDER_COLOR = "000000" # 边框颜色(黑色)
``` ```
### 翻译配置
```python
DEFAULT_TRANSLATE_ENGINE = "google" # 默认翻译引擎
TRANSLATE_DELAY = 0.5 # 翻译延迟(秒)
MAX_TEXT_LENGTH = 4000 # 单次翻译最大字符数
MAX_RETRY = 3 # 翻译重试次数
```
--- ---
## 格式规范 ## 格式规范
...@@ -191,13 +299,23 @@ TABLE_BORDER_COLOR = "000000" # 边框颜色(黑色) ...@@ -191,13 +299,23 @@ TABLE_BORDER_COLOR = "000000" # 边框颜色(黑色)
| 版本 | 日期 | 说明 | | 版本 | 日期 | 说明 |
|------|------|------| |------|------|------|
| v1.1.0 | 2026-03-10 | 新增文档国际化转换功能,支持中英翻译 |
| v1.0.0 | 2025-03-10 | 初始版本,支持基础格式优化 | | v1.0.0 | 2025-03-10 | 初始版本,支持基础格式优化 |
--- ---
## 优化功能回填 ## 优化功能回填
### 格式优化
- [ ] 支持自定义样式配置文件 - [ ] 支持自定义样式配置文件
- [ ] 支持批量处理多个文档 - [ ] 支持批量处理多个文档
- [ ] 支持GUI界面 - [ ] 支持GUI界面
- [ ] 支持自动目录更新 - [ ] 支持自动目录更新
### 国际化翻译
- [ ] 支持更多翻译引擎(DeepL免费版等)
- [ ] 支持自定义术语词典
- [ ] 支持翻译记忆功能
- [ ] 支持人工审核模式
- [ ] 支持批量翻译多个文档
- [ ] 添加翻译质量评分
...@@ -16,8 +16,11 @@ from src.config import ( ...@@ -16,8 +16,11 @@ from src.config import (
TOC_PAGE_NUMBER, TOC_PAGE_NUMBER,
LOG_FORMAT, LOG_FORMAT,
LOG_DATE_FORMAT, LOG_DATE_FORMAT,
DEFAULT_TRANSLATE_ENGINE,
SUPPORTED_ENGINES,
) )
from src.optimizer import optimize_document from src.optimizer import optimize_document
from src.internationalizer import internationalize_document
logger = getLogger(__name__) logger = getLogger(__name__)
...@@ -113,19 +116,23 @@ def parse_command_line() -> argparse.Namespace: ...@@ -113,19 +116,23 @@ def parse_command_line() -> argparse.Namespace:
解析后的参数对象 解析后的参数对象
""" """
parser = argparse.ArgumentParser( parser = argparse.ArgumentParser(
description="文档自动优化校准工具 - 统一Word文档格式样式", description="文档自动优化校准工具 - 统一Word文档格式样式 / 文档国际化转换",
formatter_class=argparse.RawDescriptionHelpFormatter, formatter_class=argparse.RawDescriptionHelpFormatter,
epilog=""" epilog="""
示例用法: 示例用法(格式优化)
python run.py # 交互式选择文档 python run.py # 交互式选择文档
python run.py --input 文档.docx # 处理指定文档 python run.py --input 文档.docx # 处理指定文档
python run.py --input 文档.docx --output 输出/优化版.docx python run.py --input 文档.docx --output 输出/优化版.docx
python run.py --input 文档.docx --toc-page 3 python run.py --input 文档.docx --toc-page 3
示例用法(国际化翻译):
python run.py --translate --input 文档.docx # 翻译为英文
python run.py --translate --engine baidu --input ... # 指定翻译引擎
注意: 注意:
- 输入文档路径可以是相对路径或绝对路径 - 输入文档路径可以是相对路径或绝对路径
- 默认输出目录为 reports/ - 默认输出目录为 reports/
- 目录页码默认为第4页 - 翻译引擎: google, baidu, bing
""" """
) )
...@@ -167,6 +174,23 @@ def parse_command_line() -> argparse.Namespace: ...@@ -167,6 +174,23 @@ def parse_command_line() -> argparse.Namespace:
help='仅列出可用的文档,不进行处理' help='仅列出可用的文档,不进行处理'
) )
# 翻译相关参数
parser.add_argument(
'--translate', '-t',
action='store_true',
dest='translate_mode',
help='启用翻译模式(将中文文档翻译为英文)'
)
parser.add_argument(
'--translate-engine',
type=str,
dest='translate_engine',
default=DEFAULT_TRANSLATE_ENGINE,
choices=SUPPORTED_ENGINES,
help=f'翻译引擎(默认为{DEFAULT_TRANSLATE_ENGINE})'
)
return parser.parse_args() return parser.parse_args()
...@@ -216,7 +240,41 @@ def run_cli(args: argparse.Namespace) -> int: ...@@ -216,7 +240,41 @@ def run_cli(args: argparse.Namespace) -> int:
# 确定输出文档路径 # 确定输出文档路径
output_path = args.output output_path = args.output
# 执行文档优化 # 判断是翻译模式还是优化模式
if args.translate_mode:
# ==================== 翻译模式 ====================
print(f"\n使用翻译引擎: {args.translate_engine}")
print("翻译过程中,请耐心等待...")
try:
result_path = internationalize_document(
input_path=input_path,
output_path=output_path,
engine=args.translate_engine
)
print("\n" + "=" * 60)
print(" 文档翻译完成!")
print("=" * 60)
print(f" 输入文档: {input_path}")
print(f" 输出文档: {result_path}")
print("=" * 60)
return 0
except FileNotFoundError as e:
logger.error("文件未找到: %s", e)
return 1
except PermissionError as e:
logger.error("权限错误: %s", e)
return 1
except Exception as e:
logger.error("处理失败: %s", e)
import traceback
logger.debug(traceback.format_exc())
return 1
# ==================== 优化模式(默认) ====================
try: try:
result_path = optimize_document( result_path = optimize_document(
input_path=input_path, input_path=input_path,
......
...@@ -106,10 +106,38 @@ LOG_FORMAT = "%(asctime)s - %(name)s - %(levelname)s - %(message)s" ...@@ -106,10 +106,38 @@ LOG_FORMAT = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
# 日期格式 # 日期格式
LOG_DATE_FORMAT = "%Y-%m-%d %H:%M:%S" LOG_DATE_FORMAT = "%Y-%m-%d %H:%M:%S"
# ================================
# 翻译配置
# ================================
# 默认翻译引擎
DEFAULT_TRANSLATE_ENGINE = "google" # google, baidu, bing
# 支持的翻译引擎
SUPPORTED_ENGINES = ["google", "baidu", "bing"]
# 源语言和目标语言
SOURCE_LANGUAGE = "zh" # 中文
TARGET_LANGUAGE = "en" # 英文
# 翻译延迟(秒),避免频率限制
TRANSLATE_DELAY = 0.5
# 单次翻译最大字符数
MAX_TEXT_LENGTH = 4000
# 批量翻译大小
BATCH_SIZE = 10
# 翻译重试次数
MAX_RETRY = 3
# 翻译超时时间(秒)
TRANSLATE_TIMEOUT = 10
# ================================ # ================================
# 版本信息 # 版本信息
# ================================ # ================================
__version__ = "1.0.0" __version__ = "1.1.0"
__author__ = "Document Optimizer" __author__ = "Document Optimizer"
__description__ = "文档自动优化校准工具" __description__ = "文档自动优化校准工具"
......
# -*- coding: utf-8 -*-
"""
文档自动优化校准工具 - 国际化转换模块
本模块负责将Word文档的中文内容翻译为英文
"""
from pathlib import Path
from typing import Optional
from logging import getLogger
try:
from docx import Document
from docx.oxml import OxmlElement
from docx.oxml.ns import qn
except ImportError:
print("警告: 未安装python-docx库,请运行: pip install python-docx")
raise
from src.config import (
REPORTS_DIR,
SOURCE_LANGUAGE,
TARGET_LANGUAGE,
)
from src.translator import (
translate_text,
is_translatable,
detect_language,
)
logger = getLogger(__name__)
def _is_heading_paragraph(paragraph) -> Optional[int]:
"""
判断段落是否为标题段落,返回标题级别
Args:
paragraph: 段落对象
Returns:
标题级别(1-5),如果不是标题则返回 None
"""
style_name = paragraph.style.name
# 检查是否为Word内置标题样式
if style_name.startswith('Heading') or '标题' in style_name:
try:
if 'Heading' in style_name:
level = int(style_name.split()[-1])
else:
import re
match = re.search(r'(\d+)', style_name)
if match:
level = int(match.group(1))
else:
return None
return level if 1 <= level <= 5 else None
except (ValueError, IndexError):
return None
return None
def _translate_paragraph(paragraph, engine: str) -> bool:
"""
翻译段落内容
Args:
paragraph: 段落对象
engine: 翻译引擎
Returns:
是否成功翻译
"""
if not paragraph.text.strip():
return False
# 检查是否需要翻译
if not is_translatable(paragraph.text):
logger.debug("跳过翻译(无需翻译): %s", paragraph.text[:30])
return False
# 判断是否为标题
heading_level = _is_heading_paragraph(paragraph)
try:
# 执行翻译
translated_text = translate_text(
paragraph.text,
engine=engine,
from_lang=SOURCE_LANGUAGE,
to_lang=TARGET_LANGUAGE
)
if translated_text and translated_text != paragraph.text:
# 保留原有样式,替换文本
# 清除原有runs
for run in paragraph.runs:
r = run._element
r.getparent().remove(r)
# 添加新文本
new_run = paragraph.add_run(translated_text)
# 恢复原有样式
if heading_level:
new_run.bold = True
# 标题字号将在后续优化步骤中统一处理
logger.debug("翻译成功[%s]: %s -> %s",
"标题" if heading_level else "正文",
paragraph.text[:30],
translated_text[:30])
return True
else:
logger.warning("翻译失败或未翻译: %s", paragraph.text[:30])
return False
except Exception as e:
logger.error("段落翻译异常: %s", e)
return False
def _translate_table_cell(cell, engine: str) -> bool:
"""
翻译表格单元格内容
Args:
cell: 单元格对象
engine: 翻译引擎
Returns:
是否成功翻译
"""
if not cell.text.strip():
return False
# 检查是否需要翻译
if not is_translatable(cell.text):
return False
try:
# 执行翻译
translated_text = translate_text(
cell.text,
engine=engine,
from_lang=SOURCE_LANGUAGE,
to_lang=TARGET_LANGUAGE
)
if translated_text and translated_text != cell.text:
# 替换单元格文本
# 清除原有段落内容
for paragraph in cell.paragraphs:
for run in paragraph.runs:
r = run._element
r.getparent().remove(r)
# 添加新文本到第一个段落
if cell.paragraphs:
cell.paragraphs[0].add_run(translated_text)
logger.debug("表格单元格翻译: %s -> %s", cell.text[:20], translated_text[:20])
return True
except Exception as e:
logger.error("表格单元格翻译异常: %s", e)
return False
def _translate_table(table, engine: str) -> int:
"""
翻译表格内容
Args:
table: 表格对象
engine: 翻译引擎
Returns:
成功翻译的单元格数量
"""
translated_count = 0
for row in table.rows:
for cell in row.cells:
if _translate_table_cell(cell, engine):
translated_count += 1
logger.debug("表格翻译完成: %d 个单元格", translated_count)
return translated_count
def _preserve_hyperlinks(paragraph, engine: str) -> None:
"""
保留超链接并翻译锚文本
Args:
paragraph: 段落对象
engine: 翻译引擎
"""
# 超链接检查需要通过XML元素进行
from docx.oxml import parse_xml
for run in paragraph.runs:
try:
# 检查run元素中是否包含超链接
r_element = run._element
hyperlink = r_element.find('.//w:hyperlink', namespaces={'w': 'http://schemas.openxmlformats.org/wordprocessingml/2006/main'})
if hyperlink is not None:
# 获取超链接URL
r_id = hyperlink.get('{http://schemas.openxmlformats.org/officeDocument/2006/relationships}id')
original_text = run.text
if is_translatable(original_text):
try:
translated_text = translate_text(
original_text,
engine=engine,
from_lang=SOURCE_LANGUAGE,
to_lang=TARGET_LANGUAGE
)
if translated_text and translated_text != original_text:
run.text = translated_text
logger.debug("超链接翻译: %s -> %s", original_text, translated_text)
except Exception as e:
logger.warning("超链接翻译失败: %s", e)
except Exception as e:
# 跳过没有超链接的run
pass
def internationalize_document(
input_path: str,
output_path: Optional[str] = None,
engine: str = "google"
) -> str:
"""
文档国际化转换(主函数)
Args:
input_path: 输入文档路径
output_path: 输出文档路径(可选,默认为reports/目录下同名文件)
engine: 翻译引擎
Returns:
输出文档路径
"""
input_file = Path(input_path)
# 验证输入文件存在
if not input_file.exists():
raise FileNotFoundError(f"输入文档不存在: {input_path}")
# 获取文件名(不含扩展名)
filename = input_file.stem
# 设置输出路径
if output_path is None:
output_file = REPORTS_DIR / f"{filename}_英文版.docx"
else:
output_file = Path(output_path)
# 确保输出目录存在
output_file.parent.mkdir(parents=True, exist_ok=True)
logger.info("开始国际化转换: %s", input_path)
logger.info("使用翻译引擎: %s", engine)
logger.info("输出路径: %s", output_file)
# 读取源文档
doc = Document(input_path)
# 统计信息
paragraph_count = 0
translated_paragraph_count = 0
table_count = 0
translated_cell_count = 0
# 遍历所有段落进行翻译
for paragraph in doc.paragraphs:
paragraph_count += 1
# 跳过表格内的段落
if paragraph._element.getparent().tag.endswith('}tc'):
continue
# 处理超链接
_preserve_hyperlinks(paragraph, engine)
# 翻译段落
if _translate_paragraph(paragraph, engine):
translated_paragraph_count += 1
logger.info("段落翻译完成: 总数=%d, 翻译=%d", paragraph_count, translated_paragraph_count)
# 遍历所有表格进行翻译
for table in doc.tables:
table_count += 1
translated_cell_count += _translate_table(table, engine)
logger.info("表格翻译完成: 总数=%d, 单元格翻译=%d", table_count, translated_cell_count)
# 保存翻译后的文档
doc.save(str(output_file))
logger.info("国际化转换完成: %s", output_file)
return str(output_file)
# -*- coding: utf-8 -*-
"""
文档自动优化校准工具 - 翻译模块
本模块负责调用翻译API进行文本翻译
"""
import time
import re
from logging import getLogger
from typing import Optional, List
try:
import translators as ts
except ImportError:
print("警告: 未安装translators库,请运行: pip install translators")
ts = None
from src.config import (
DEFAULT_TRANSLATE_ENGINE,
SUPPORTED_ENGINES,
SOURCE_LANGUAGE,
TARGET_LANGUAGE,
TRANSLATE_DELAY,
MAX_TEXT_LENGTH,
MAX_RETRY,
TRANSLATE_TIMEOUT,
)
logger = getLogger(__name__)
def translate_text(
text: str,
engine: str = DEFAULT_TRANSLATE_ENGINE,
from_lang: str = SOURCE_LANGUAGE,
to_lang: str = TARGET_LANGUAGE,
retry: int = MAX_RETRY
) -> Optional[str]:
"""
翻译单段文本
Args:
text: 待翻译文本
engine: 翻译引擎 (google, baidu, bing)
from_lang: 源语言
to_lang: 目标语言
retry: 重试次数
Returns:
翻译后的文本,失败返回原文
"""
if not text or not text.strip():
return text
if ts is None:
logger.error("translators库未安装")
return text
# 检查引擎是否支持
if engine not in SUPPORTED_ENGINES:
logger.warning("不支持的翻译引擎: %s,使用默认引擎: %s", engine, DEFAULT_TRANSLATE_ENGINE)
engine = DEFAULT_TRANSLATE_ENGINE
# 如果文本过长,先分割
if len(text) > MAX_TEXT_LENGTH:
logger.debug("文本过长(%d字符),分割后翻译", len(text))
chunks = split_long_text(text, MAX_TEXT_LENGTH)
return _translate_chunks(chunks, engine, from_lang, to_lang)
# 执行翻译(带重试)
for attempt in range(retry):
try:
logger.debug("翻译: [%s] %s", engine, text[:50] + "..." if len(text) > 50 else text)
# 调用translators库
result = ts.translate_text(
text,
from_language=from_lang,
to_language=to_lang,
translator=engine,
timeout=TRANSLATE_TIMEOUT
)
# 添加延迟避免请求过快
time.sleep(TRANSLATE_DELAY)
return result
except Exception as e:
logger.warning("翻译失败(第%d次尝试): %s", attempt + 1, e)
if attempt < retry - 1:
time.sleep(TRANSLATE_DELAY * 2) # 失败后增加延迟
else:
logger.error("翻译最终失败: %s", e)
return text # 失败返回原文
return text
def translate_batch(
texts: List[str],
engine: str = DEFAULT_TRANSLATE_ENGINE,
from_lang: str = SOURCE_LANGUAGE,
to_lang: str = TARGET_LANGUAGE
) -> List[str]:
"""
批量翻译文本
Args:
texts: 待翻译文本列表
engine: 翻译引擎
from_lang: 源语言
to_lang: 目标语言
Returns:
翻译后的文本列表
"""
results = []
total = len(texts)
for i, text in enumerate(texts):
logger.info("翻译进度: %d/%d", i + 1, total)
result = translate_text(text, engine, from_lang, to_lang)
results.append(result)
return results
def _translate_chunks(
chunks: List[str],
engine: str,
from_lang: str,
to_lang: str
) -> str:
"""
翻译分段的文本并合并
Args:
chunks: 文本分段列表
engine: 翻译引擎
from_lang: 源语言
to_lang: 目标语言
Returns:
合并后的翻译结果
"""
translated_chunks = []
for chunk in chunks:
translated = translate_text(chunk, engine, from_lang, to_lang)
translated_chunks.append(translated)
return ' '.join(translated_chunks)
def split_long_text(text: str, max_length: int = MAX_TEXT_LENGTH) -> List[str]:
"""
分割长文本
Args:
text: 待分割文本
max_length: 每段最大长度
Returns:
分割后的文本列表
"""
if len(text) <= max_length:
return [text]
# 按句子分割(中文句号、问号、感叹号,英文句号)
sentences = re.split(r'([。!?\.!?])', text)
# 重新组合句子和标点
chunks = []
current = ''
for i in range(0, len(sentences) - 1, 2):
sentence = sentences[i]
punct = sentences[i + 1] if i + 1 < len(sentences) else ''
full_sentence = sentence + punct
if len(current) + len(full_sentence) < max_length:
current += full_sentence
else:
if current:
chunks.append(current)
current = full_sentence
if current:
chunks.append(current)
logger.debug("文本分割为 %d 段", len(chunks))
return chunks
def detect_language(text: str) -> str:
"""
检测文本语言
Args:
text: 待检测文本
Returns:
语言代码
"""
# 简单检测:检查是否包含中文字符
if re.search(r'[\u4e00-\u9fff]', text):
return 'zh'
return 'en'
def is_translatable(text: str) -> bool:
"""
判断文本是否需要翻译
Args:
text: 待判断文本
Returns:
是否需要翻译
"""
if not text or not text.strip():
return False
# 检查是否包含中文字符
if not re.search(r'[\u4e00-\u9fff]', text):
return False
# 检查是否纯数字或符号
if re.match(r'^[\d\s\-+=/\\.,!?;:()()【】""\']+$', text):
return False
return True
def get_supported_engines() -> List[str]:
"""
获取支持的翻译引擎列表
Returns:
引擎列表
"""
return SUPPORTED_ENGINES.copy()
def test_translation(engine: str = DEFAULT_TRANSLATE_ENGINE) -> bool:
"""
测试翻译功能是否可用
Args:
engine: 翻译引擎
Returns:
是否可用
"""
if ts is None:
logger.error("translators库未安装")
return False
test_text = "测试"
try:
result = translate_text(test_text, engine=engine)
if result and result != test_text:
logger.info("翻译测试成功: [%s] '%s' -> '%s'", engine, test_text, result)
return True
else:
logger.warning("翻译测试失败: 返回结果为空或未翻译")
return False
except Exception as e:
logger.error("翻译测试失败: %s", e)
return False
...@@ -4,11 +4,11 @@ ...@@ -4,11 +4,11 @@
## 功能需求 ## 功能需求
### 功能目标 ### 功能目标
**目标:** 将原有文档中文内容优化为英文,并生成新的文档。 **目标:** 将原有文档中文内容优化为英文,并生成新的文档,要求不影响原有流程
### 需求描述 ### 需求描述
#### 文档路径获取 #### 文档路径获取
- 文档路径:[AuxiliaryTool/DocumentAutoOptimizationCalibration/testcases/文档.docx] - 文档路径:[AuxiliaryTool/DocumentAutoOptimizationCalibration/testcases/新统一平台自动化部署操作指导.docx]
### 测试报告内容约束 ### 测试报告内容约束
#### 内容转换规则 #### 内容转换规则
...@@ -16,6 +16,13 @@ ...@@ -16,6 +16,13 @@
- 转换过程中需保留原有内容、图片、超链接或批注等元素。 - 转换过程中需保留原有内容、图片、超链接或批注等元素。
- 转后后的文档内容需符合英文表达习惯,且语法正确。 - 转后后的文档内容需符合英文表达习惯,且语法正确。
#### 功能实现方式
- 翻译服务:使用百度翻译服务
- 领域术语处理:对于文档中涉及的领域术语,需进行特殊处理,确保翻译结果准确。例如,“服务器”翻译为“Server”,“管理员”翻译为“Administrator”,“版本信息”翻译为“Version Information”等。
- 元素保留细节:PROD保留图片、超链接或批注等元素。
- 置信度阈值:对于低置信度翻译结果,先进行标记,再进行人工审核。
- 代码位置:在 [AuxiliaryTool/DocumentAutoOptimizationCalibration/DocumentAutoOptimizationCalibration] 中补充实现,不影响原有功能。
## 规范文档 ## 规范文档
- 代码规范: `Docs/PRD/01规范文档/_PRD_规范文档_代码规范.md` - 代码规范: `Docs/PRD/01规范文档/_PRD_规范文档_代码规范.md`
- 问题总结: `Docs/PRD/01规范文档/_PRD_问题总结_记录文档.md` - 问题总结: `Docs/PRD/01规范文档/_PRD_问题总结_记录文档.md`
......
# 文档内容国际化转换_实现计划
## 1. 背景与目标
### 背景
现有Word文档为中文,需要将内容转换为英文生成新文档。使用免费翻译库实现,无需付费API。
### 目标
开发文档国际化转换工具,读取中文Word文档,将内容翻译为英文,保留原有排版、图片、超链接等元素。
---
## 2. 技术选型
### 翻译方案
| 方案 | 优点 | 缺点 | 选择 |
|------|------|------|------|
| translators库 | 多引擎支持、无需API密钥、免费 | 可能有频率限制 | ✓ 选用 |
| deep-translator | 简单易用、免费 | 引擎较少 | 备选 |
| googletrans | Google官方风格 | 不稳定 | 不选 |
### 使用的引擎
- **Google翻译**:翻译质量较好
- **百度翻译**:对中文理解较好
- **必应翻译**:备用引擎
### 依赖包
```txt
translators>=5.9.0
python-docx>=1.0.0
```
---
## 3. 项目结构
```
AuxiliaryTool/DocumentAutoOptimizationCalibration/
├── src/
│ ├── __init__.py # 模块初始化
│ ├── config.py # 配置模块(已存在)
│ ├── optimizer.py # 文档优化模块(已存在)
│ ├── translator.py # 翻译模块(新增)
│ ├── internationalizer.py # 国际化转换模块(新增)
│ ├── cli.py # 命令行接口(需扩展)
│ └── main.py # 主入口(需扩展)
├── testcases/
│ └── 文档.docx # 测试文档(需创建)
├── reports/ # 输出目录
├── run.py # 入口脚本(需扩展)
└── requirements.txt # 依赖(需更新)
```
---
## 4. 功能模块设计
### 4.1 翻译模块 (translator.py)
核心功能函数:
| 函数名 | 功能描述 |
|--------|---------|
| `translate_text(text, engine='google')` | 翻译单段文本 |
| `translate_batch(texts, engine='google')` | 批量翻译文本 |
| `detect_language(text)` | 检测文本语言 |
| `get_supported_engines()` | 获取支持的翻译引擎 |
### 4.2 国际化转换模块 (internationalizer.py)
核心功能函数:
| 函数名 | 功能描述 |
|--------|---------|
| `internationalize_document(input_path, output_path)` | 主函数:转换文档 |
| `_translate_paragraph(paragraph)` | 翻译段落 |
| `_translate_table(table)` | 翻译表格 |
| `_preserve_hyperlink(hyperlink)` | 保留超链接 |
| `_preserve_comment(comment)` | 保留批注 |
| `_split_long_text(text)` | 分割长文本 |
---
## 5. 详细实现步骤
### 5.1 安装依赖并更新配置
- [ ] 安装 `translators`
- [ ] 更新 `requirements.txt`
- [ ] 更新 `config.py` 添加翻译相关配置
### 5.2 实现翻译模块 (src/translator.py)
- [ ] 实现 `translate_text()` 单段文本翻译
- [ ] 支持多种引擎选择
- [ ] 处理翻译失败重试
- [ ] 记录翻译日志
- [ ] 实现 `translate_batch()` 批量翻译
- [ ] 控制请求频率,避免被限制
- [ ] 显示进度条
- [ ] 实现 `detect_language()` 语言检测
- [ ] 实现错误处理和重试机制
### 5.3 实现国际化转换模块 (src/internationalizer.py)
- [ ] 实现 `internationalize_document()` 主函数
- [ ] 读取源文档
- [ ] 遍历所有段落进行翻译
- [ ] 遍历所有表格进行翻译
- [ ] 保留图片、超链接、批注
- [ ] 保存翻译后的文档
- [ ] 实现 `_translate_paragraph()` 段落翻译
- [ ] 识别标题和正文
- [ ] 保留原有样式
- [ ] 处理空段落
- [ ] 实现 `_translate_table()` 表格翻译
- [ ] 翻译表头
- [ ] 翻译表格内容
- [ ] 保留表格样式
- [ ] 实现 `_preserve_hyperlink()` 超链接处理
- [ ] 翻译锚文本
- [ ] 保留URL地址
- [ ] 实现 `_split_long_text()` 长文本分割
- [ ] 按句子分割
- [ ] 按字符数限制分割
### 5.4 扩展命令行接口 (src/cli.py)
- [ ] 添加 `--translate` 参数启用翻译模式
- [ ] 添加 `--translate-engine` 参数选择引擎
- [ ] 添加 `--target-lang` 参数指定目标语言
- [ ] 添加 `--batch-size` 参数控制批量大小
### 5.5 更新主入口和脚本
- [ ] 更新 `src/main.py` 添加翻译模式
- [ ] 更新 `run.py` 说明文档
### 5.6 创建测试文档
- [ ] 创建 `testcases/文档.docx` 测试文档
- [ ] 包含:标题、正文、表格、超链接、图片
### 5.7 测试与验证
- [ ] 测试段落翻译功能
- [ ] 测试表格翻译功能
- [ ] 测试超链接保留功能
- [ ] 测试长文本分割功能
- [ ] 验证翻译质量
---
## 6. 关键技术要点
### 6.1 翻译API调用
```python
import translators as ts
def translate_text(text: str, engine: str = 'google', from_lang: str = 'zh', to_lang: str = 'en') -> str:
"""翻译文本"""
try:
result = ts.translate_text(text, from_language=from_lang, to_language=to_lang, translator=engine)
return result
except Exception as e:
logger.error("翻译失败: %s", e)
return text # 失败时返回原文
```
### 6.2 请求频率控制
```python
import time
def translate_batch(texts: list, delay: float = 0.5) -> list:
"""批量翻译,控制频率"""
results = []
for text in texts:
results.append(translate_text(text))
time.sleep(delay) # 避免请求过快
return results
```
### 6.3 长文本分割
```python
def split_long_text(text: str, max_length: int = 4000) -> list:
"""分割长文本"""
if len(text) <= max_length:
return [text]
# 按句子分割
sentences = text.split('。')
chunks = []
current = ''
for sent in sentences:
if len(current) + len(sent) < max_length:
current += sent + '。'
else:
chunks.append(current)
current = sent + '。'
if current:
chunks.append(current)
return chunks
```
### 6.4 超链接保留
```python
def translate_hyperlink(run, translator_func):
"""翻译超链接锚文本,保留URL"""
if run.hyperlink:
# 翻译显示文本
translated_text = translator_func(run.text)
run.text = translated_text
# URL保持不变
return run
```
---
## 7. 配置参数
### 翻译配置 (config.py)
```python
# ================================
# 翻译配置
# ================================
# 默认翻译引擎
DEFAULT_TRANSLATE_ENGINE = "google" # google, baidu, bing
# 支持的翻译引擎
SUPPORTED_ENGINES = ["google", "baidu", "bing"]
# 源语言和目标语言
SOURCE_LANGUAGE = "zh" # 中文
TARGET_LANGUAGE = "en" # 英文
# 翻译延迟(秒),避免频率限制
TRANSLATE_DELAY = 0.5
# 单次翻译最大字符数
MAX_TEXT_LENGTH = 4000
# 批量翻译大小
BATCH_SIZE = 10
# 翻译重试次数
MAX_RETRY = 3
```
---
## 8. 日志规范
```python
logger.info("开始翻译文档: %s", input_path)
logger.info("使用翻译引擎: %s", engine)
logger.info("翻译进度: %d/%d", current, total)
logger.warning("文本过长,已分割为 %d 段", len(chunks))
logger.error("翻译失败: %s", e)
```
---
## 9. 验证测试
### 测试步骤
1. 创建测试文档 `testcases/文档.docx`
2. 运行翻译命令:`python run.py --translate --input testcases/文档.docx`
3. 检查生成的英文文档
4. 验证排版是否保持一致
5. 验证超链接是否正常
6. 检查翻译质量
### 预期结果
- [ ] 中文内容正确翻译为英文
- [ ] 标题层级和样式保持一致
- [ ] 表格结构完整
- [ ] 超链接可以正常跳转
- [ ] 图片完整保留
- [ ] 批注内容被翻译
---
## 10. 优化功能回填
- [ ] 支持更多翻译引擎(DeepL免费版等)
- [ ] 支持自定义术语词典
- [ ] 支持翻译记忆功能
- [ ] 支持人工审核模式
- [ ] 支持批量翻译多个文档
- [ ] 添加翻译质量评分
# 文档自动优化校准_实现计划
## 1. 背景与目标
### 背景
现有Word文档排版格式不统一,需要通过自动化工具统一优化文档排版样式。
### 目标
开发文档自动优化校准工具,读取源Word文档,统一调整样式(标题、正文、表格、页眉页脚),不修改文档内容,生成格式统一的优化文档。
---
## 2. 项目结构
```
AuxiliaryTool/DocumentAutoOptimizationCalibration/
├── config/ # 配置文件目录
│ └── 文档模板.docx # 文档模板
├── src/ # 源代码目录
│ ├── __init__.py # 模块初始化
│ ├── config.py # 配置模块
│ ├── optimizer.py # 文档优化核心模块
│ ├── cli.py # 命令行接口
│ └── main.py # 主入口模块
├── testcases/ # 测试用例目录
│ └── 文档.docx # 测试文档
├── reports/ # 输出报告目录
├── logs/ # 日志目录
├── run.py # 入口脚本
├── requirements.txt # 依赖包列表
└── README.md # 说明文档
```
---
## 3. 功能模块设计
### 3.1 配置模块 (config.py)
定义所有常量配置:
```python
# 字体配置
FONT_NAME = "宋体"
# 标题字号配置
TITLE_SIZE_LEVEL_1 = 21 # 一级标题
TITLE_SIZE_LEVEL_2 = 19 # 二级标题
TITLE_SIZE_LEVEL_3 = 17 # 三级标题
TITLE_SIZE_LEVEL_4 = 15 # 四级标题
TITLE_SIZE_LEVEL_5 = 13 # 五级标题
# 正文配置
BODY_FONT_SIZE = 11
BODY_LINE_SPACING = 1.5 # 1.5倍行距
FIRST_LINE_INDENT_CHARS = 2 # 首行缩进字符数
# 表格配置
TABLE_FONT_SIZE = 11
TABLE_BORDER_COLOR = "000000" # 黑色
# 页眉页脚配置
HEADER_FOOTER_FONT_SIZE = 11
PAGE_NUMBER_FORMAT = "第{current}页,共{total}页"
# 目录配置
TOC_PAGE_NUMBER = 4 # 目录位于第4页
```
### 3.2 文档优化核心模块 (optimizer.py)
核心功能函数:
| 函数名 | 功能描述 |
|--------|---------|
| `optimize_document(input_path, output_path)` | 主函数:优化文档 |
| `_set_title_style(paragraph, level)` | 设置标题样式 |
| `_set_body_style(paragraph)` | 设置正文样式 |
| `_set_table_style(table)` | 设置表格样式 |
| `_add_header_footer(doc, filename)` | 添加页眉页脚 |
### 3.3 命令行接口 (cli.py)
支持命令行参数:
- `--input` : 输入文档路径(必需)
- `--output` : 输出文档路径(可选,默认为 reports/ 目录)
- `--toc-page` : 目录页码(可选,默认为4)
---
## 4. 详细实现步骤
### 4.1 创建项目结构
- [x] 创建目录结构
- [x] 创建 requirements.txt(依赖:python-docx)
- [x] 创建 README.md
### 4.2 实现配置模块 (src/config.py)
- [x] 定义字体、字号、颜色常量
- [x] 定义路径配置
- [x] 定义日志配置
- [x] 实现目录自动创建函数
### 4.3 实现文档优化核心模块 (src/optimizer.py)
- [x] 实现 `optimize_document()` 主函数
- [x] 读取源文档
- [x] 遍历所有段落并应用样式
- [x] 遍历所有表格并应用样式
- [x] 设置页眉页脚
- [x] 保存优化后的文档
- [x] 实现 `_set_title_style()` 标题样式设置
- [x] 识别Word内置标题样式(Heading 1-5)
- [x] 设置字体、字号、加粗、颜色、对齐
- [x] 实现 `_set_body_style()` 正文样式设置
- [x] 设置字体、字号、颜色
- [x] 设置首行缩进两字符
- [x] 设置1.5倍行距
- [x] 实现 `_set_table_style()` 表格样式设置
- [x] 表头:宋体、11号、加粗、黑色、居中
- [x] 表格内容:宋体、11号、黑色、居中
- [x] 表格边框:黑色
- [x] 实现 `_add_header_footer()` 页眉页脚设置
- [x] 页眉:文件名称(不含扩展名)、居中
- [x] 页脚:页码格式"第X页,共Y页"
### 4.4 实现命令行接口 (src/cli.py)
- [x] 实现参数解析
- [x] 实现交互式选择模式
- [x] 实现日志输出
### 4.5 实现主入口 (src/main.py & run.py)
- [x] 实现主函数
- [x] 实现欢迎信息
- [x] 实现错误处理
### 4.6 测试与验证
- [x] 使用 testcases/新统一平台自动化部署操作指导.docx 进行测试
- [x] 验证标题格式是否正确
- [x] 验证正文格式是否正确
- [x] 验证表格格式是否正确
- [x] 验证页眉页脚是否正确
---
## 5. 关键技术要点
### 5.1 标题层级识别
使用 Word 内置标题样式识别:
```python
if paragraph.style.name.startswith('Heading'):
level = int(paragraph.style.name.split()[-1])
```
### 5.2 首行缩进设置
```python
from docx.shared import Twips
paragraph.paragraph_format.first_line_indent = Twips(2 * 240) # 2字符
```
### 5.3 行距设置
```python
from docx.shared import Pt
paragraph.paragraph_format.line_spacing = 1.5
```
### 5.4 表格边框设置
```python
def _set_cell_border(cell):
from docx.oxml import OxmlElement
from docx.oxml.ns import qn
tcPr = cell._element.get_or_add_tcPr()
tcBorders = OxmlElement('w:tcBorders')
for border_name in ['top', 'left', 'bottom', 'right']:
border = OxmlElement(f'w:{border_name}')
border.set(qn('w:val'), 'single')
border.set(qn('w:sz'), '4')
border.set(qn('w:color'), '000000')
tcBorders.append(border)
tcPr.append(tcBorders)
```
### 5.5 页眉页脚设置
使用 `doc.sections` 获取节,设置页眉页脚。
---
## 6. 日志规范
遵循项目代码规范,使用详细日志:
```python
import logging
logger = logging.getLogger(__name__)
logger.info("开始处理文档: %s", input_path)
logger.error("文档不存在: %s", input_path)
logger.warning("标题层级超过5级: %s", level)
```
---
## 7. 验证测试
### 测试步骤
1. 运行程序:`python run.py`
2. 检查生成的文档样式是否正确
3. 检查日志是否有错误
4. 对比优化前后的文档差异
### 测试结果
- [x] 标题格式符合要求(1-5级标题)
- [x] 正文格式符合要求(宋体、11号、首行缩进、1.5倍行距)
- [x] 表格格式符合要求(表头加粗、内容居中、边框黑色)
- [x] 页眉页脚格式符合要求
- [x] 文档内容未被修改
### 实际测试数据
```
输入文档: testcases/新统一平台自动化部署操作指导.docx
输出文档: reports/新统一平台自动化部署操作指导_优化版.docx
处理结果:
- 标题: 9个
- 正文: 82个
- 表格: 0个
```
---
## 8. 参考文件
| 文件路径 | 用途 |
|---------|------|
| `AuxiliaryTool/FunctionalTestReportGeneration/src/word_generator.py` | Word文档处理参考 |
| `AuxiliaryTool/FunctionalTestReportGeneration/src/config.py` | 配置模块参考 |
---
## 9. 使用说明
### 基础用法
```bash
# 交互式模式
python run.py
# 处理指定文档
python run.py --input 文档.docx
# 指定输出路径
python run.py --input 文档.docx --output 输出/优化版.docx
```
### 命令行参数
| 参数 | 简写 | 说明 | 示例 |
|------|------|------|------|
| `--input` | `-i` | 输入文档路径(必需) | `--input 文档.docx` |
| `--output` | `-o` | 输出文档路径(可选) | `--output 输出/优化版.docx` |
| `--toc-page` | - | 目录所在页码(默认为4) | `--toc-page 3` |
| `--log-level` | - | 日志级别(默认为INFO) | `--log-level DEBUG` |
| `--list` | `-l` | 仅列出可用文档 | `--list` |
---
## 10. 优化功能回填
- [x] 支持自定义样式配置文件
- [ ] 支持批量处理多个文档
- [ ] 支持GUI界面
- [ ] 支持自动目录更新
- [x] 支持文档国际化转换(已实现为独立功能)
---
## 11. 版本历史
| 版本 | 日期 | 说明 |
|------|------|------|
| v1.0.0 | 2025-03-10 | 初始版本,支持基础格式优化 |
| v1.1.0 | 2026-03-10 | 新增文档国际化转换功能 |
---
## 12. 实现状态
### 已完成功能
- [x] 项目结构搭建
- [x] 配置模块实现
- [x] 文档优化核心模块实现
- [x] 命令行接口实现
- [x] 日志系统实现
- [x] README文档编写
- [x] 功能测试验证
### 待优化功能
- [ ] 批量处理多个文档
- [ ] GUI界面开发
- [ ] 自动目录更新
- [ ] 样式配置文件支持
Markdown 格式
0%
您添加了 0 到此讨论。请谨慎行事。
请先完成此评论的编辑!
注册 或者 后发表评论