TCDN 使用文档

TCDN 是零代码翻译CDN，通过DNS配置即可让你的网站支持104种语言，服务端渲染对搜索引擎友好，无需修改网站任何代码。

平台简介

TCDN (Translation CDN) 是一个服务端渲染的多语言翻译CDN解决方案。和传统前端JS翻译插件不同，TCDN在CDN层面对网页进行翻译，直接返回翻译好的完整HTML给浏览器和搜索引擎爬虫。

快速开始（5分钟配置）

只需三步，让你的网站拥有多语言能力：

接入模式选择

TCDN支持两种接入模式，根据你的需求选择：

🌍 子域名模式（推荐）

每个语言使用独立子域名，对SEO最友好，推荐跨境电商、出海SaaS使用。

# 源站（保持不变）
www.example.com
# 多语言版本
en.example.com   → 英文
ja.example.com   → 日文
de.example.com   → 德文
fr.example.com   → 法文
es.example.com   → 西班牙文

🔗 路径模式

统一域名下用路径区分语言，适合不想配置多个子域名的场景，需要在源站Nginx配置反向代理。

# 源站（保持不变）
example.com/
# 多语言版本
example.com/en/   → 英文
example.com/ja/   → 日文
example.com/de/   → 德文

添加网站

登录控制台后，在网站列表页面点击「添加网站」：

1. 网站名称：便于你识别，如"公司官网"
2. 源站域名：你的网站原始域名，如 www.example.com（不要带http://）
3. 源语言：网站内容的原始语言
4. 目标语言：勾选需要开启的目标语言（支持104种）
5. 接入模式：选择子域名或路径模式

DNS配置

子域名模式DNS配置

在你的域名DNS管理后台（如Cloudflare、阿里云解析、腾讯云解析等），为每个要开启的语言添加CNAME记录：

具体CNAME目标地址在添加网站后会在控制台显示。

语言设置

TCDN支持104种语言，你可以在网站配置页面随时增删目标语言。

常用语言代码

翻译引擎

默认使用内置免费翻译通道，开箱即用、无需任何API Key；正式上线建议在服务端配置 Google / DeepL / OpenAI 官方 API，翻译质量更高、稳定不排队。免费通道不可用时，已配置的官方引擎会自动无缝切换，翻译不中断，最终用户无需任何操作：

自定义术语库

术语库用于确保品牌名称、产品名称、专业词汇翻译一致性。

使用方法

1. 进入网站详情页，点击「术语库」标签
2. 选择语言对（如中文→英文）
3. 添加术语：原文、目标翻译
4. 保存后，翻译时会优先使用你的术语

缓存管理

TCDN采用本地磁盘+S3云存储双层缓存架构，页面翻译一次后全球CDN复用，缓存命中响应时间<50ms。

两种缓存刷新方式

缓存预热

缓存预热可以提前翻译页面，让用户首次访问就是秒开体验。

使用方法

1. 在网站TCDN配置页面找到「缓存预热」区域
2. 单URL预热：输入具体URL路径，点击预热
3. Sitemap批量预热：提交网站Sitemap地址，TCDN会自动抓取所有URL并批量翻译预热

图片翻译

图片OCR识别目前是管理后台中的一个独立工具（上传图片即可识别其中的文字），尚未作为开关集成到TCDN配置中，TCDN不会自动替换页面图片里的文字。

使用方式

在管理后台的「高级功能」中打开OCR工具，上传图片并选择语言，即可获取图片中的文字内容。

自定义CSS/JS注入

可以在翻译后的页面中注入自定义CSS或JavaScript，实现语言切换器、样式调整、统计代码等功能。

部署指南

以下是TCDN服务端的部署说明。如果你只是使用TCDN服务，不需要自己部署，直接使用我们托管的服务即可。

基础部署步骤

# 1. 克隆项目并安装依赖
git clone <repository-url>
cd tcdn-project
npm install

# 2. 配置环境变量
cp .env.example .env
# 编辑 .env 配置数据库、端口、翻译引擎API Key等

# 3. 初始化数据库
npm run db:init

# 4. 启动服务
pm2 start server-v6.js --name tcdn
pm2 save

宝塔面板部署

如果你使用宝塔面板，可以按照以下步骤部署：

1. 在宝塔软件商店安装「PM2管理器」和「Nginx」
2. 通过「文件」上传项目代码到 /www/wwwroot/tcdn
3. 在项目目录打开终端，执行 npm install 安装依赖
4. 复制 .env.example 为 .env，填写数据库等配置
5. 在PM2管理器中添加项目，启动文件选择 server-v6.js
6. 在宝塔网站中添加站点，配置反向代理到Node服务端口（默认3000）
7. 配置SSL证书（Let's Encrypt免费证书即可）

Nginx反向代理配置参考

如果使用路径模式，需要在源站Nginx配置反向代理：

# 在源站Nginx配置中添加
location ~^/(en|ja|de|fr|es)/(.*)$ {
    proxy_pass http://your-tcdn-server:3000/$2;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    # TCDN通过X-TCDN-Lang头识别目标语言
    proxy_set_header X-TCDN-Lang $1;
}

SEO说明

TCDN自动处理多语言SEO，你无需额外配置：

• hreflang标签：自动为每个语言版本生成 <link rel="alternate" hreflang="xx">，帮助Google识别语言关系
• canonical标签：每个页面指向自己的规范URL，避免重复内容问题
• x-default：自动添加，指向默认语言版本
• og:locale：Open Graph locale标签，优化社交媒体分享显示
• HTML lang属性：自动设置正确的 <html lang="xx">

常见问题

Q: 配置DNS后多久能生效？

通常1-10分钟，取决于你的DNS服务商TTL设置。如果长时间不生效，可以尝试刷新本地DNS缓存（ipconfig /flushdns 或修改DNS服务器为8.8.8.8）。

Q: 修改了术语为什么页面没变化？

修改术语后需要刷新对应页面的缓存。使用TCDN配置页面的「单页缓存刷新」功能，输入页面URL即可。刷新后下次访问就会用新术语重新翻译。

Q: 翻译字符数是怎么计算的？

只有第一次翻译页面时才会计入字符配额，缓存命中不计费。一个中文汉字算1个字符，英文单词按字母数计算。页面缓存后无论多少次访问都不再收费。

Q: 支持登录态页面吗（需要Cookie的页面）？

支持。TCDN会透传Cookie和请求头，登录用户看到的翻译页面和原站功能完全一致。注意：包含用户个性化内容的页面建议不要缓存太久或排除缓存。

Q: 怎么排除不需要翻译的内容？

在网站TCDN配置中，可以通过CSS选择器排除特定区域，比如给不需要翻译的元素加上 class="notranslate" 类名，然后在排除规则中添加该选择器。

Q: 翻译用什么通道？需要自己申请API Key吗？

默认使用内置免费翻译通道，开箱即用、不需要申请任何Key；正式上线建议在服务端 .env 中配置 Google / DeepL / OpenAI 官方 API，翻译质量高、稳定不排队。免费通道不可用时系统自动切换，保证翻译不中断。

Q: 子域名模式和路径模式哪个SEO更好？

Google官方表示两种方式都能被正确识别，但子域名模式在实际海外SEO中表现更优，因为各语言版本被视为独立站点，可以单独积累域名权重，推荐使用子域名模式。

Q: 页面上的视频/Flash内容会翻译吗？

不会。TCDN翻译HTML文本和图片文字，视频、音频、Flash等多媒体内容无法自动翻译。