docs/features/programming/markdown_translate.md
技术文档和项目 README 通常采用 Markdown 格式编写，它们是开发者理解项目、学习技术的重要资料。GPT Academic 提供了专门的 Markdown 翻译功能，可以将英文技术文档翻译为中文，或将中文文档翻译为英文，同时完整保留 Markdown 的格式标记，确保翻译后的文档可以直接使用。
这项功能针对 Markdown 文档的特性进行了专门优化。翻译时会智能识别并保护 Markdown 语法元素——标题层级、代码块、链接、列表等格式都会原封不动地保留，只有正文内容会被翻译。对于长文档，系统会自动将其分割成适当大小的片段进行多线程并行翻译，完成后再合并为完整文档，这种设计既保证了翻译质量又大幅提升了处理速度。
该功能支持三种翻译模式。英译中模式适合翻译 GitHub 上的英文项目文档，帮助您快速了解国外开源项目；中译英模式则可以将您的中文文档翻译成英文，方便项目的国际化推广；指定语言模式允许您将文档翻译成任意语言，只需在高级参数中指定目标语言即可。
使用此功能前，请确保已配置可用的大语言模型 API。由于 Markdown 文档通常篇幅不长，翻译消耗的 Token 相对较少，大多数模型都可以胜任这项任务。推荐使用 gpt-3.5-turbo、qwen-max 或 deepseek-chat 等性价比较高的模型。
!!! info "关于 tiktoken 依赖"
Markdown 翻译功能依赖 tiktoken 库来计算文本长度和智能分片。这个依赖通常会在安装项目时自动安装。如果启动时提示缺少此依赖，请执行：
```bash
pip install --upgrade tiktoken
```
当您有本地的 Markdown 文件或整个文档目录需要翻译时，直接在输入框中填写文件或文件夹的路径，然后选择相应的翻译插件即可。
对于单个文件，输入完整的文件路径，例如 /home/user/docs/README.md。对于包含多个 Markdown 文件的文件夹，输入文件夹路径如 /home/user/docs/，系统会自动递归搜索该目录下所有 .md 文件并批量翻译。
在函数插件区的编程分类中，选择 翻译Markdown（英译中） 插件即可开始翻译。翻译过程中，对话区会实时显示每个文件的处理进度。完成后，翻译结果会保存为新文件并出现在下载区。
这是最便捷的使用方式之一。如果您想快速了解某个 GitHub 项目，可以直接将项目主页的 URL 粘贴到输入框：
https://github.com/binary-husky/gpt_academic
系统会自动从 GitHub 获取该项目的 README 文件并进行翻译。您也可以指定具体的 Markdown 文件 URL：
https://github.com/binary-husky/gpt_academic/blob/master/docs/use_audio.md
如果您需要将文档翻译成中文或英文以外的语言，可以使用 Markdown翻译（指定翻译成何种语言） 插件。选择此插件后，在高级参数输入区中填写目标语言：
Japanese
或者使用中文指定：
日语
系统将根据您指定的语言进行翻译。这个功能适合需要多语言文档的国际化项目。
Markdown 翻译功能支持多种输入格式，系统会自动识别并处理：
| 输入类型 | 格式示例 | 说明 |
|---|---|---|
| 本地文件 | /home/user/docs/README.md | 翻译单个文件 |
| 本地目录 | /home/user/docs/ | 递归翻译目录下所有 .md 文件 |
| GitHub 项目主页 | https://github.com/owner/repo | 自动获取并翻译 README |
| GitHub 文件链接 | https://github.com/owner/repo/blob/main/docs/guide.md | 翻译指定的 Markdown 文件 |
| 原始文件链接 | https://raw.githubusercontent.com/owner/repo/main/README.md | 直接下载并翻译 |
当输入 GitHub 项目主页时，系统会调用 GitHub API 自动定位该项目的 README 文件。这意味着无论 README 文件是叫 README.md、readme.md 还是 README.markdown，都能被正确识别和翻译。
翻译完成后，系统会生成以下文件：
| 文件 | 说明 |
|---|---|
翻译后的 .md 文件 | 保留原格式的翻译结果，可直接使用 |
| 翻译过程记录 | 包含每个片段的翻译详情，供调试参考 |
所有生成的文件都会出现在界面右侧的"文件下载区"，点击即可下载。对于批量翻译多个文件的情况，每个源文件都会生成对应的翻译文件。
如果您对翻译有特殊要求，可以通过高级参数传递额外指令。在选择插件之前，点击"展开"按钮显示高级参数输入区，然后输入您的特定要求。
例如，您希望保持某些专业术语不翻译，可以添加：
Keep the following terms untranslated: API, SDK, Docker, Kubernetes
这些指令会与默认的翻译提示词合并，影响翻译结果。
对于需要定期翻译文档的场景（如开源项目的文档国际化），可以结合脚本实现自动化处理。将需要翻译的 Markdown 文件统一放在一个目录下，然后输入该目录路径进行批量翻译。翻译后的文件会按原文件名生成，方便后续的版本管理。
???+ question "翻译后的格式出现问题，比如代码块被破坏" 这种情况较少发生，但可能在某些复杂文档中出现。建议：
1. 检查原文档的 Markdown 语法是否规范
2. 尝试切换到能力更强的模型（如 GPT-4）
3. 对于问题片段，可以手动修复后在本地重新编辑
???+ question "GitHub 链接无法获取 README" 可能的原因包括：
1. **私有仓库**：本功能仅支持公开仓库
2. **网络问题**：如使用代理，请确保代理配置正确
3. **API 限制**：GitHub API 有访问频率限制，稍后重试
如果持续失败，可以手动下载 README 文件到本地，然后用本地路径进行翻译。
???+ question "翻译速度很慢" 文档翻译速度主要取决于文档长度和 API 响应速度。优化建议：
1. 使用响应更快的模型，如 `gpt-3.5-turbo` 或 `qwen-turbo`
2. 确保网络连接稳定
3. 对于特别长的文档，系统会自动分片并行处理，耐心等待即可
???+ question "中译英的翻译质量不理想" 中译英比英译中更具挑战性。可以尝试：
1. 使用能力更强的模型，如 GPT-4o 或 Claude
2. 在高级参数中添加"请使用专业的技术文档风格翻译"
3. 翻译后人工审校关键内容