Laravel 的语言文件可以统一管理页面提示、表单错误和操作结果，适合后台系统、对外网站和多语言接口。将文本从模板中分离出来后，后续增加英文、日文等语言时，不需要逐个修改页面中的固定文字。
一、配置默认语言
Laravel 的语言配置位于：
config/app.php常见配置如下：
'locale' => 'zh_CN',
'fallback_locale' => 'en',locale 表示默认语言，fallback_locale 表示找不到对应翻译时使用的备用语言。
如果项目没有 lang 目录，可以执行：
php artisan lang:publish该命令会发布 Laravel 的语言文件目录。不同 Laravel 版本生成的默认文件内容可能有所不同。
二、创建语言文件
在 lang 目录下创建中文和英文目录：
lang/
├── zh_CN/
│ └── messages.php
└── en/
└── messages.php中文语言文件：
<?php
return [
'welcome' => '欢迎使用 Laravel',
'login_success' => '登录成功',
'order_created' => '订单创建成功',
];英文语言文件：
<?php
return [
'welcome' => 'Welcome to Laravel',
'login_success' => 'Login successful',
'order_created' => 'Order created successfully',
];语言文件返回一个 PHP 数组，数组键应保持一致，方便根据当前语言读取相同的翻译内容。
三、在 Blade 模板中调用翻译
在 Blade 模板中使用 __() 函数：
<h1>{{ __('messages.welcome') }}</h1>
<p>{{ __('messages.login_success') }}</p>也可以使用 trans()：
<p>{{ trans('messages.order_created') }}</p>两种写法功能相近。项目中应保持统一，避免同一类页面混用多种风格。
四、在控制器中调用语言文本
控制器中同样可以使用 __()：
namespace App\Http\Controllers;
use Illuminate\Http\RedirectResponse;
class OrderController extends Controller
{
public function store(): RedirectResponse
{
return redirect()
->route('orders.index')
->with('success', __('messages.order_created'));
}
}如果使用 JSON 接口：
return response()->json([
'message' => __('messages.order_created'),
]);接口语言由当前应用语言环境决定。对于公开 API，也可以根据请求头或用户配置设置语言。
五、使用带参数的翻译文本
语言文件可以使用占位符：
<?php
return [
'hello_user' => '你好，:name',
'items_count' => '当前共有 :count 条记录',
];调用时传入参数：
$message = __('messages.hello_user', [
'name' => $user->name,
]);
$countMessage = __('messages.items_count', [
'count' => 12,
]);在 Blade 模板中：
<p>{{ __('messages.hello_user', ['name' => $user->name]) }}</p>占位符名称应保持清晰，避免使用没有业务含义的数字或单字母变量。
六、根据请求切换语言
可以通过路由参数实现简单的语言切换：
use Illuminate\Support\Facades\App;
use Illuminate\Support\Facades\Route;
Route::get('/language/{locale}', function (string $locale) {
abort_unless(
in_array($locale, ['zh_CN', 'en'], true),
404
);
session(['locale' => $locale]);
return back();
});这个路由只保存用户选择的语言，还需要在后续请求中读取 session 并设置应用语言。
七、使用中间件设置语言
创建中间件：
php artisan make:middleware SetLocale编辑 app/Http/Middleware/SetLocale.php：
<?php
namespace App\Http\Middleware;
use Closure;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\App;
use Symfony\Component\HttpFoundation\Response;
class SetLocale
{
public function handle(
Request $request,
Closure $next
): Response {
$locale = session('locale', config('app.locale'));
if (!in_array($locale, ['zh_CN', 'en'], true)) {
$locale = config('app.fallback_locale');
}
App::setLocale($locale);
return $next($request);
}
}中间件会读取用户保存在 session 中的语言。如果语言不在允许范围内，就使用备用语言。
然后将中间件加入 Web 请求中。不同 Laravel 版本的中间件注册方式可能不同，应按照项目当前版本的 bootstrap/app.php 或 HTTP 内核配置进行注册。
Laravel 11、12 常见的 bootstrap/app.php 注册方式如下：
use App\Http\Middleware\SetLocale;
use Illuminate\Foundation\Configuration\Middleware;
->withMiddleware(function (Middleware $middleware): void {
$middleware->web(append: [
SetLocale::class,
]);
})注册后，使用语言切换地址：
/language/en再次访问页面时，页面文本会切换为英文。
八、通过请求头设置 API 语言
对于 API，可以根据 Accept-Language 请求头设置语言。示例中只允许中文和英文：
use Illuminate\Support\Facades\App;
$locale = $request->getPreferredLanguage([
'zh_CN',
'en',
]);
App::setLocale($locale ?: config('app.fallback_locale'));实际项目可以将这段逻辑放在 API 中间件中。
测试请求：
curl -H "Accept-Language: en" \
http://127.0.0.1:8000/api/profile如果请求没有提供语言，或者语言不在允许范围内，系统应使用默认语言或备用语言。
九、处理缺失翻译
如果当前语言文件中没有对应键，Laravel 会按照备用语言配置查找翻译。仍然找不到时，通常会返回传入的翻译键，例如：
messages.unknown_key因此，新增页面文本后，应同时补充各语言文件：
'delete_confirm' => '确定要删除这条记录吗？','delete_confirm' => 'Are you sure you want to delete this record?',不要直接在模板中大量混用固定中文和翻译键，否则后续维护时容易遗漏。
十、清理配置缓存
如果修改了 config/app.php 或其他配置文件，项目使用配置缓存时，需要重新生成缓存：
php artisan config:clear
php artisan config:cache如果页面仍然显示旧内容，还应检查：
- 当前请求是否经过设置语言的中间件。
lang目录名称是否与locale完全一致。- 翻译键是否写错。
- 语言文件是否返回数组。
- session 是否成功保存语言选择。
十一、常见问题
zh_CN 和 zh-CN 可以混用吗？
不建议混用。语言目录名称、config/app.php 中的 locale 和代码中设置的语言值应保持一致。项目确定一种格式后，所有配置都使用相同格式。
语言文件中的键名可以使用中文吗？
技术上可以，但建议使用稳定、清晰的英文键名，例如：
'login_success' => '登录成功',这样更便于团队维护和后续增加语言。
多语言切换后页面没有变化怎么办？
先确认 App::setLocale() 是否执行，再检查语言文件路径、目录名称和翻译键是否一致。如果项目启用了配置缓存，也要清理并重新生成配置缓存。
Laravel 多语言是否需要单独安装扩展？
基础语言文件和语言切换功能不需要额外安装扩展，Laravel 自带相关支持。只有在使用第三方翻译平台或特殊本地化功能时，才需要额外引入扩展。
