多语言与 AI 翻译

YeCha 的多语言分两层:界面文案(语言包)与内容译文(ye_poly_contents)。语言完全靠 URL 前缀识别,不依赖 cookie,便于分享与收录。

本页导航

启用与 URL 规则

选项说明
plugin.poly.enabled启用多语插件后后台出现「多语」模块
site.languages启用语言数组,如 ["zh","en"]
site.default_lang基准语言,站内原始内容按它写
site.name_en / site.subtitle_en英文界面下的站点名与副标题
  • 中文:/、/docs-install.html、/category/guide/
  • 英文:/en/、/en/docs-install.html、/en/category/guide/
  • Router 只在语言已启用且 Poly::on() 为真时剥掉首段并递归解析;未启用时 /ja/… 直接 404。
  • 站内链接一律用 ui_lp() 生成前缀,不要手写;分类/标签链接用 Poly::termUrl()。
已知既有行为:插件独立页(/theme、/plugin、/downloads、/enterprise 等)在 /ja/、/ko/ 等前缀下返回 404,官网目前只开放中文与 /en 两版;内容页(文章/页面)不受此限制。

界面语言包

语言包在 lang/*.php,返回键值数组,模板里用 __('nav.docs') 取值;Lang::short() 返回当前语言码。

新增一个导航项或按钮时:

  1. 在 core/Nav.php 的 defs() 里用语言键做 label;
  2. 同时在 lang/zh_CN.php、lang/en_US.php 补上同名键;
  3. 其它语言包若未覆盖,__ 回落到基准语言,别把中文硬编码进视图。

内容译文

ye_poly_contents 以 group_id(基准内容 id)+ lang 唯一确定一条译文:

字段说明
group_id / lang / status所属内容、语言码、发布状态(只有 publish 前台可见)
title / slug / excerpt / content译文标题、URL 段、摘要、正文
description / keywords译文 SEO 字段
manual_override / ai_generated / ai_revision / stale人工修订保护、AI 生成标记、修订号、待更新标记
source_lang / last_ai_at源语言与最近一次 AI 翻译时间

前台取数:Poly::row($baseId, $lang);无译文或状态非 publish 时回退基准语言正文,页面不会空白。列表页按 Poly::publishedList($lang, $limit) 取已发布译文。

术语多语

分类与标签的名称、别名在 ye_metas:

字段说明
names_i18nJSON,如 {"en":"Guides","ja":"ガイド"}
name_en英文名的简写兼容字段
slug_i18n各语言 URL 别名
count预计算的文章数,各语言共用

模板里用 Poly::termName($row, $lang) 取名称、Poly::termUrl($type, $row) 取链接;别直接输出 $row['name'],否则英文页会漏中文。

后台 AI 翻译

「文章 / 页面」列表的 AI 翻译 按钮把一篇内容翻成各启用语言。1.2.2 / 1.2.3 两个版本专门修过它的稳定性:

机制作用
单请求只翻 1 种语言不再在一个 HTTP 请求里串行翻全部语言,避免多个 FPM 进程各卡在长网络等待上
按 cid 文件并发锁(300s TTL)防止重复点击叠加进程
会话队列 + meta-refresh 自动续链N 种语言拆成 N 个短请求自动接着做,安全阀限制迭代次数
set_time_limit(30) + 接口超时 20s单个请求的硬墙钟,失败快速暴露
覆盖翻译(force)勾选后重译已有语言,但保护 manual_override 的人工修订
语种校验 + 自动重试(2 次)日语须含假名、韩语须含谚文、拉丁语种须含字母且非纯汉字;不通过强化提示词重试,仍失败如实报错、绝不入库
续链容错某一种失败也继续翻下一种,最后统一报告成功/跳过/失败,不因单点失败停整批

系统提示词要求「用流利目标语言 native 书写、不得保留中文」,降低中文源文被原样回显的概率。

繁体与特殊语种

  • core/ZhTw.php 处理简繁转换;tw 内容子集在大术语深翻页走 ye_meta_page_bounds 键序快路径(1.2.4),子集不足 limit 时安全回退旧查询。
  • 阿拉伯语等 RTL 语言需要主题样式配合(dir="rtl");默认主题未内置 RTL 布局,做这类站要单独适配。
  • 语言码必须与 site.languages 一致,否则前缀不会被 Router 识别。

常见问题

现象排查
/en/xxx.html 还是中文译文不存在或 status≠publish;基准语言回退是预期行为,去「多语」补译文
点文章链接跳回中文链接漏了语言前缀;统一用 ui_lp() / Poly::termUrl()
分类名在英文页是中文names_i18n 缺该语言;后台「分类标签」补齐
AI 翻译后仍是中文1.2.3 语种校验会拦下并报错;看后台失败提示,必要时人工修订后勾 manual_override
覆盖翻译把人工改过的译文冲掉正常情况下不会:manual_override=1 的行被跳过;检查该标记是否丢失
/ja/theme 404插件页语言前缀的既有行为,见启用与 URL 规则
某个按钮显示 nav.xxx语言包缺键,补齐 lang/*.php

更多见常见问题与使用手册:多语。