文档首页 / HareAdmin 开发手册

多语言

国际化分三层,请勿混用:

  • 界面文案(按钮、提示、菜单)→ 库表 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=模块名

常见问题

  1. JS 词条不生效:检查 ajax/lang 是否带当前 lang,以及 yt_lang 是否有对应小写 key。
  2. 不要为每个页面造「删除成功」之类成功文案,统一 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 保证(地区类插件可在安装/导入时补充)。