多语言
国际化分三层,请勿混用:
- 界面文案(按钮、提示、菜单)→ 库表
yt_lang,调用lang() - 业务内容(文章标题、分类名)→
ContentLang(yt_content_lang) - 模块配置值(站名、SEO 等访客文案)→ 插件
config.php的localize+Settings
PHP / 模板 / JS 统一写 lang('…') / {:lang('…')}。__() 与 Lang::get 同源,同一小段代码不要混用多种风格。
调用方式
lang('Operate success');
lang('My name is %s', ['HareAdmin']);
lang('Are you sure?');
{:lang('Edit')}
{:lang('Are you sure?')}
lang('Are you sure?');
Fast.api.confirm(lang('Are you sure?'), function (index) { /* … */ });
词条不存在时一般回退为 key 本身。库表 yt_lang.key 存小写(JS 查找会 lower-case)。
反馈文案复用(强制)
| 意图 | Key | 中文 |
|---|---|---|
| 确认 | Are you sure? | 确定吗? |
| 成功 | Operate success | 操作成功 |
| 失败 | Operation failed | 操作失败 |
| 不允许 | Cannot operate | 不能操作 |
| 参数错误 | Invalid parameters | 参数不正确 |
| 对话框标题 | Warning | 警告 |
| 按钮 | OK / Cancel | 确定 / 取消 |
CRUD 菜单节点复用短 key:Edit / Add / Delete / Multi。后台 AJAX 优先 Fast.api.ajax(自带 toast);成功回调里不要再 Toastr.success。
词条从哪里来
- 运行时真相:后台「翻译管理」→
yt_lang - 插件安装源:
addons/{name}/lang/zh.php、en.php… 安装/升级时合并进库
语言由 LangService 解析(路径前缀 / 域名 / 参数 / Cookie)。路径语言模式下,JS 语言包请求需带 ?lang=(并优先 Config.lang_path_prefix)。
RTL(书写方向)
html[dir] 跟随当前 UI 语言。例如 UI 为 ar/he/fa/ur → dir=rtl 并加载 RTL CSS;地区是 ar-SA 但 UI 仍是 en/zh 时保持 LTR。样式优先逻辑属性(margin-inline-*、ms-*/me-*)。
业务内容多语言
ContentLang::get('doc_article', $id, 'title', $lang, $fallback);
ContentLang::setMany('doc_article', $id, 'title', ['zh' => '…', 'en' => '…']);
模块设置与 localize
插件配置里访客可见文案按语言存;开关、路由、密钥全局一份。Web / App / 小程序读同一套解析结果。
return [
[
'name' => 'site_name',
'type' => 'string', // 仅 string|text|editor 可 localize
'title' => 'Site name',
'localize' => true,
'public' => true,
'value' => 'Documents',
],
[
'name' => 'rewrite',
'type' => 'array',
'localize' => false,
'public' => false,
'value' => [/* … */],
],
];
- 默认
localize=false;禁止给 radio / array / 密钥 / ID / rewrite 开 localize - PHP:
settings('doc')->all()/settings_get('doc', 'site_name') - API:
GET /api/settings/module?module=doc&lang=zh&client=app(只返回public!=false) - 译文存
yt_content_lang:table_name=addon_config,record_id=模块名
常见问题
- JS 词条不生效:检查
ajax/lang是否带当前lang,以及yt_lang是否有对应小写 key。 - 不要为每个页面造「删除成功」之类成功文案,统一
Operate success。
地区包(Region Packs)
核心统一用表 yt_region(模型 WorldRegion)。新功能不要再写 yt_area*。
- Region Pack(设置 / 地区):国家级数据包 — ISO、电话区号、货币、地址格式标记。多数场景只需「国家 + 州/省」。
- 更深地址树(市 / 区 / …):需要时从应用市场安装对应地区插件。字段、导入步骤、pack 编码等写在该插件商店页,不写入本通用手册。
接口 /api/ajax/area_tree、cities、get_city_by_lat 读 yt_region,没有数据时可回退旧表 yt_area。
扩展字段(lng/lat/code/iso2/pack)由核心 RegionSchema 保证(地区类插件可在安装/导入时补充)。