html_translation_lib/
lib.rs

1//! HTML翻译库
2//!
3//! 这个库提供了一个完整的HTML内容翻译解决方案，专门为网页本地化而设计。
4//! 它可以智能识别HTML文档中的可翻译文本内容，并将其翻译为目标语言，
5//! 同时保持HTML结构的完整性。
6//!
7//! ## 核心特性
8//!
9//! - **智能文本识别**: 自动识别HTML中需要翻译的文本内容，跳过代码、链接等
10//! - **批量处理优化**: 将多个文本项组合成批次，减少翻译API调用次数
11//! - **DOM结构保护**: 翻译过程中完全保持HTML的DOM结构不变
12//! - **缓存机制**: 内置缓存系统，避免重复翻译相同内容
13//! - **错误恢复**: 自动重试机制和错误处理，确保翻译过程的可靠性
14//! - **异步支持**: 支持异步操作，不阻塞主线程
15//!
16//! ## 使用示例
17//!
18//! ### 基本翻译
19//!
20//! ```rust,no_run
21//! use html_translation_lib::{TranslationConfig, HtmlTranslator};
22//!
23//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
24//! // 创建翻译配置
25//! let config = TranslationConfig::new()
26//!     .target_language("zh")
27//!     .api_url("http://localhost:1188/translate")
28//!     .enable_cache(true);
29//!
30//! // 创建翻译器
31//! let mut translator = HtmlTranslator::new(config).await?;
32//!
33//! // 翻译HTML内容
34//! let html = r#"<html><body><h1>Hello World</h1></body></html>"#;
35//! let translated_html = translator.translate_html(html).await?;
36//! println!("{}", translated_html);
37//! # Ok(())
38//! # }
39//! ```
40//!
41//! ### 翻译文件
42//!
43//! ```rust,no_run
44//! use html_translation_lib::{TranslationConfig, HtmlTranslator};
45//!
46//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
47//! let config = TranslationConfig::new().target_language("zh");
48//! let mut translator = HtmlTranslator::new(config).await?;
49//!
50//! // 翻译整个HTML文件
51//! translator.translate_file("input.html", "output_zh.html").await?;
52//! # Ok(())
53//! # }
54//! ```
55//!
56//! ### 与Monolith集成
57//!
58//! ```rust,no_run
59//! use html_translation_lib::{TranslationConfig, translate_before_merge};
60//! use markup5ever_rcdom::RcDom;
61//!
62//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
63//! // 在合并资源前翻译HTML内容
64//! let dom: RcDom = /* 解析的HTML DOM */;
65//! let config = TranslationConfig::new().target_language("zh");
66//! let translated_dom = translate_before_merge(dom, config).await?;
67//! // 然后继续使用monolith进行资源合并
68//! # Ok(())
69//! # }
70//! ```
71
72#![warn(missing_docs)]
73#![warn(rust_2018_idioms)]
74
75// 公开模块
76pub mod config;
77pub mod core;
78pub mod error;
79pub mod pipeline;
80pub mod storage;
81pub mod utils;
82
83// 测试工具模块 (仅在测试时可用)
84#[cfg(test)]
85pub mod test_utils;
86
87// 重新导出核心类型
88pub use config::{TranslationConfig, TranslationConfigBuilder};
89pub use core::HtmlTranslator;
90pub use error::{TranslationError, TranslationResult};
91
92use markup5ever_rcdom::RcDom;
93
94// 内部模块 (临时移除)
95// mod translator;
96
97// use markup5ever_rcdom::RcDom; // 临时注释掉未使用的导入
98
99/// 翻译HTML内容的便利函数
100///
101/// 这是一个简单的一次性翻译函数，适用于简单的翻译需求。
102/// 对于需要复杂配置或多次翻译的场景，建议使用 `HtmlTranslator`。
103///
104/// # 参数
105///
106/// * `html_content` - 要翻译的HTML内容字符串
107/// * `target_lang` - 目标语言代码（如 "zh", "en", "ja"）
108/// * `api_url` - 可选的翻译API URL
109///
110/// # 返回值
111///
112/// 返回翻译后的HTML内容字符串
113///
114/// # 示例
115///
116/// ```rust,no_run
117/// use html_translation_lib::translate_html_content;
118///
119/// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
120/// let html = r#"<h1>Hello World</h1>"#;
121/// let translated = translate_html_content(
122///     html,
123///     "zh",
124///     Some("http://localhost:1188/translate")
125/// ).await?;
126/// println!("{}", translated);
127/// # Ok(())
128/// # }
129/// ```
130#[cfg(feature = "async")]
131pub async fn translate_html_content(
132    html_content: &str,
133    target_lang: &str,
134    api_url: Option<&str>,
135) -> TranslationResult<String> {
136    let config = TranslationConfig::new()
137        .target_language(target_lang)
138        .api_url(api_url.unwrap_or("http://localhost:1188/translate"));
139    
140    let mut translator = HtmlTranslator::new(config).await?;
141    translator.translate_html(html_content).await
142}
143
144/// 在Monolith合并前翻译DOM内容
145///
146/// 专门为与Monolith工具集成而设计的函数。在资源合并之前对HTML内容进行翻译，
147/// 确保翻译后的内容能够正确地被Monolith处理。
148///
149/// # 参数
150///
151/// * `dom` - 要翻译的HTML DOM树
152/// * `config` - 翻译配置
153///
154/// # 返回值
155///
156/// 返回翻译后的DOM树，可以直接传给Monolith进行后续处理
157///
158/// # 示例
159///
160/// ```rust,no_run
161/// use html_translation_lib::{TranslationConfig, translate_before_merge};
162/// use markup5ever_rcdom::RcDom;
163///
164/// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
165/// let dom: RcDom = /* 从HTML文件解析的DOM */;
166/// let config = TranslationConfig::new()
167///     .target_language("zh")
168///     .enable_cache(true);
169///
170/// let translated_dom = translate_before_merge(dom, config).await?;
171/// // 现在可以传给monolith进行资源合并
172/// # Ok(())
173/// # }
174/// ```
175#[cfg(feature = "async")]
176pub async fn translate_before_merge(
177    dom: RcDom,
178    config: TranslationConfig,
179) -> TranslationResult<RcDom> {
180    let mut translator = HtmlTranslator::new(config).await?;
181    translator.translate_dom(dom).await
182}
183
184/// 同步版本的HTML内容翻译
185///
186/// 为不支持异步的环境提供的同步接口。内部使用异步运行时执行翻译。
187///
188/// # 参数
189///
190/// * `html_content` - 要翻译的HTML内容
191/// * `target_lang` - 目标语言代码
192/// * `api_url` - 可选的翻译API URL
193///
194/// # 示例
195///
196/// ```rust,no_run
197/// use html_translation_lib::translate_html_content_sync;
198///
199/// # fn example() -> Result<(), Box<dyn std::error::Error>> {
200/// let html = r#"<h1>Hello World</h1>"#;
201/// let translated = translate_html_content_sync(
202///     html,
203///     "zh",
204///     Some("http://localhost:1188/translate")
205/// )?;
206/// println!("{}", translated);
207/// # Ok(())
208/// # }
209/// ```
210#[cfg(feature = "sync")]
211pub fn translate_html_content_sync(
212    html_content: &str,
213    target_lang: &str,
214    api_url: Option<&str>,
215) -> TranslationResult<String> {
216    use tokio::runtime::Runtime;
217    
218    let rt = Runtime::new()
219        .map_err(|e| TranslationError::InternalError(format!("创建异步运行时失败: {e}")))?;
220    
221    rt.block_on(translate_html_content(html_content, target_lang, api_url))
222}
223
224/// 库信息
225#[derive(Debug, Clone)]
226pub struct LibraryInfo {
227    /// 库名称
228    pub name: &'static str,
229    /// 库版本
230    pub version: &'static str,
231    /// 支持的特性列表
232    pub features: Vec<&'static str>,
233}
234
235/// 获取库信息
236///
237/// 返回当前库的版本信息和启用的特性
238#[allow(clippy::vec_init_then_push)]
239pub fn get_library_info() -> LibraryInfo {
240    let mut features = Vec::new();
241    
242    #[cfg(feature = "async")]
243    features.push("async");
244    
245    #[cfg(feature = "sync")]
246    features.push("sync");
247    
248    LibraryInfo {
249        name: env!("CARGO_PKG_NAME"),
250        version: env!("CARGO_PKG_VERSION"),
251        features,
252    }
253}
html_translation_lib/lib.rs

html_translation_lib/
lib.rs
