多语言站点
标准版及以上商业版功能
校对日期:2026-10-02。需要商业版标准版及以上。 本文面向站点管理员、内容运营人员、主题开发者和前后端集成人员。
一、先了解系统如何实现多语言
UJCMS 通过为每个语言版本建立独立站点来实现多语言网站:
中文主站(Site 1,zh-CN)
├── 英文站(Site 5,en,语言组主站 = Site 1)
└── 日文站(Site 8,ja,语言组主站 = Site 1)每个语言站都有独立的栏目、文章、主题、权限和静态页。各站点通过“语言组”建立关联; 不同语言的栏目通过相同的栏目别名对应,文章则通过手动或通过翻译功能建立的译文关联对应。
| 概念 | 数据含义 | 使用影响 |
|---|---|---|
站点语言 lang | BCP-47 标准语言标签,如 zh-CN、en、en-US | 用于 <html lang>、语言切换和 hreflang |
| 语言组主站 | langParentId 为空,且有语言变体指向它 | 仅作为语言组的关联基准,不等同于站点树中的上级站点 |
| 语言变体 | langParentId 指向组内主站 | 与主站仍是完整、独立的站点 |
| 栏目对应关系 | 组内栏目使用相同别名(slug,即栏目页 /channel/{别名} 中的一段) | 决定栏目页能否精确切换 |
| 文章对应关系 | 文章加入同一个翻译组 | 决定文章页能否直达译文并输出 hreflang |
语言组与站点树的父子关系相互独立。不要为了建立语言关系而调整站点树,应使用站点表单中的 “语言组”字段完成配置。
版本说明:单站点的语言字段、模板变量和公开 API 在社区版中均可使用;语言组至少需要两个站点, 因此依赖商业版标准版的多站点能力。
二、规划访问地址
推荐方案
| 场景 | 全局“多域名” | 示例 | 建议 |
|---|---|---|---|
| 单个业务网站、多种语言 | 关闭 | example.com/、example.com/en/ | 最简单,语言用子目录 |
| 单个业务网站、多种语言 | 开启 | www.、en.example.com/ | 需要 DNS、证书和反向代理支持 |
| 多个业务网站、多种语言 | 开启 | a.example.com/、a.example.、b.example.com/、b.example. | 推荐:业务网站用子域名,语言用子目录 |
| 多个业务网站、多种语言、单域名 | 关闭 | example.、example. | 只能使用单层子目录 |
系统目前只能识别一段子目录。example. 这类两段式站点前缀不受支持,请改用 site-a-en,或采用“站点子域名 + 语言子目录”的推荐方案。
“多域名”开关的实际作用
入口:配置 → 全局设置 → 基础设置 → 多域名。
- 关闭时,非空子目录在全部站点中必须唯一;静态页共用同一套输出目录结构。
- 开启时,系统按
(域名, 子目录)的组合区分站点,因此a.example.与com/ en/ b.example.可以共存;静态页也会先按域名分目录。com/ en/ - 使用子域名或多个独立域名时应先开启,再创建站点。已有重复子目录后不要直接关闭此开关。
- 每个站点的“域名”只填写主机名,如
en.example.com,不要带协议、端口或路径;协议和全局 端口需分别配置。
子目录只允许字母、数字、下划线和连字符组成的单段值。以下值保留,不可用作子目录: uploads、themes、WEB-INF、cp、api、frontend、m(忽略大小写)。
系统如何根据请求定位站点
无子目录:Host 对应的无子目录站点 → 全局默认站点
有子目录:(Host, subDir) 精确匹配 → 全局唯一的 subDir 兼容回退 → 404因此,在生产环境中应将真实的 Host 请求头传给 UJCMS,并确保 DNS、TLS 证书和反向代理均覆盖 已配置的域名。由于兼容回退机制的存在,全局唯一的子目录站点可能通过其他 Host 访问;主题应输出 规范链接(canonical),反向代理也应拒绝未登记的 Host。
两点补充:
- 兼容回退只在子目录全局唯一时生效。开启多域名后,如果两个站点使用相同的子目录,而请求 Host 又不匹配其中任何一个(常见原因是站点“域名”留空),系统将返回 404,并在日志中输出 WARN,提示补充域名;系统不会随意匹配其中一个站点。
- 解析站点时不会判断站点状态。已关闭的站点仍可被解析,但会返回 503,并显示
themes/错误页,而不是返回 404;同时,该站点不会出现在语言组备选项中。error/ site_ disabled. html
三、在控制台创建语言版本
1. 设置主站语言
单站点版本可在 配置 → 站点设置 → 基础设置 → 语言 中修改;多站点管理员还可在 系统 → 站点管理 → 编辑 中设置。请使用标准语言标签,例如:
- 简体中文:
zh-CN - 繁体中文(台湾):
zh-TW - 英语:
en;需要区分地区时可用en-US、en-GB
新建站点和已有站点的默认值均为 zh-CN。通常,同一语言组中的每种语言只能出现一次。
语言下拉列表中的选项来自全局字典 站点语言(别名 sys_site_lang)。系统预置 12 种语言: zh-CN、zh-TW、en、ja、ko、de、fr、es、pt、ru、ar、it。可在 配置 → 字典管理 → 站点语言 中添加、删除或修改选项(该字典属于全局数据,需要全局数据权限;没有该权限的账号在字典管理中 只能查看,页面会标明“只读”);也可以直接输入列表之外的标准语言标签。
升级提示:此功能上线前创建的角色缺少“字典”权限,站点表单不显示候选列表(仍可直接 输入)。在角色权限中重新保存一次该角色即可补上。
语言列表已于 2026-09-02 从 3 种扩充至 12 种。在此之前已经执行过该数据库变更集的数据库中 只有 zh-CN、zh-TW、en 三项,Liquibase 不会重复执行;请在 配置 → 字典管理 → 站点语言 中手动补充其余语言,或重新创建数据库。
同一语言组内进行“语言重复”校验时,也会计入已关闭的站点。即使关闭的站点不显示在语言 切换器中,它仍会占用相应语言;需要先修改该站点的语言或将其删除。
2. 创建语言变体
进入 系统 → 站点管理,在主站所在行点击新增语言版本(需要 site:create 权限)。系统将 打开通用的“站点管理 - 新增”表单,并自动填写来源站点的名称、协议、域名、上级站点、所属组织和 “复制站点”等信息:
- 修改站点名称(默认与来源站点相同),并选择目标“语言”(默认为空)。
- 确认“语言组”指向正确的组主站。即使从某个语言变体点击“新增语言版本”,系统也会预填 该变体所属的主站。
- 根据地址方案填写协议、域名和子目录。选定语言后,如果子目录为空,系统会自动填入小写语言 标签(例如,选择
en后会填入en),也可手动修改:- 同域名英文版:域名沿用主站,子目录保留自动填入的
en; - 英文子域名:域名填
en.example.com,清空子目录,并先开启“多域名”; - 多站点推荐方案:域名填该业务站点域名,子目录填语言码。
- 同域名英文版:域名沿用主站,子目录保留自动填入的
- 保留“复制数据”中默认选中的 模板 / 模型 / 栏目 三项。普通“新增”操作只默认选中前两项; 三项之间存在依赖关系,选择“栏目”时必然同时包含模板和模型。复制栏目时会保留别名,这是 自动映射栏目页的基础。
- 保存后确认新站点状态为“正常”,再在主站中使用“批量新增译文”翻译栏目和文章(见“维护栏目和文章的对应关系”一节)。
“新增语言版本”只会复制已有结构,不会自动翻译栏目和文章内容。建站后,在源语言站点新增的 栏目也不会自动出现在其他语言站点中。这两种情况都可以通过“维护栏目和文章的对应关系”一节介绍的栏目“批量新增译文”功能 处理。站点列表中的“语言”列只为语言组成员显示标签,独立站点则留空。
3. 配置后的快速检查
至少访问以下地址:
主站首页
语言站首页
主站的一个栏目页
语言站的同别名栏目页
/sitemap-channel.xml(子目录站点为 /en/sitemap-channel.xml)检查页面最终生成的绝对 URL,确认其中的协议、域名、全局端口和子目录均正确。
四、维护栏目和文章的对应关系
栏目:用相同别名自动对应
栏目名称可以翻译,但不同语言站点中的对应栏目应使用相同的别名。例如,中文站的“新闻”和 英文站的“News”都使用 news。系统根据“目标站点 ID + 栏目别名”查找对应栏目:
- 找到同别名栏目:栏目页可以精确对应,并输出
hreflang; - 未找到同别名栏目:可见的语言切换器沿上级栏目逐级查找,进入最近一个有同别名栏目的上级 (例如中文站“新闻 › 国内”在英文站没有对应栏目,切换后进入英文站的“News”);各级都没有时才 回退到目标语言首页。回退地址不会写入
hreflang。
两个语言站点的栏目树不必完全一致:让对应的栏目使用相同别名即可,各自独有的子栏目会落到共同的上级。 重命名栏目别名会同时影响栏目页切换,以及未建立文章翻译链接时的文章页回退地址。
栏目:批量新增译文(商业版标准版)
此功能用于将当前站点的栏目同步并翻译到语言组内的其他站点。入口:内容 → 栏目管理 → 批量新增译文(需要 channel: 权限;当前站点不属于语言组时不显示该按钮)。 操作方向与文章批量新增译文一致:在源语言站点执行,处理结果写入目标站点,当前站点的栏目 保持不变。对话框顶部会显示“翻译方向:当前站点语言 → 目标站点语言”。
- 选择目标站点(支持多选,默认选中同组的所有站点),并按需限定某个栏目及其子栏目(默认为 全站)。弹窗会为每个站点显示一行预览:“共 N 个栏目:可新建 a 个,待翻译 b 个(含正文 c 篇),已翻译或已修改 d 个”。如果因目标站点缺少同名模型或上级栏目而无法新建,且数量 不为零,系统还会追加显示相应数量。
- 选择本次使用的服务商:仅新建栏目(不翻译)、大模型服务商、机器翻译引擎。默认选中全局 “翻译服务商”;未设置时,依次使用“默认服务商”和第一个可用选项。文章批量新增译文的默认 行为不同:未设置服务商时,默认选择“仅创建草稿”。选择多个目标站点时,只列出所有目标站点 共同可用的服务商。大模型的译文通常更符合目标语言网站的导航和 SEO 表达习惯,机器翻译引擎 则速度更快、成本更低。
- 确认后,系统会按站点逐一同步执行,弹窗显示“正在处理 X(第 n/m 个站点)”。该操作不是 后台任务,因此没有任务记录和停止按钮。某个站点处理失败后,系统会提示错误并继续处理下一个 站点,最后汇总显示结果;预览数量为零的站点不会发起请求。
每个站点的执行分两步:
- 新建:对于目标站点中不存在的同别名栏目,系统将按照建站复制规则创建栏目,包括设置、 正文、定制字段、访问组和角色权限;静态页、流程和访问量会被清零。系统按别名匹配上级栏目。 限定栏目子树时,如果目标站点中不存在上级栏目,该栏目会被计入“无上级栏目”,且不会新建。 系统按“同类型 + 同名”匹配目标站点中的模型;如果未找到,但源模型是全局共享模型,则直接 沿用源模型,否则计入“无同名模型”并跳过。每个栏目都会单独提交;如果中途失败,已创建的 栏目会保留,再次运行即可继续创建。
- 翻译:把新建栏目以及已存在但仍与本站完全相同(即未翻译)的名称、SEO 标题/关键词/ 描述和正文(例如“关于我们”这类单页栏目)翻译为目标站点语言。别名和定制字段值保持不变; 任何与源站点不同的值都会被视为已翻译或已手动修改,系统不会覆盖。因此,该操作可以安全地 重复执行。刚建站时,所有栏目均与来源站点相同,一次执行即可完成全部翻译。名称和 SEO 字段 通过一次调用成批翻译,结果会按字段长度上限截断:名称 50 个字符,SEO 标题和关键词 150 个 字符,描述 1000 个字符。如果这一步失败,整批结果都不会写入,也不会继续翻译正文,弹窗会 提示“栏目未翻译”。之后,系统会逐个翻译栏目正文并立即写回;超过 24000 个字符的正文将直接 跳过。单篇失败会列入“以下栏目正文未翻译,重跑可补译”;额度用尽或 AI 被关闭后,系统将停止 处理剩余正文。
如果预览提示“没有可新建或待翻译的栏目”,说明目标站点中已存在所有同别名栏目,且各字段都与 源站点不同。此时不再显示服务商下拉列表,“开始”按钮也会置灰。这并非缺少翻译引擎,而是没有 需要翻译的内容。
注意:
- 该功能只受全局 AI 开关约束,不受站点设置中的“AI预翻译”开关影响;文章的两种翻译操作 则同时受这两个开关影响。AI 未开启或没有可用服务商时,弹窗会用黄色提示说明原因,但仍可选择 “仅新建栏目”。
- 目标栏目正文为空时不会翻译正文(比对以目标值为准);刻意在各语言保持相同的值(如品牌名) 每次重新运行时都会被视为尚未翻译,并再次翻译。可以修改其中一个字符,或避免对该栏目子树 重复运行此功能。
- 删除、移动或修改别名不会同步;修改过别名的栏目在目标站点中会被视为新栏目。
- 正文在当前请求中完成翻译。翻译多个单页栏目可能需要数分钟:控制台最长等待 10 分钟,机器 翻译引擎的单次 HTTP 调用读取超时时间为 60 秒。反向代理的读取超时时间需相应延长,具体要求 与下文 AI 预翻译相同。
- 用量计入源站点的每日额度和 AI 调用日志;操作日志名称为“批量新增栏目译文”。
文章:手动关联对应译文
先在各语言站点中分别创建并发布文章,再建立翻译关系:
- 打开 内容 → 文章管理,编辑一篇已经保存的文章。
- 表单底部会显示“翻译”区域,每个对应的语言站点占一行。
- 按标题搜索并选择对应文章(每次最多列出 20 条,已经属于其他翻译组的文章不会显示;标题 相近时请输入更完整的标题),点击该行“保存”(需
article:update)。清空选择后保存可解除 该语言的关联。 - 如启用了静态页,切换到所有相关语言站重新生成这些文章页。
关联成功后,切换文章语言时会直接打开对应文章,且 exact=true。此时,主题和 sitemap 才会 将其作为文章级 hreflang 输出。处于草稿、待审等不可访问状态的目标译文不会出现在公开备选项 中;已发布和已归档的文章则可以显示。
如果旧站中的两个语言站点已经分别录入文章,也需要在此处逐篇关联。系统不支持按别名或标题 自动批量关联:文章别名较少使用,别名和标题通常也不会在不同语言中保持一致,因而缺少可靠的 自动匹配依据。通过“新增译文”或“批量新增译文”创建的译文会由系统自动关联,无需手动处理。
翻译组遵循以下规则:
- 只能关联同一语言组内、分属不同站点的文章;
- 一个翻译组在每个站点最多有一篇文章(草稿同样占位);
- 一篇文章最多属于一个翻译组;
- 如果两篇文章已经分别属于不同的翻译组,系统不会自动合并;必须先解除其中一篇文章的关联, 再重新建立关联。
新增译文:一键创建并关联草稿(商业版标准版)
目标站点中还没有对应文章时,无需手动切换站点并重新创建。在“翻译”区域的目标站点所在行点击 新增译文:
- 弹出的对话框会根据源栏目别名,预先选择目标站点中的同别名栏目,也可以改选其他栏目。 如果该行本可使用 AI 预翻译(见下文),对话框中还会出现“创建后立即 AI 预翻译”,默认 勾选,下方可选择本次使用的翻译服务商(默认为全局设置的翻译服务商):确定后系统先创建草稿, 再立即翻译标题、SEO 字段和正文,无需再点一次“AI 预翻译”;只想复制原文时取消勾选即可。 目标语言没有可用服务商时(AI 未开启或未配置),勾选框不可用并显示原因。
- 系统在目标站点创建一篇草稿副本(复制标题、副标题、正文、SEO、图片/附件与定制字段; 不复制标签——请在目标站点补充目标语言标签;静态页、审核流程、百度推送、AIGC 标记与 浏览量、评论数等计数清零),并自动加入当前文章的翻译组。
- 切换到目标站点,完成翻译和校对后发布;如果启用了静态页,还需重新生成相关页面。
草稿不会进入审核流程,也不会显示在前台、hreflang 或 sitemap 中,发布后才会生效。 该操作需要“新增译文”权限,并且操作者所属的组织必须拥有目标站点的权限。系统会根据目标栏目 的模型重组定制字段;如果两侧模型不一致,无法匹配的字段将被舍弃。
可能过期:提醒译文需要同步
建立关联后,翻译组会跟踪各语言版本的同步状态。如果某篇文章在“最近一次同步”后发生过 原创修改,组内其他成员会在文章列表和“翻译”区域显示可能过期标签。文章列表会为已关联 且未过期的文章显示“已关联翻译”图标;文章表单的“翻译”区域则会在标题旁标记当前文章自身 是否过期。
系统不区分修改了哪个字段:对于一篇已发布或已归档且自身当前不处于“可能过期”状态的 文章,只要标题、SEO、正文、图片/附件或定制字段中任何一项与保存前不同,这次保存就被视为原创 修改,并将组内其他成员标记为过期。内容没有实际变化的保存(例如新增译文后顺手点击了源文的 “保存”)不算原创修改,不会把刚建的译文标为过期。因此:
- 编辑并保存被标记的文章,即表示该文章已同步。编辑界面会显示标签,保存前请一并核对另一语言 版本中的修改;
- 草稿阶段的修改不会影响其他语言版本。保存译文草稿(包括 AI 预翻译写入)不会反过来将源文 标记为“可能过期”;
- 重新关联表示确认“当前内容一致”。解除关联后再重新关联会重置过期状态;刚编辑过的文章加入 已有翻译组时,也不会立即将组内成员标记为过期;
- 审核通过或驳回、归档、下线、置顶等不修改正文内容的操作不参与判定;
- 该标签仅用于提醒,不能保证识别所有同步情况。例如,同时编辑两个语言版本时,可能因保存先后顺序 产生误判。该标签不影响发布和
hreflang输出。
AI 预翻译(商业版标准版)
站点开启“AI预翻译”(配置 → 站点设置 → AI功能,默认开启),且操作者拥有 ai:translate 权限(权限树中的 日志 → AI日志 → AI预翻译)时,“翻译”区域中已关联的草稿译文所在行 会显示 AI 预翻译 按钮。显示按钮时不会检查全局 AI 开关和服务商配置;如果缺少相关配置, 点击后才会报错(见问题排查表)。点击后弹出对话框,可为本次翻译选择服务商:列出全部大模型服务商 和支持该语言对的机器翻译引擎,默认选中全局设置的“翻译服务商”;大模型译文通常更自然、术语更准确,但处理 较慢;机器翻译引擎速度快、成本低,适合常规稿件。点击“开始翻译”后,系统会根据当前文章内容翻译标题、 副标题、完整标题、SEO 关键词、SEO 描述和正文,并覆盖目标草稿。文章没有独立的 SEO 标题字段;标题类字段会截断为 最多 150 个字符,SEO 描述最多保留 1000 个字符;目标草稿原有的标签不会改变。完成后,请切换到 目标站点,校对译文并发布;“翻译”区域中该行显示的译文标题会随之更新。
如果大模型对某些字段返回了空值,系统会保留这些字段的原文,并在提示中列出字段名(例如 “标题、SEO描述”),请在目标站点补充。机器翻译引擎对非空文本返回空译文时,按“AI服务响应无法 解析”报错,草稿不会被改动,稍后重试即可。
可在 配置 → 全局设置 → AI服务商 的“翻译”区域设置翻译服务商。通过“翻译服务商”下拉列表 选择;如果留空,则使用默认的大模型服务商。可选服务商分为两类:
- 大模型服务商:AI 服务商列表中的任意一家(DeepSeek/Qwen 等 OpenAI 兼容部署);
- 机器翻译引擎:百度翻译、有道翻译或 DeepL。无论当前选择哪一家服务商,这三种引擎的凭证 字段都会显示在下拉列表下方。百度翻译需要“百度翻译 APP ID”和“百度翻译密钥”,有道翻译需要 “有道应用ID”和“有道应用密钥”,DeepL 需要“DeepL认证密钥”;以
:fx结尾的 DeepL 免费版 密钥会自动使用免费版接口。配置完成后,可以在两个“批量新增译文”弹窗中按次选择引擎,无需将 其设为默认翻译服务商。每个密钥输入框旁都有“测试”按钮(需要config:权限),可使用 表单中的当前凭证将“你好”试译为英文,并显示耗时。测试前无需保存;留空的密钥将沿用已保存值。 测试不受全局 AI 开关影响,不写入 AI 调用日志,也不占用额度,只记录一条操作日志。ai: update
机器翻译速度快、成本低,适合批量处理常规文章;大模型通常更适合 Markdown 文章,译文也更自然。 机器翻译按字符计量:AI 调用日志的“Token数”列记录原文与译文的字符数,“服务商”列显示引擎名称, “模型”列显示 mt:baidu、mt:youdao 或 mt:deepl。机器翻译同样受站点每日 token 配额和全局 每日上限约束。
注意:
- 该功能只填充草稿,不会改写已发布内容,也不会自动发布。填充后的草稿会带有 “含AI生成内容”标记,以满足 AIGC 合规要求;
- 每次点击会发起两次调用,分别处理元信息和正文。只有两次调用均成功后才会写入草稿;任意一次 失败,草稿都保持不变。AI 调用日志中会记录两行,功能列显示“预翻译”,用量计入源站点 (即操作者所在站点)的每日额度;
- 翻译通常需要 1~2 分钟,机器翻译一般只需数秒。弹窗中的“取消等待”只会停止前端等待,不会 中止服务端调用和计量;控制台最长等待 10.5 分钟;
- 反向代理需设置足够长的读取超时时间,要求与 AI 写作助手相同。否则,翻译长文时连接可能会在 代理处中断,但草稿仍可能写入。机器翻译引擎单次 HTTP 调用的读取超时时间固定为 60 秒;
- 正文超过 24000 个字符(含标记)时将拒绝翻译,请手动处理超长文章;
- 如果机器翻译引擎不支持所选站点语言,系统会直接提示。三家引擎均支持系统预置的 12 种站点 语言;匹配时先检查完整的小写语言标签,再检查主语言子标签,因此
en-GB、pt-BR也可以使用。 DeepL 会将zh-TW源文按通用中文处理;目标语言为en、pt时,分别默认使用美式英语和 欧洲葡萄牙语。大模型服务商不会检查语言;源站点与目标站点语言相同时,系统也不会阻止调用, 并会正常计费; - 机器翻译可能会破坏 Markdown 文章中的个别标记语法,发布前请仔细校对;大模型处理 Markdown 通常更稳定。翻译 HTML 正文时,系统会分别处理文本节点以及图片的
alt和title属性, 不翻译script、style、code、pre、textarea中的内容;只包含标点或空白的片段会原样保留。
批量新增译文(商业版标准版)
为拥有大量文章的站点新增语言版本时,逐篇创建译文较为耗时。可使用 内容 → 文章管理 → 批量新增译文(需要 article: 权限;当前站点不属于语言组时不显示该按钮; 2026-09-04 之前称为“批量翻译”)。请注意操作方向:应在源语言站点执行,译文草稿会创建在 所选目标站点中,当前站点的文章保持不变。对话框会显示翻译方向(当前站点语言 → 目标站点语言):
- 选择目标站点(支持多选,默认选中同组的所有站点),并按需选择栏目(默认为全站,包含 子栏目)。扫描范围仅包括当前站点中已发布和已归档的文章,不包括草稿、待审和已下线文章。 系统会为每个站点显示一行预览计数:“共 N 篇文章:可新建译文 a 篇,已有译文 b 篇,无同别名 栏目 c 篇”,后两类会被跳过。以下信息仅在数量不为零时追加显示:目标栏目中可直接关联的已有 文章、已创建但尚未翻译的草稿,以及因同别名或同标题命中多篇而“需手工关联”的文章。
- 选择翻译方式。下拉列表依次提供:仅创建草稿(不翻译)、机器翻译引擎和大模型 服务商。“仅创建草稿”适合由人工翻译团队先批量创建草稿,AI 未开启时也可使用;机器翻译 速度快、成本低,适合大批量处理;大模型逐篇处理较慢,但通常能更稳定地处理 Markdown。列表 只显示已完整配置凭证且支持当前语言对的引擎;选择多个目标站点时,只显示所有目标站点共同 可用的引擎。所有大模型服务商都会显示。如果全局“翻译服务商”在列表中,则默认选中该服务商, 否则默认选择“仅创建草稿”。全局 AI 或当前站点的“AI预翻译”开关关闭时,列表中只保留 “仅创建草稿”。
- 确认后,任务将在后台执行。选择多个目标站点时,每个站点对应一个任务,并按提交顺序依次 执行。弹窗会为每个任务显示“已扫描 n / N 篇”,并支持随时停止。点击一次“停止”会作用于所有 未完成任务:正在运行的任务会在处理完当前文章后停止,排队中的任务则直接取消。关闭弹窗不会 影响任务执行;之后可以在 系统 → 生成管理 页面的“任务列表”中查看进度和完成报告,任务 类型为“批量新增译文”。
行为规则:
- 先关联,后新建:如果目标栏目中已有同别名或同标题、且尚未加入翻译组的文章(包括草稿), 系统会将其视为已有译文并直接关联,不再创建草稿。例如,两个语言站点都使用同一演示数据包 初始化时,不会因此产生重复草稿。按标题关联的文章会在完成报告中单独列出,请务必复核。如果 同一别名或标题命中多篇文章,系统既不会关联,也不会新建,请手动处理。同一篇目标文章同时 匹配两篇源文时,只会关联先扫描到的源文。
- 处理规则与逐篇新增译文完全一致:系统只创建草稿并加入翻译组,不会自动发布。通过翻译 填充的草稿带有“含AI生成内容”标记,必须切换到目标站点校对后再发布。操作者所属的组织必须 拥有目标站点的权限。
- 单篇处理失败时会跳过并继续,报告会逐篇说明原因,最多保留 50 条明细;即使任务成功,报告也会 写入任务的错误信息栏。大模型对某篇文章的个别字段返回空值时,该篇仍计入“已翻译”,但报告会 注明“其中部分字段未获得译文 N 篇”并在明细中列出字段名,这些字段保留原文,请到目标站点补充。正文超过 24000 个字符时,系统仍会创建草稿,但不翻译正文,并计入 “已建稿未翻译”,不会报错。每日额度耗尽或 AI 被关闭时,任务会自动中止,已经创建的草稿将 保留。引擎触发限流时,同一篇文章会等待 2 秒后重试一次;使用机器翻译引擎时,每篇文章之间 间隔 0.3 秒,以适配百度翻译免费版的 1 QPS 限制。
- 支持重复执行:对同一范围再次运行时,系统会自动跳过目标站点中已有译文的文章,适合在 额度耗尽并中止后,于第二天继续处理。对于因翻译失败或选择“仅创建草稿”而留下的草稿,只要 从未被人工编辑过(仍为草稿、没有 AI 生成标记,且修改时间等于创建时间),重新运行并选择 服务商后就会自动补译,预览中显示为“已建稿未翻译”。任何经人工保存的草稿都不会被覆盖; 如需重新翻译,请在文章表单的“翻译”区域逐篇执行 AI 预翻译。
- 翻译计量方式与单篇预翻译相同,用量计入源站点的每日额度和 AI 调用日志。任务由单线程执行器 串行处理,最多可排队 32 个;超过上限时提交失败,任务行会停留在“等待”状态。请等待之前的 任务完成后再次提交。
权限与日志速查
| 动作 | 权限键(权限树位置) | 操作日志名称 |
|---|---|---|
| 修改文章翻译链接(“翻译”区域保存) | article:update(文章管理) | 修改文章翻译链接 |
| 新增译文 | article:(文章管理 → 新增译文) | 新增译文 |
| AI 预翻译 | ai:translate(日志 → AI日志 → AI预翻译) | AI预翻译 |
| 文章批量新增译文 / 停止 | article:(文章管理 → 批量新增译文) | 批量新增译文 / 停止批量新增译文 |
| 栏目批量新增译文 | channel:(栏目管理 → 批量新增译文) | 批量新增栏目译文 |
| 翻译服务商、引擎凭证与引擎测试 | config:ai:show / config:(配置 → 全局设置) | 修改全局AI设置 / 全局设置机器翻译引擎测试 |
| 站点“AI预翻译”开关 | siteSettings:(配置 → 站点设置) | 修改站点AI设置 |
以上权限均属于商业版标准版。社区版无法创建第二个站点、也就不会有语言组,因此“新增译文”“批量新增译文” 和“AI 预翻译”按钮都不会显示(它们只在当前站点属于语言组、且存在其他语言站点时出现)。在 日志 → AI日志 中,预翻译和两种 批量翻译的功能列均显示“预翻译”,并按操作者所在的源站点记录。
五、语言切换与 SEO 的具体规则
系统会集中计算当前页面的其他语言版本,exact 表示目标页面是否与当前页面的内容完全对应:
| 当前页面 | 目标地址 | exact |
|---|---|---|
| 首页 | 对应语言站点首页 | 是 |
| 栏目页 | 同别名栏目;找不到则最近的有同别名栏目的上级栏目,再找不到则目标首页 | 找到对应栏目时为是,否则为否 |
| 文章页 | 显式关联的译文;未关联则所在栏目(或其最近的上级)的同别名栏目,再找不到则首页 | 找到对应译文时为是,否则为否 |
| 搜索、标签等其他页 | 目标首页 | 否 |
可见的语言切换器可以展示所有备选项,让用户即使在没有对应译文时,也能进入其他语言站点。 用于 SEO 的 hreflang 则只能输出 exact=true 的备选项,不能将回退到首页或栏目的地址当作 文章译文。
主题中的可见切换器
系统不会强制在页头显示语言切换器。可以在 FreeMarker 主题中加入以下代码:
[@LangSiteList; alternates]
[#if alternates?size gt 1]
<nav class="lang-switch" aria-label="Language">
[#list alternates as alt]
<a href="${alt.url}" hreflang="${alt.lang}"[#if alt.current] aria-current="page"[/#if]>
${alt.site.name}
</a>
[/#list]
</nav>
[/#if]
[/@LangSiteList]LangSiteList 参数:
| 参数 | 默认值 | 说明 |
|---|---|---|
siteId | 当前站点 | 为指定站点计算语言备选项 |
isIncludeSelf | true | 是否包含当前页面本身 |
isExactOnly | false | 是否只保留精确对应的内容;用于 SEO 时必须设为 true |
每个 alt 对象都包含 site、lang、url、fullUrl、exact 和 current。站内导航通常 使用 url,SEO 和跨域集成则使用 fullUrl。
如果希望切换器显示语言名称(如“简体中文”“English”)而不是站点名称,可以读取字典 站点语言,按语言标签查找名称,查不到时回退为语言标签:
[#assign langNames = {}/]
[@DictList type='sys_site_lang' limit='100'; langs]
[#list langs as d][#assign langNames = langNames + {(d.value)!'': d.name}/][/#list]
[/@DictList]
${langNames[alt.lang]!alt.lang}这样在 配置 → 字典管理 → 站点语言 中修改名称后,切换器会同步显示新名称。
<html lang>、hreflang 与 canonical
主题布局至少应包含:
<html lang="${site.langTag}">系统不会自动推断文字方向。站点语言为阿拉伯语等 RTL(从右到左)语言时,该语言站点的主题 布局需自行输出 dir="rtl",并适配相应样式。
同时,还应在 <head> 中输出精确匹配的语言备选项:
[@LangSiteList isExactOnly=true; alternates]
[#if alternates?size gt 1]
[#list alternates as alt]
<link rel="alternate" hreflang="${alt.lang}" href="${alt.fullUrl}">
[/#list]
<link rel="alternate" hreflang="x-default" href="${alternates[0].fullUrl}">
[/#if]
[/@LangSiteList]x-default 使用精确备选列表中的第一项。系统先按站点的 order_ 和 ID 对语言组排序,再选取 第一个在当前页面中存在精确对应内容且状态正常的站点。对于首页,该站点就是组内排序第一的 站点;对于栏目页,如果排序第一的站点中没有同别名栏目,则顺延至下一个站点。系统没有单独的 “默认语言”字段。如需更改 x-default,应调整站点排序,并确保该站点中存在对应栏目,然后重新 生成组内静态页。
此外,还应根据已配置的站点地址输出 canonical,避免未知 Host 或兼容回退产生重复页面:
[#if article??]
[#assign canonicalUrl = article.fullUrl]
[#elseif channel??]
[#assign canonicalUrl = channel.fullUrl]
[#else]
[#assign canonicalUrl = site.fullUrl]
[/#if]
<link rel="canonical" href="${canonicalUrl}">当前仓库中的 themes/(中文默认主题)和 themes/(英文演示主题,随商业版 演示镜像以主题包形式提供)已经内置动态 <html lang>、精确 hreflang 代码块和页头可见的语言 切换器(下拉列表,名称取自字典“站点语言”)。两者组成中英文语言组时,访客可在两个站点的对应页面 之间直接切换。journal 主题包自带英文演示种子(栏目树、约 40 篇英文文章、首页焦点区块、页脚链接 组,以及 Section / Story / Gallery 三个内容模型——清单建站的第 2 个站点不复制模型,种子必须自带), 以 seed: all 安装到英文站点即得到一个有内容的英文演示站。它的演示数据与中文默认主题按对应关系对齐, 而不是照搬:Journal 是杂志站,没有视频、下载、文库栏目;但与中文站对应的栏目使用相同别名 (news、world、photo、product、about-us,栏目名称仍是 News / World / Photos / Gear / About), 23 篇与中文站同题的文章在安装时自动关联为译文。因此在演示站上,这五个栏目和这 23 篇文章可以在两种语言 之间直接切换并输出 hreflang;各自独有的子栏目(中文站“国内”、英文站“Business”“Science”)切换到对方的 上级栏目,英文站独有的“Sport”“Life”切换到中文站首页。themes/1/mobile 和 themes/1/shuili 仅支持动态 <html lang>,未内置 hreflang 代码块。使用自定义主题或上述内置主题时,需要参照前面的代码补充相关功能。
1/journal 的首页、栏目页(第 1 页)和文章页已经输出 canonical。1/default 和 1/shuili 的布局提供了 canonical 参数,但目前没有页面模板实际传入该参数;1/mobile 布局则没有提供此 参数。要输出 canonical,页面模板必须传入参数,或直接使用上述代码输出。
Sitemap
- 栏目 sitemap 会为同别名的精确对应栏目输出
<xhtml:link>。没有可输出的栏目时,系统会将 首页作为占位条目,以保持 sitemap 有效,并附带首页的语言备选项; - 文章 sitemap 只会为已显式关联且可访问的译文输出
<xhtml:link>; - 未关联的文章不会将栏目回退地址写入 sitemap。文章 sitemap 中没有文章时,同样以首页作为 占位条目,但该条目不包含语言备选项;
- 文章 sitemap 每批处理 2000 篇文章。语言关系通过批量查询获取,不会为每篇文章额外查询翻译组。
六、静态页更新
动态页面会立即读取最新的语言关系;静态 HTML 则不会因为“加入语言组”“增加同别名栏目”或 “关联文章译文”等操作而自动更新已有页面。
入口:系统 → 生成管理 → 页面静态化。按变更范围处理:
| 变更 | 至少需要重新生成 |
|---|---|
| 站点加入/离开语言组,修改站点语言、地址或排序 | 组内所有站点的首页、栏目页和文章页 |
| 新增或修改同别名栏目 | 两侧栏目页、会回退到该栏目的下级栏目页,以及会回退到该栏目的相关文章页 |
| 建立、解除或替换文章翻译链接 | 翻译组内所有相关语言站的对应文章页 |
修改主题里的语言切换、hreflang 或 canonical | 使用该主题的全部相关静态页 |
如果无法确定影响范围,请在每个语言站点中执行“全部更新”。生成完成后,应同时检查源语言页面 和目标语言页面,因为 hreflang 要求各语言版本相互引用。
七、公开 API
当前站点
GET /api/site/current
GET /api/site/current?subDir=en返回的站点对象包含 lang、langTag 和 langParentId,可用于客户端初始化。传入 subDir 时, 系统仍会结合当前请求的 Host 解析站点。
当前页面的语言备选
GET /api/site/langs
GET /api/site/langs?subDir=en&channel=news
GET /api/site/langs?subDir=en&articleId=123channel 参数应传入栏目别名,而不是栏目 ID;articleId 必须属于当前解析出的站点。同时传入 两者时,以 articleId 为准。两个接口还分别映射到 /frontend/ 和 /frontend/,这也是 frontend 被保留为子目录的原因之一。示例响应如下:
[
{
"siteId": 1,
"name": "中文站",
"lang": "zh-CN",
"url": "/channel/news",
"fullUrl": "https://www.example.com/channel/news",
"exact": true,
"current": true
},
{
"siteId": 5,
"name": "English",
"lang": "en",
"url": "/en/channel/news",
"fullUrl": "https://www.example.com/en/channel/news",
"exact": true,
"current": false
}
]前端可以展示所有返回项,但生成 hreflang 时必须过滤出 exact=true 的条目,并保留当前页面的 自引用。无子目录的多域名客户端必须透传原始 Host;使用子目录的客户端应显式传入 subDir。 当前的最小 Vue 前后端分离示例(Headless)不会自动实现完整的多语言路由。项目集成时,需要自行维护语言路由 和用于判别请求站点的信息。
八、无人值守安装
全新安装时,可以直接在 ujcms. 中声明语言站点:
ujcms:
install:
auto: true
admin:
username: admin
password: ${UJCMS_ADMIN_PASSWORD}
sites:
- name: 中文站
protocol: https
domain: www.example.com
lang: zh-CN
theme: { source: bundled, seed: all }
- name: English
sub-dir: en
lang: en
lang-of: 中文站
theme: { source: bundled, seed: all }从第二个站点开始,新增任何站点都需要商业版标准版。lang 和 lang-of 必须同时配置;lang-of 通过站点名称引用站点 1 或清单中更早的条目,不能向后引用,也不能逐级关联形成多层语言组。语言变体未填写 协议或域名时,将继承主站的协议或域名。
与控制台中的“新增语言版本”不同,通过清单创建的语言变体不会复制主站栏目,即复制数据为空。 两个站点的栏目别名能否对齐,取决于它们的种子数据:使用同一主题时栏目别名全部一致;使用不同主题时, 只有两个主题中别名相同的栏目相互对应(演示站的 default 与 journal 即如此)。之后新增的栏目仍需通过 “批量新增译文”同步。文章方面,安装清单会把语言组内来源相同的演示文章自动关联为译文——同一主题时是 全部演示文章,不同主题时是两个主题标为同一篇的文章;安装后新写的文章不在此列。继续安装时,同名站点将被视为已经创建,系统会将 清单中声明的语言、语言组、子目录、协议和域名应用到该站点。
完整安装参数和 Docker 环境变量映射见 安装向导与无人值守安装。
九、常见问题
| 现象 | 排查建议 |
|---|---|
/en/... 返回 404 | 确认请求 Host 正确,且与语言站点的域名和子目录匹配;确认多个站点使用同一 en 子目录时已开启多域名;在多域名模式下,确认这些站点均已填写域名(日志中会有 WARN 提示) |
| 站点页面返回 503 | 站点已关闭,系统显示 site_disabled 错误页,而不是 404;关闭的站点也不会出现在语言组备选项中 |
| 语言切换器中只有当前站点 | 确认各站点指向同一个语言组主站,其他语言站点状态正常,并且主题中包含 LangSiteList 代码 |
| 栏目页切换后进入目标站点的上级栏目或首页 | 两侧栏目的别名(slug)不一致,或目标栏目不存在;系统改用最近的有同别名栏目的上级,各级都没有才进入首页 |
| 文章页切换后进入栏目页或首页 | 尚未建立文章翻译链接,或目标文章不是已发布或已归档状态 |
页面没有 hreflang | 页面没有至少两个 exact 条目;主题中未加入精确备选代码块;静态页尚未重新生成 |
fullUrl 中的域名或协议错误 | 目标站点的协议、域名或全局端口配置错误;在多域名模式下,使用子目录的站点也必须填写正确域名 |
| 保存时报语言重复 | 同一语言组已存在相同 lang(包括已关闭的站点);编辑已有变体或改选其他语言 |
| 站点语言下拉列表中只有 3 种语言 | 数据库在 2026-09-02 之前已执行字典变更集;请在字典管理中手动补充其余语言,或重新创建数据库 |
| 新增语言版本后自动填入了子目录 | 这是选择语言后生成的建议值;如果采用子域名方案,请清空后再保存 |
| 删除主站失败 | 先删除语言变体,或把变体解除/迁移后再删除主站 |
| 访问者没有自动进入母语站点 | 系统不做语言自动跳转(见“功能边界与运维约束”一节第 5 条);如有需要在反向代理或前端实现 |
| “可能过期”标签不消失 | 编辑并保存被标记的文章即可清除;确认无需合并另一语言版本的修改时,同样保存一次即可 |
| 错误显示“可能过期” | 两侧同时编辑,或在为同步而保存时又加入新内容,可能触发并发保存导致的误判;该标签仅用于提醒,保存被标记的文章即可清除 |
| 新增译文报“已有成员” | 该翻译组在目标站点已有文章(含草稿);先在“翻译”区域解除该站点链接 |
| 新增译文报“无同别名栏目” | 在对话框中手动选择目标栏目,或先在目标站点创建同别名栏目 |
| AI 预翻译按钮不出现 | 需商业版标准版、站点“AI预翻译”开关开启、拥有 ai:translate 权限,且该行已关联草稿(已发布译文不提供预翻译);全局 AI 开关与服务商配置不影响按钮显示,缺失时点击后报错 |
| AI 预翻译报“AI功能未开启” | 全局设置 → AI服务商 的“是否开启”未打开,或站点“AI预翻译”开关关闭;机器翻译引擎同样受全局开关控制 |
| AI 预翻译报“AI服务商未配置” | 已选择机器翻译引擎,但凭证填写不完整(百度需要 APP ID 和密钥,有道需要应用ID和应用密钥,DeepL 需要认证密钥);或未选择服务商且默认服务商为空。可在“全局设置 → AI服务商”中使用“测试”按钮验证引擎凭证 |
| 刚新增的译文立刻显示“可能过期” | 新增译文之后又保存了源文并且内容有变化(2026-09-05 之前的版本:即使内容没有变化也会如此)。在目标站点校对并保存译文即可清除 |
| AI 预翻译提示“部分字段未获得译文” | 大模型对列出的字段返回了空值,这些字段保留了原文;在目标站点手动补充,或再执行一次 AI 预翻译(会重新覆盖草稿的全部字段) |
| AI 预翻译报“模型把生成预算用在了深度思考上,返回为空” | 大模型是推理模型且开启了深度思考;草稿未被改动。管理员在“全局设置 → AI服务商”编辑该服务商,在“请求附加参数”中填入“关闭深度思考”预设(“测试”按钮可检测并一键填入)后重试 |
| AI 预翻译报“AI服务响应无法解析” | 机器翻译引擎对非空文本返回了空译文,或大模型返回了无法使用的内容;草稿未被改动,可重试 |
| AI 预翻译报“机器翻译引擎不支持该语言” | 所选机器翻译引擎不支持源或目标站点语言;换用其他引擎或大模型服务商(系统预置的 12 种站点语言三家引擎均支持) |
| 译文与源文语言相同 | 语言组内两个站点 lang 相同(见“功能边界与运维约束”一节第 2 条);系统不拦截同语言翻译且照常计费,先改正站点语言 |
| 批量新增译文下拉列表中只有“仅创建草稿” | 全局 AI 未开启、当前站点的“AI预翻译”开关已关闭,或没有完整配置凭证且支持当前语言对的引擎;选择多个目标站点时,如果某个站点的语言对不受支持,该引擎也不会显示 |
| 批量新增译文没有处理某些文章 | 扫描范围仅本站已发布与已归档文章;目标站点无同别名栏目的文章被跳过(先通过栏目的“批量新增译文”功能补齐栏目) |
| 栏目批量新增译文提示“当前无法翻译” | 全局 AI 未开启或没有可用服务商(该操作不受站点“AI预翻译”开关影响);仍可“仅新建栏目”,按提示修复后重新运行即可补译 |
| 栏目批量新增译文预览显示“已翻译或已修改” | 目标值已与当前站点不同,系统不会覆盖;如需重新翻译,请手动编辑目标栏目 |
十、功能边界与运维约束
以下限制由当前实现决定,运维时不应只依赖界面提示来规避:
- 不要将仍有关联变体的语言组主站加入另一个语言组。 后端已限制删除仍有关联变体的主站, 但目前对“将主站改为语言变体”没有同等保护,可能形成不受支持的语言组链。应先逐个迁移现有 语言变体,或解除其关联。
- 修改主站语言前,请手动检查组内是否存在重复语言。 服务端和控制台会检查语言变体是否 重复,但修改主站自身的语言时,尚未检查同组的其他站点,可能产生两个相同的
hreflang。 这是当前版本尚未覆盖的校验情况,并不表示系统支持这种配置。 - 地址唯一性由服务层校验,没有数据库唯一约束。虽然站点管理操作通常不频繁,仍应避免多人同时 创建相同域名/子目录组合。
- 对于无法识别且未带子目录的 Host,系统会显示全局默认站点;全局唯一的子目录还支持跨 Host 兼容回退。在生产环境中,应同时配置 Host 白名单、反向代理限制和 canonical。
- 翻译操作始终由运营人员触发。系统提供 AI 预翻译和批量新增译文(商业版标准版),但只会填充 目标站点的草稿,必须经人工校对后发布。修改源文时,系统不会自动同步栏目或文章正文,也不会 自动发布译文;系统不会根据
Accept-Language请求头或访问者所在地区自动跳转语言站点,也不 会将控制台界面语言与站点内容语言绑定。如果需要自动跳转,应在反向代理或前端脚本中实现,并 排除搜索引擎爬虫,以免影响各语言页面的收录。 - 语言组没有独立的默认语言字段;
x-default由站点排序决定。 - 翻译操作不会判断语言对是否合理。大模型服务商不检查语言;任何服务商都不会拒绝源站点和 目标站点语言相同的调用。第 2 条所述的重复语言会导致系统在同一种语言之间“翻译”,并照常计费。
- 栏目“批量新增译文”只受全局 AI 开关控制,不受站点“AI预翻译”开关影响;文章的“AI 预翻译” 和“批量新增译文”则同时受两个开关控制。
十一、上线验收清单
- [ ] 每个站点的协议、域名、端口和子目录均与公网地址一致;代理正确透传 Host。
- [ ] 同一语言组内各站点的语言标签唯一(包括已关闭站点)且格式正确,所有对应站点状态正常; 升级后的数据库已补齐站点语言字典。
- [ ] 对应栏目别名一致;关键文章已经显式关联并发布。
- [ ] 主题输出动态
<html lang>、精确hreflang、x-default和 canonical。 - [ ] 可见切换器在首页、栏目页、已关联/未关联文章页上的回退符合预期。
- [ ] sitemap 中栏目和已关联文章的备选地址正确,并且相互引用;无栏目站点的首页占位条目也正确。
- [ ] 启用静态页的所有语言站已经按影响范围重新生成。
- [ ] 代理会拒绝未登记的 Host;搜索引擎只能索引预期的 canonical 地址。