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() 返回当前语言码。
新增一个导航项或按钮时:
- 在
core/Nav.php的defs()里用语言键做label; - 同时在
lang/zh_CN.php、lang/en_US.php补上同名键; - 其它语言包若未覆盖,
__回落到基准语言,别把中文硬编码进视图。
内容译文
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_i18n | JSON,如 {"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 |