网站翻译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 EndpointPOST /v1/website/translate
片段翻译端点Snippet EndpointPOST /v1/website/translate-snippet
任务查询端点Task Query EndpointGET /v1/website/tasks/{task_id}
认证AuthenticationBearer Token(Authorization 请求头)Bearer Token in Authorization header
请求体Request Bodyapplication/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/jsonMust be application/json

请求参数

Request Parameters

参数Parameter类型Type必填Required说明Description
urlstringrequired待翻译网站入口 URL,需以 http:// 或 https:// 开头Website entry URL; must start with http:// or https://
source_langstringrequired源语言代码,auto 为自动检测。详见语种列表Source language code; auto for auto-detection. See Language List
target_langsstring[]required目标语言列表,支持多语言同时翻译,如 ["en","ja","ko"],最多 10 种Target language list; supports multiple simultaneous translations, e.g. ["en","ja","ko"], max 10
preserve_tagsbooleanoptional是否保留 HTML 标签结构和属性,默认 truePreserve HTML tag structure and attributes, default true
exclude_selectorsstring[]optionalCSS 选择器排除列表,匹配的元素内容不翻译,如 [".brand-name","code","pre"]CSS selector exclusion list; matched elements are not translated, e.g. [".brand-name","code","pre"]
crawl_depthintegeroptional抓取深度:1(仅入口页)/ 2(入口页+同站链接)/ 3(递归 2 层)。默认 2Crawl depth: 1 (entry only) / 2 (entry + same-site links) / 3 (recursive 2 levels). Default 2
max_pagesintegeroptional最大抓取页数,1~500,默认 50Max pages to crawl, 1~500, default 50
translate_metabooleanoptional是否翻译 SEO 元数据(title、description、og 标签等),默认 trueTranslate SEO metadata (title, description, og tags), default true
translate_altbooleanoptional是否翻译图片 alt 属性文本,默认 trueTranslate image alt attribute text, default true
glossary_idstringoptional关联术语库 ID,确保站点术语翻译一致Associated glossary ID for consistent site terminology
callback_urlstringoptional异步翻译完成后的回调地址,结果通过 HTTP POST 推送Webhook URL; results pushed via HTTP POST on async completion

请求示例

Request Examples

# 整站翻译:多语言 + 排除品牌词
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
  }'

响应字段说明

Response Fields

字段Field类型Type说明Description
task_idstring翻译任务唯一 ID,用于查询进度和结果Unique task ID for progress query and results
statusstring任务状态:pending / processing / succeeded / failedStatus: pending / processing / succeeded / failed
pages_totalinteger抓取到的总页数Total pages crawled
pages_completedinteger已翻译完成的页数Pages translated so far
target_langsstring[]目标语言列表Target language list
estimated_secondsinteger预计完成耗时(秒)Estimated completion time in seconds
results_urlstring翻译结果 CDN 地址(任务完成后可用),按语言分目录存放Translated results CDN URL (available on completion); organized by language subdirectories
char_countinteger翻译字符总数(计费依据,仅完成时返回)Total translated characters (billing basis; returned on completion)
created_atstring任务创建时间(ISO 8601 UTC)Task creation time (ISO 8601 UTC)
completed_atstring任务完成时间(仅 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"
{
  "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
htmlstringrequired待翻译的 HTML 字符串,最大 50,000 字符HTML string to translate, max 50,000 chars
source_langstringrequired源语言代码,auto 为自动检测Source language code; auto for auto-detection
target_langstringrequired目标语言代码(片段翻译仅支持单语言)Target language code (snippet supports single language only)
preserve_tagsbooleanoptional是否保留 HTML 标签结构,默认 truePreserve HTML tag structure, default true
exclude_selectorsstring[]optionalCSS 选择器排除列表,匹配元素不翻译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"]
  }'

片段翻译响应

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
}
💡 片段翻译使用建议
  • 使用 exclude_selectors 排除 codepre 等代码块,避免源码被误翻译
  • 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
2000成功Success
4001001参数错误,请检查必填参数和参数格式Invalid parameter; check required fields and format
4001002不支持的语言代码Unsupported language code
4001010URL 格式无效或无法访问,请检查 URL 是否正确Invalid or inaccessible URL; verify the URL is correct
4001011目标语言数量超过 10 种上限Number of target languages exceeds the 10-language limit
4001012CSS 选择器语法错误,无法解析Invalid CSS selector syntax; cannot parse
4001013max_pages 超出 1~500 范围max_pages out of range (1~500)
4003011网站抓取失败,可能因 robots.txt 限制、需登录或反爬机制Website crawl failed; may be due to robots.txt restrictions, login required, or anti-crawl mechanisms
4003012HTML 片段超过 50,000 字符限制HTML snippet exceeds 50,000 character limit
4012001认证失败,Token 无效或已过期Authentication failed; invalid or expired token
4032003无权限访问该资源Access denied; insufficient permissions
4042005指定的 task_id 不存在或已过期Specified task_id does not exist or has expired
4133001请求体超出大小限制Request body exceeds size limit
4223013页面无有效可翻译文本(可能为纯图片或 JS 渲染页面)Page has no translatable text; may be image-only or JS-rendered
4294001请求频率超限,请稍后重试Rate limit exceeded; please retry later
4564002套餐配额已用尽,请升级或等待重置Plan quota exhausted; upgrade or wait for reset
5005001服务器内部错误,请重试或联系技术支持Internal server error; retry or contact support
5035002服务暂时不可用,建议稍后重试Service temporarily unavailable; retry later

最佳实践

Best Practices

  1. 合理设置抓取深度:仅翻译首页用 crawl_depth=1,多页面站点用 2,大型站点可设为 3 并配合 max_pages 控制规模。
  2. 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.
  3. 排除代码和品牌词:通过 exclude_selectors 排除 codepre、品牌名称等不应翻译的内容。
  4. Exclude Code & Brand Terms: Use exclude_selectors to exclude code, pre, and brand names that shouldn't be translated.
  5. 保留 SEO 元数据:默认开启 translate_meta,确保多语言站点的 title、description 等 SEO 标签同步翻译,利于搜索引擎收录。
  6. Preserve SEO Metadata: Keep translate_meta enabled by default; ensures SEO title/description tags are translated for search engine indexing.
  7. 术语库保证一致性:企业站点关联 glossary_id,确保产品名、专业术语在所有页面统一翻译。
  8. Glossary for Consistency: Link glossary_id for corporate sites to ensure product names and terminology are uniformly translated across all pages.
  9. 动态内容用片段翻译:SPA 应用、AJAX 加载的内容使用片段翻译接口实时处理,整站静态内容使用抓取翻译。
  10. Snippets for Dynamic Content: Use the snippet endpoint for SPA and AJAX-loaded content; use crawl translation for static site-wide content.
  11. 优先使用回调:整站翻译耗时较长,建议使用 callback_url 替代轮询,减轻服务器压力。
  12. 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
使用说明
  • 所有 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.