Markdown Translator

一个高性能的Rust翻译库，专为Markdown文档设计，提供智能文本翻译功能。

✨ 主要特性

🚀 高性能并行处理: 利用Rust异步特性，支持多任务并发翻译
🔧 智能代码块处理: 自动识别并跳过代码块，保持代码完整性
⚡ 速率限制: 内置智能速率限制器，防止API过载
📝 配置灵活: 支持TOML配置文件和程序化配置
🔄 错误恢复: 完善的错误处理和重试机制
📄 文本分块: 智能文本分割，支持长文档翻译
🌐 多API支持: 支持DeepLX和兼容的翻译API

🚀 快速开始

安装

将以下内容添加到你的 Cargo.toml:

[dependencies]
markdown-translator = "0.1.0"
tokio = { version = "1.0", features = ["full"] }

基本使用

use markdown_translator::{TranslationService, TranslationConfig};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 配置翻译服务
    let config = TranslationConfig {
        enabled: true,
        source_lang: "en".to_string(),
        target_lang: "zh".to_string(),
        deeplx_api_url: "http://localhost:1188/translate".to_string(),
        max_requests_per_second: 1.0,
        max_text_length: 3000,
        max_paragraphs_per_request: 10,
    };
    
    // 创建翻译服务
    let translator = TranslationService::new(config);
    
    // 翻译文本
    let markdown = r#"
    # Hello World
    
    This is a markdown document with code:
    
    ```rust
    fn main() {
        println!("Hello, world!");
    }
    ```
    
    The code above will be preserved during translation.
    "#;
    
    let result = translator.translate(markdown).await?;
    println!("Translation result:\n{}", result);
    
    Ok(())
}

使用配置文件

创建 translation-config.toml:

[translation]
enabled = true
source_lang = "auto"
target_lang = "zh"
deeplx_api_url = "http://localhost:1188/translate"
max_requests_per_second = 2.0
max_text_length = 3000
max_paragraphs_per_request = 10

然后在代码中使用:

use markdown_translator::{TranslationService, TranslationLibConfig};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 从配置文件加载配置
    let lib_config = TranslationLibConfig::load_from_default_locations();
    let translator = TranslationService::new(lib_config.translation);
    
    let result = translator.translate("Hello, world!").await?;
    println!("Translation: {}", result);
    
    Ok(())
}

📋 配置选项

翻译配置

字段	类型	默认值	说明
`enabled`	`bool`	`false`	是否启用翻译功能
`source_lang`	`String`	`"auto"`	源语言代码，"auto"表示自动检测
`target_lang`	`String`	`"zh"`	目标语言代码
`deeplx_api_url`	`String`	`"http://localhost:1188/translate"`	DeepLX API地址
`max_requests_per_second`	`f64`	`0.5`	每秒最大请求数
`max_text_length`	`usize`	`3000`	单次翻译的最大文本长度
`max_paragraphs_per_request`	`usize`	`10`	单次请求的最大段落数

配置文件搜索路径

库会按以下顺序搜索配置文件：

translation-config.toml (当前目录)
config.toml (当前目录)
.translation-config.toml (当前目录)

性能调优

高性能配置

适用于本地网络环境或高性能API服务：

[translation]
enabled = true
source_lang = "auto"
target_lang = "zh"
deeplx_api_url = "http://localhost:1188/translate"
max_requests_per_second = 3.0
max_text_length = 4000
max_paragraphs_per_request = 15

稳定配置

适用于公网环境或API限制较严格的场景：

[translation]
enabled = true
source_lang = "auto"
target_lang = "zh"
deeplx_api_url = "http://localhost:1188/translate"
max_requests_per_second = 0.5
max_text_length = 2000
max_paragraphs_per_request = 5

🌐 支持的翻译API

DeepLX

这是推荐的翻译API，支持多种部署方式：

# 使用Docker运行DeepLX
docker run -d -p 1188:1188 ghcr.io/owo-network/deeplx:latest

# 测试API
curl -X POST http://localhost:1188/translate \
  -H "Content-Type: application/json" \
  -d '{"text":"Hello World","source_lang":"auto","target_lang":"zh"}'

兼容的API格式

库支持两种API格式：

标准DeepLX格式:

{
  "text": "Hello, world!",
  "source_lang": "en",
  "target_lang": "zh"
}

DpTrans格式:

{
  "text": "Hello, world!",
  "source_lang": "en", 
  "target_lang": "zh"
}

🔧 高级特性

并行处理

库内置并行处理支持，可以同时翻译多个文本块：

use markdown_translator::{TranslationService, TranslationConfig};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = TranslationConfig {
        enabled: true,
        max_requests_per_second: 3.0, // 增加并发数
        ..Default::default()
    };
    
    let translator = TranslationService::new(config);
    
    // 长文档会自动分块并并行处理
    let long_document = std::fs::read_to_string("long_document.md")?;
    let result = translator.translate(&long_document).await?;
    
    Ok(())
}

代码块保护

库会自动识别Markdown代码块并跳过翻译：

# 标题会被翻译

这段文字会被翻译。

```rust
// 这段代码不会被翻译
fn main() {
    println!("Hello, world!");
}

这段文字也会被翻译。


### 错误处理和重试

内置重试机制，自动处理临时网络错误：

```rust
use markdown_translator::{TranslationService, TranslationError};

match translator.translate("Hello, world!").await {
    Ok(result) => println!("Translation: {}", result),
    Err(TranslationError::Http(e)) => eprintln!("Network error: {}", e),
    Err(TranslationError::ApiError { code, message }) => {
        eprintln!("API error {}: {}", code, message);
    }
    Err(e) => eprintln!("Other error: {}", e),
}

📊 性能基准

在典型配置下的性能表现：

文档大小	处理时间	并发数	吞吐量
1KB	~1s	1	~1KB/s
10KB	~3s	3	~3.3KB/s
100KB	~15s	5	~6.7KB/s

注：性能取决于网络延迟、API响应时间和配置参数

🛠️ 开发

构建

cargo build --release

测试

cargo test

文档生成

cargo doc --open

运行示例

# 生成配置文件
cargo run --example generate_config

# 运行翻译测试
cargo run --example test_translation

🤝 贡献

欢迎贡献代码！请遵循以下步骤：

Fork 项目
创建功能分支 (git checkout -b feature/AmazingFeature)
提交更改 (git commit -m 'Add some AmazingFeature')
推送到分支 (git push origin feature/AmazingFeature)
开启 Pull Request

📄 许可证

本项目使用 MIT 许可证 - 查看 LICENSE 文件了解详情。

🙏 致谢

DeepLX - 提供免费的翻译API
reqwest - HTTP客户端库
tokio - 异步运行时
serde - 序列化框架

📞 支持

如果遇到问题或有建议，请：

查看文档
搜索现有的Issues
创建新的Issue描述问题

注意: 请遵守API服务提供商的使用条款和速率限制。合理使用翻译服务，避免滥用。

markdown-translator 0.1.0