webman 中实际生效的翻译函数是 trans()，其依赖 config/translation.php 配置文件，必须包含 locale、fallback_locale 和 path 三项，且不支持 i18n() 或 __()。
trans() 是 Webman 中实际生效的翻译函数，不是 i18n() 或 __() —— 后两者在标准 Webman 项目里不存在，直接调用会报 Call to undefined function 错误。
Webman 的多语言能力基于 symfony/translation 组件，配置和使用方式与 Laravel/Symfony 一脉相承，但路径、文件结构和加载逻辑有自己的一套约定。不按它的规则来，哪怕语言文件放对了位置，trans() 也返回原字符串。
config/translation.php 必须存在且格式正确
Webman 不读取 config/app.php 里的 language 或 languages 配置项，也不认 i18n.php 这类自定义文件。它只认 config/translation.php，且该文件必须返回一个数组，包含三个关键键：
-
locale：默认语言标识（如'zh_CN'），决定未显式指定语言时的 fallback 行为 -
fallback_locale：数组，当当前语言缺失某 key 时，依次尝试这里的语言（如['zh_CN', 'en']） -
path：绝对路径，指向语言文件根目录（不是单个 PHP 文件）
<?php return [
'locale' => 'zh_CN',
'fallback_locale' => ['zh_CN', 'en'],
'path' => base_path() . '/resource/translations',
];
- 如果
path拼写错误（比如少个s写成translation），trans()会静默失败，始终返回原始 key -
base_path()指向项目根目录，不要硬写<strong>DIR</strong>.'/../resource/...'，容易因入口不同出错
语言文件必须放在 resource/translations/{locale}/messages.php
Webman 默认只加载 messages.php，不支持 auth.php、validation.php 这类分组文件（除非你手动注册额外的 MessageCatalogue）。
- 正确路径：
resource/translations/zh_CN/messages.php - 错误路径：
lang/zh.php、resources/lang/zh/messages.php、resource/translations/zh_CN.php - 文件内容必须是纯
return [...]数组，不能有输出、不能有 class、不能用define()
// resource/translations/en/messages.php
return [
'hello' => 'Hello world!',
'welcome_back' => 'Welcome back, :name!',
];
- 键名区分大小写，
trans('Hello')和trans('hello')是两个不同 key - 占位符用
:name格式，调用时传数组：trans('welcome_back', ['name' => 'Alice'])
每个请求必须独立设置语言，不能全局 locale()
locale('en') 是修改单例实例的默认 locale，但它跨请求残留——因为 Webman 是常驻内存模型，一次设置会影响后续所有请求，直到进程重启。
- ❌ 在控制器里直接写
locale('en')，会导致下一个中文用户看到英文内容 - ✅ 正确做法是在中间件中根据请求上下文设置，例如从 URL 参数、Header 或 Cookie 读取：
// app/middleware/Lang.php
<?php namespace app\middleware;
use support\Request;
class Lang
{
public function handle(Request $request, \Closure $next)
{
$lang = $request->get('lang', $request->header('accept-language', 'zh_CN'));
$lang = str_starts_with($lang, 'zh') ? 'zh_CN' : 'en';
locale($lang);
return $next($request);
}
}
- 别忘了在
config/middleware.php中注册这个中间件 - 如果用 Session 存语言偏好，注意 Webman 默认不启用 session，需先装
webman/session插件
trans() 看似简单，但背后依赖路径、文件名、配置键、请求生命周期四个环节严丝合缝。最容易被忽略的是：语言文件目录必须叫 resource/translations，不能是 lang 或 locales；config/translation.php 文件名一个字母都不能错；每个请求的语言设置必须隔离，不能靠“设一次管全场”。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
