网站翻译 Website Translation
一键翻译整站 HTML,智能保留 DOM 结构、内联样式、JS 交互和 SEO 元数据。支持整站抓取翻译和 HTML 片段实时翻译两种模式,自动跳过代码块和脚本,可结合术语库确保多语言站点术语一致,适用于企业官网、电商平台、文档站点的多语言部署。 One-click full-site HTML translation with intelligent DOM, inline style, JS interaction, and SEO metadata preservation. Offers full-site crawl translation and HTML snippet real-time translation modes. Auto-skips code blocks and scripts; integrates glossary for consistent multi-site terminology across corporate sites, e-commerce, and documentation hubs.
快速概览 Quick Overview
属性 Attribute 说明 Description
整站翻译端点 Crawl Endpoint POST /v1/website/translate
片段翻译端点 Snippet Endpoint POST /v1/website/translate-snippet
任务查询端点 Task Query Endpoint GET /v1/website/tasks/{task_id}
认证 Authentication Bearer Token(Authorization 请求头) Bearer Token in Authorization header
请求体 Request Body application/json(JSON 格式)application/json (JSON format)
翻译模式 Translation Mode 整站抓取(异步)/ 片段翻译(同步实时) Full-site crawl (async) / Snippet (sync real-time)
最大页面数 Max Pages 单任务最多 500 页 Up to 500 pages per task
片段上限 Snippet Limit 单次最多 50,000 字符 Max 50,000 characters per snippet
DOM 保留 DOM Preservation 保留 HTML 结构、内联样式、JS 交互、SEO 标签 Preserves HTML structure, inline styles, JS interaction, SEO tags
网站抓取翻译 Crawl & Translate
POST /v1/website/translate
认证 Authentication
所有 API 请求需在 HTTP Header 中携带 Access Token。
All API requests must include an Access Token in the HTTP Header.
Authorization: Bearer {access_token}
请求头 Request Headers
请求头 Header 必填 Required 说明 Description
Authorizationrequired 格式 Bearer {access_token},用于身份认证 Format: Bearer {access_token}, used for authentication
Content-Typerequired 固定为 application/json Must be application/json
请求参数 Request Parameters
参数 Parameter 类型 Type 必填 Required 说明 Description
url string required 待翻译网站入口 URL,需以 http:// 或 https:// 开头 Website entry URL; must start with http:// or https://
source_lang string required 源语言代码,auto 为自动检测。详见语种列表 Source language code; auto for auto-detection. See Language List
target_langs string[] required 目标语言列表,支持多语言同时翻译,如 ["en","ja","ko"],最多 10 种 Target language list; supports multiple simultaneous translations, e.g. ["en","ja","ko"], max 10
preserve_tags boolean optional 是否保留 HTML 标签结构和属性,默认 true Preserve HTML tag structure and attributes, default true
exclude_selectors string[] optional CSS 选择器排除列表,匹配的元素内容不翻译,如 [".brand-name","code","pre"] CSS selector exclusion list; matched elements are not translated, e.g. [".brand-name","code","pre"]
crawl_depth integer optional 抓取深度:1(仅入口页)/ 2(入口页+同站链接)/ 3(递归 2 层)。默认 2 Crawl depth: 1 (entry only) / 2 (entry + same-site links) / 3 (recursive 2 levels). Default 2
max_pages integer optional 最大抓取页数,1~500,默认 50 Max pages to crawl, 1~500, default 50
translate_meta boolean optional 是否翻译 SEO 元数据(title、description、og 标签等),默认 true Translate SEO metadata (title, description, og tags), default true
translate_alt boolean optional 是否翻译图片 alt 属性文本,默认 true Translate image alt attribute text, default true
glossary_id string optional 关联术语库 ID,确保站点术语翻译一致 Associated glossary ID for consistent site terminology
callback_url string optional 异步翻译完成后的回调地址,结果通过 HTTP POST 推送 Webhook URL; results pushed via HTTP POST on async completion
请求示例 Request Examples
cURL
Python
JavaScript
Java
Go
# 整站翻译:多语言 + 排除品牌词
curl -X POST https://api.itranslator.cc/v1/website/translate \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/about",
"source_lang": "zh",
"target_langs": ["en", "ja", "ko"],
"preserve_tags": true,
"exclude_selectors": [".brand-name", "code", "pre"],
"translate_meta": true,
"callback_url": "https://myapp.com/webhook/website-translate"
}'
# 仅翻译首页(crawl_depth=1)
curl -X POST https://api.itranslator.cc/v1/website/translate \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com",
"source_lang": "auto",
"target_langs": ["en"],
"crawl_depth": 1,
"max_pages": 1
}'
import requests
import time
token = "YOUR_ACCESS_TOKEN"
url = "https://api.itranslator.cc/v1/website/translate"
# 提交整站翻译任务
payload = {
"url": "https://example.com/about",
"source_lang": "zh",
"target_langs": ["en", "ja", "ko"],
"preserve_tags": True,
"exclude_selectors": [".brand-name", "code", "pre"],
"translate_meta": True,
"glossary_id": "gl_brand_001",
"callback_url": "https://myapp.com/webhook/website-translate"
}
resp = requests.post(
url,
headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
json=payload
)
task = resp.json()
task_id = task["task_id"]
print(f"任务已提交: {task_id}, 预计耗时: {task['estimated_seconds']}s")
# 轮询任务状态
while True:
status = requests.get(
f"https://api.itranslator.cc/v1/website/tasks/{task_id}",
headers={"Authorization": f"Bearer {token}"}
).json()
print(f"进度: {status['pages_completed']}/{status['pages_total']}")
if status["status"] in ("succeeded", "failed"):
break
time.sleep(5)
if status["status"] == "succeeded":
print(f"✅ 翻译完成,结果地址: {status['results_url']}")
const axios = require("axios");
const token = process.env.API_TOKEN;
// 提交整站翻译任务
const resp = await axios.post(
"https://api.itranslator.cc/v1/website/translate",
{
url: "https://example.com/about",
source_lang: "zh",
target_langs: ["en", "ja", "ko"],
preserve_tags: true,
exclude_selectors: [".brand-name", "code", "pre"],
translate_meta: true,
callback_url: "https://myapp.com/webhook/website-translate"
},
{ headers: { Authorization: `Bearer ${token}` } }
);
const { task_id, estimated_seconds } = resp.data;
console.log(`任务已提交: ${task_id}, 预计耗时: ${estimated_seconds}s`);
// 查询任务状态
const status = await axios.get(
`https://api.itranslator.cc/v1/website/tasks/${task_id}`,
{ headers: { Authorization: `Bearer ${token}` } }
);
console.log(`状态: ${status.data.status}, 进度: ${status.data.pages_completed}/${status.data.pages_total}`);
import okhttp3.*;
import com.google.gson.Gson;
import java.util.Arrays;
import java.util.List;
import java.util.Map;
OkHttpClient client = new OkHttpClient();
// 构建请求体(使用 Gson 序列化)
Map payload = new java.util.HashMap<>();
payload.put("url", "https://example.com/about");
payload.put("source_lang", "zh");
payload.put("target_langs", Arrays.asList("en", "ja", "ko"));
payload.put("preserve_tags", true);
payload.put("exclude_selectors", Arrays.asList(".brand-name", "code", "pre"));
payload.put("translate_meta", true);
String json = new Gson().toJson(payload);
RequestBody body = RequestBody.create(json,
MediaType.parse("application/json"));
Request request = new Request.Builder()
.url("https://api.itranslator.cc/v1/website/translate")
.header("Authorization", "Bearer " + token)
.header("Content-Type", "application/json")
.post(body)
.build();
try (Response response = client.newCall(request).execute()) {
System.out.println(response.body().string());
}
package main
import (
"bytes"
"encoding/json"
"fmt"
"io"
"net/http"
"os"
)
func main() {
payload, _ := json.Marshal(map[string]interface{}{
"url": "https://example.com/about",
"source_lang": "zh",
"target_langs": []string{"en", "ja", "ko"},
"preserve_tags": true,
"exclude_selectors": []string{".brand-name", "code", "pre"},
"translate_meta": true,
})
req, _ := http.NewRequest("POST",
"https://api.itranslator.cc/v1/website/translate",
bytes.NewBuffer(payload))
req.Header.Set("Authorization", "Bearer "+os.Getenv("API_TOKEN"))
req.Header.Set("Content-Type", "application/json")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}
响应字段说明 Response Fields
字段 Field 类型 Type 说明 Description
task_id string 翻译任务唯一 ID,用于查询进度和结果 Unique task ID for progress query and results
status string 任务状态:pending / processing / succeeded / failed Status: pending / processing / succeeded / failed
pages_total integer 抓取到的总页数 Total pages crawled
pages_completed integer 已翻译完成的页数 Pages translated so far
target_langs string[] 目标语言列表 Target language list
estimated_seconds integer 预计完成耗时(秒) Estimated completion time in seconds
results_url string 翻译结果 CDN 地址(任务完成后可用),按语言分目录存放 Translated results CDN URL (available on completion); organized by language subdirectories
char_count integer 翻译字符总数(计费依据,仅完成时返回) Total translated characters (billing basis; returned on completion)
created_at string 任务创建时间(ISO 8601 UTC) Task creation time (ISO 8601 UTC)
completed_at string 任务完成时间(仅 succeeded 时返回) Completion time (only when succeeded)
响应示例 Response Examples
提交任务 Submit Task
{
"task_id": "web-t_abc123",
"status": "processing",
"pages_total": 12,
"pages_completed": 0,
"target_langs": ["en", "ja", "ko"],
"estimated_seconds": 120,
"results_url": "https://cdn.itranslator.cc/websites/web-t_abc123/",
"created_at": "2026-07-21T10:00:00Z"
}
任务完成(回调推送) Task Completed (Callback)
翻译完成后,结果通过 HTTP POST 推送到 callback_url:
On completion, the result is pushed via HTTP POST to the callback_url:
{
"task_id": "web-t_abc123",
"status": "succeeded",
"pages_total": 12,
"pages_completed": 12,
"target_langs": ["en", "ja", "ko"],
"char_count": 45600,
"results_url": "https://cdn.itranslator.cc/websites/web-t_abc123/",
"created_at": "2026-07-21T10:00:00Z",
"completed_at": "2026-07-21T10:02:15Z"
}
查询任务状态 Query Task Status
GET /v1/website/tasks/{task_id}
查询整站翻译任务的状态和进度。建议轮询间隔 5~10 秒,或使用 callback_url 回调模式。
Query the status and progress of a website translation task. Recommended polling interval: 5~10 seconds, or use callback_url callback mode.
curl -X GET https://api.itranslator.cc/v1/website/tasks/web-t_abc123 \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Copy
{
"task_id": "web-t_abc123",
"status": "processing",
"pages_total": 12,
"pages_completed": 8,
"target_langs": ["en", "ja", "ko"],
"estimated_seconds": 40,
"created_at": "2026-07-21T10:00:00Z"
}
HTML 片段翻译 HTML Snippet Translation
POST /v1/website/translate-snippet
直接传入 HTML 字符串,返回翻译后的 HTML。同步实时返回,适合动态页面、AJAX 内容、SPA 应用的实时翻译。单次最大 50,000 字符。 Pass HTML strings directly and get translated HTML back synchronously. Ideal for dynamic pages, AJAX content, and SPA real-time translation. Max 50,000 characters per request.
片段翻译参数 Snippet Parameters
参数 Parameter 类型 Type 必填 Required 说明 Description
html string required 待翻译的 HTML 字符串,最大 50,000 字符 HTML string to translate, max 50,000 chars
source_lang string required 源语言代码,auto 为自动检测 Source language code; auto for auto-detection
target_lang string required 目标语言代码(片段翻译仅支持单语言) Target language code (snippet supports single language only)
preserve_tags boolean optional 是否保留 HTML 标签结构,默认 true Preserve HTML tag structure, default true
exclude_selectors string[] optional CSS 选择器排除列表,匹配元素不翻译 CSS selector exclusion list; matched elements not translated
curl -X POST https://api.itranslator.cc/v1/website/translate-snippet \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"html": "<h1>欢迎光临</h1><p>我们提供最好的服务。</p><pre>const x = 1;</pre>",
"source_lang": "zh",
"target_lang": "en",
"exclude_selectors": ["pre"]
}'
Copy
片段翻译响应 Snippet Response
{
"translated_html": "<h1>Welcome</h1><p>We provide the best service.</p><pre>const x = 1;</pre>",
"source_lang": "zh",
"target_lang": "en",
"char_count": 18
}
💡 片段翻译使用建议
💡 Snippet Translation Tips
使用 exclude_selectors 排除 code、pre 等代码块,避免源码被误翻译
Use exclude_selectors to exclude code, pre blocks to prevent source code from being translated
适合在浏览器端通过 JS SDK 实时翻译动态加载的内容,实现无刷新的多语言切换
Ideal for client-side real-time translation of dynamically loaded content via JS SDK for seamless language switching
长 HTML 超过 50,000 字符时建议分段处理或使用整站翻译接口
For HTML exceeding 50,000 chars, chunk the content or use the full-site translation endpoint
错误码 Error Codes
HTTP Code 错误码 Error Code 说明 Description
200 0成功 Success
400 1001参数错误,请检查必填参数和参数格式 Invalid parameter; check required fields and format
400 1002不支持的语言代码 Unsupported language code
400 1010URL 格式无效或无法访问,请检查 URL 是否正确 Invalid or inaccessible URL; verify the URL is correct
400 1011目标语言数量超过 10 种上限 Number of target languages exceeds the 10-language limit
400 1012CSS 选择器语法错误,无法解析 Invalid CSS selector syntax; cannot parse
400 1013max_pages 超出 1~500 范围 max_pages out of range (1~500)
400 3011网站抓取失败,可能因 robots.txt 限制、需登录或反爬机制 Website crawl failed; may be due to robots.txt restrictions, login required, or anti-crawl mechanisms
400 3012HTML 片段超过 50,000 字符限制 HTML snippet exceeds 50,000 character limit
401 2001认证失败,Token 无效或已过期 Authentication failed; invalid or expired token
403 2003无权限访问该资源 Access denied; insufficient permissions
404 2005指定的 task_id 不存在或已过期 Specified task_id does not exist or has expired
413 3001请求体超出大小限制 Request body exceeds size limit
422 3013页面无有效可翻译文本(可能为纯图片或 JS 渲染页面) Page has no translatable text; may be image-only or JS-rendered
429 4001请求频率超限,请稍后重试 Rate limit exceeded; please retry later
456 4002套餐配额已用尽,请升级或等待重置 Plan quota exhausted; upgrade or wait for reset
500 5001服务器内部错误,请重试或联系技术支持 Internal server error; retry or contact support
503 5002服务暂时不可用,建议稍后重试 Service temporarily unavailable; retry later
最佳实践 Best Practices
合理设置抓取深度 :仅翻译首页用 crawl_depth=1,多页面站点用 2,大型站点可设为 3 并配合 max_pages 控制规模。
Set Crawl Depth Wisely : Use crawl_depth=1 for homepage only, 2 for multi-page sites, 3 for large sites with max_pages to control scope.
排除代码和品牌词 :通过 exclude_selectors 排除 code、pre、品牌名称等不应翻译的内容。
Exclude Code & Brand Terms : Use exclude_selectors to exclude code, pre, and brand names that shouldn't be translated.
保留 SEO 元数据 :默认开启 translate_meta,确保多语言站点的 title、description 等 SEO 标签同步翻译,利于搜索引擎收录。
Preserve SEO Metadata : Keep translate_meta enabled by default; ensures SEO title/description tags are translated for search engine indexing.
术语库保证一致性 :企业站点关联 glossary_id,确保产品名、专业术语在所有页面统一翻译。
Glossary for Consistency : Link glossary_id for corporate sites to ensure product names and terminology are uniformly translated across all pages.
动态内容用片段翻译 :SPA 应用、AJAX 加载的内容使用片段翻译接口实时处理,整站静态内容使用抓取翻译。
Snippets for Dynamic Content : Use the snippet endpoint for SPA and AJAX-loaded content; use crawl translation for static site-wide content.
优先使用回调 :整站翻译耗时较长,建议使用 callback_url 替代轮询,减轻服务器压力。
Prefer Callbacks : Full-site translation takes time; use callback_url instead of polling to reduce server load.
应用场景 Use Cases
场景 Scenario 推荐配置 Recommended Config 说明 Notes
🏢 企业官网
Corporate Website
整站翻译 + 术语库 + SEO
Full-site + glossary + SEO
多语言企业站点,保留品牌词和 SEO 元数据
Multi-language corporate site; preserve brand terms and SEO metadata
🛒 电商平台
E-commerce
片段翻译 + 排除选择器
Snippet + exclude selectors
商品页动态内容实时翻译,排除价格、SKU 等不翻译
Real-time product page translation; exclude prices, SKUs
📚 文档站点
Documentation Hub
整站翻译 + 排除代码块
Full-site + exclude code
技术文档多语言化,排除 code/pre 代码块
Multi-language technical docs; exclude code/pre blocks
📰 新闻/博客
News/Blog
整站翻译 + 多语言
Full-site + multi-language
内容站点批量多语言翻译,保留文章排版
Batch multi-language content translation; preserve article layout
⚛️ SPA 应用
SPA Application
片段翻译(前端 SDK)
Snippet (frontend SDK)
React/Vue 等单页应用实时翻译动态渲染内容
Real-time translation for React/Vue SPA dynamic content
🌐 落地页/营销页
Landing Page
整站翻译 + SEO + 情绪
Full-site + SEO + emotion
营销活动页面多语言,保留转化追踪代码和表单
Multi-language campaign pages; preserve tracking codes and forms
使用说明
Notes
所有 API 请求均使用 HTTPS,建议开启 HTTP Keep-Alive 以提高性能。
All API requests use HTTPS; enable HTTP Keep-Alive for better performance.
请勿在客户端代码中暴露 Access Token,建议通过后端代理调用。
Do not expose your Access Token in client-side code; use a backend proxy.
推荐设置合理的超时时间(30 秒),并实现指数退避重试策略。
Set a reasonable timeout (30s) and implement exponential backoff for retries.