本地化 - Knowledge of Laravel

什么是本地化

Laravel 的本地化功能提供了一种便捷方式来获取多种语言的翻译字符串，用于在应用中支持多语言。翻译字符串有两种管理方式：

方式	特点
PHP 文件	例如 `lang/ja/messages.php`，采用键值数组。适合按功能整理（如校验错误消息）
JSON 文件	例如 `lang/ja.json`，直接用翻译字符串作为键。适合翻译量大的应用

默认 Laravel 应用未包含 lang 目录。要自定义，请通过 lang:publish Artisan 命令发布。

php artisan lang:publish

Locale 配置

默认 Locale

应用默认语言在 config/app.php 的 locale 中配置，通常通过 .env 中的 APP_LOCALE 环境变量控制。

// config/app.php
'locale' => env('APP_LOCALE', 'en'),
'fallback_locale' => env('APP_FALLBACK_LOCALE', 'en'),

# .env
APP_LOCALE=ja
APP_FALLBACK_LOCALE=en

fallback_locale 是指定语言无对应翻译时所使用的备用语言。

运行时修改 Locale

使用 App 门面的 setLocale() 方法可以按请求修改 locale。

use Illuminate\Support\Facades\App;

Route::get('/greeting/{locale}', function (string $locale) {
    if (! in_array($locale, ['en', 'ja', 'fr'])) {
        abort(400);
    }

    App::setLocale($locale);

    // ...
});

检查当前 Locale

use Illuminate\Support\Facades\App;

$locale = App::currentLocale();

if (App::isLocale('ja')) {
    // 日语时的处理
}

创建语言文件

PHP 文件形式

在 lang/{语言代码}/ 目录下创建 PHP 文件，返回键值数组。

/lang
    /en
        messages.php
    /ja
        messages.php

<?php

// lang/ja/messages.php

return [
    'welcome' => '欢迎使用本应用！',
    'goodbye' => '再见！',
];

存在地区差异的语言请按 ISO 15897 命名目录。例如英式英语应写为 en_GB 而不是 en-gb。

JSON 形式

翻译字符串较多时推荐使用 JSON 形式。在 lang/ 目录下创建以语言代码命名的 JSON 文件。

/lang
    en.json
    ja.json

将原始英文文本作为键。

{
    "Welcome to our application!": "欢迎使用本应用！",
    "I love programming.": "我热爱编程。",
    "Logout": "登出",
    "Dashboard": "仪表盘"
}

JSON 形式下英文原文本身就是键，因此英文默认展示可自动生效。没有翻译文件的语言会直接返回键（英文原文）。

PHP 与 JSON 的选择

适合 PHP 文件的场景

想按功能整理，例如校验错误信息
覆盖 Laravel 内置翻译（如 validation.php、auth.php）
需要分层管理键

// lang/ja/validation.php
return [
    'required' => ':attribute 是必填项。',
    'email' => ':attribute 必须是有效的邮箱地址。',
];

适合 JSON 的场景

UI 文案多，不想再费心命名键
模板里直接写英文，其他语言通过翻译文件覆盖
后续增加国际化需求

{{-- 在 Blade 模板里直接写英文 --}}
{{ __('Welcome to our application!') }}

获取翻译字符串

`__()` 辅助函数

最常用方式。PHP 文件形式下用 “文件名.键” 语法。

// PHP 文件形式：lang/ja/messages.php 中的 'welcome'
echo __('messages.welcome');
// => 欢迎使用本应用！

// JSON 形式：将翻译原文作为键
echo __('I love programming.');
// => 我热爱编程。

若不存在对应翻译，则原样返回键。

echo __('messages.not_exists');
// => messages.not_exists（键原样返回）

在 Blade 模板中使用

Blade 中使用 {{ __() }}：

{{-- PHP 文件形式 --}}
<h1>{{ __('messages.welcome') }}</h1>

{{-- JSON 形式 --}}
<button>{{ __('Logout') }}</button>

{{-- @lang 指令（已不推荐，仅保留向后兼容） --}}
@lang('messages.welcome')

@lang 指令已不推荐。目前建议使用 {{ __() }}。

占位符

翻译字符串中可以嵌入形如 :name 的占位符。

// lang/ja/messages.php
return [
    'welcome' => '欢迎你，:name！',
    'greet'   => '你好，:Name！',  // 首字母大写
    'shout'   => 'HEY :NAME!',      // 全部大写
];

向 __() 的第二个参数传入替换值数组：

echo __('messages.welcome', ['name' => '田中']);
// => 欢迎你，田中！

echo __('messages.greet', ['name' => 'taro']);
// => 你好，Taro！（Name 首字母大写）

echo __('messages.shout', ['name' => 'taro']);
// => HEY TARO!（NAME 全大写）

Blade 中同样可用：

<p>{{ __('messages.welcome', ['name' => $user->name]) }}</p>

复数

不同语言的复数规则不同。Laravel 使用 | 分隔单数与复数。

基本复数

// lang/ja/messages.php
return [
    'apples' => '有 1 个苹果|有多个苹果',
];

JSON 形式同理：

{
    "There is one apple|There are many apples": "有 1 个苹果|有多个苹果"
}

用 trans_choice() 传入数量：

echo trans_choice('messages.apples', 1);
// => 有 1 个苹果

echo trans_choice('messages.apples', 5);
// => 有多个苹果

指定范围的复数

也可指定更精确的范围：

'apples' => '{0} 没有苹果|[1,19] 有若干苹果|[20,*] 有很多苹果',

echo trans_choice('messages.apples', 0);
// => 没有苹果

echo trans_choice('messages.apples', 10);
// => 有若干苹果

echo trans_choice('messages.apples', 50);
// => 有很多苹果

复数中的占位符

:count 会展示数量。第 3 参数可传入额外替换值。

// lang/ja/messages.php
return [
    'minutes_ago' => '{1} :value 分钟前|[2,*] :value 分钟前',
    'items'       => '共 :count 项',
];

echo trans_choice('messages.minutes_ago', 5, ['value' => 5]);
// => 5 分钟前

echo trans_choice('messages.items', 3);
// => 共 3 项

覆盖包的语言文件

若第三方包自带语言文件，可以在 lang/vendor/{包名}/{语言}/ 下放置同名文件进行覆盖。例如自定义 skyrim/hearthfire 包的英文消息：

lang/
└── vendor/
    └── hearthfire/
        └── en/
            └── messages.php

// lang/vendor/hearthfire/en/messages.php
return [
    'welcome' => '自定义消息',
    // 只定义需要覆盖的键，其他键会读原文件
];

实践示例：中英切换中间件

一个根据 URL 路径、Session 或用户设置自动切换 locale 的中间件示例：

创建中间件

php artisan make:middleware SetLocale

实现中间件

<?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
        $supportedLocales = ['ja', 'en'];

        // Session 中已存则使用它
        $locale = $request->session()->get('locale');

        // 若无则参考浏览器的 Accept-Language
        if (! $locale) {
            $browserLocale = substr($request->getPreferredLanguage($supportedLocales) ?? 'ja', 0, 2);
            $locale = in_array($browserLocale, $supportedLocales) ? $browserLocale : 'ja';
        }

        App::setLocale($locale);

        return $next($request);
    }
}

注册中间件

在 bootstrap/app.php 中注册：

use App\Http\Middleware\SetLocale;

->withMiddleware(function (Middleware $middleware) {
    $middleware->append(SetLocale::class);
})

添加切换路由

// routes/web.php
Route::post('/locale/{locale}', function (string $locale) {
    if (! in_array($locale, ['ja', 'en'])) {
        abort(400);
    }

    session(['locale' => $locale]);

    return back();
})->name('locale.switch');

在 Blade 模板中添加切换按钮

<div>
    <form method="POST" action="{{ route('locale.switch', 'ja') }}">
        @csrf
        <button type="submit">日本語</button>
    </form>

    <form method="POST" action="{{ route('locale.switch', 'en') }}">
        @csrf
        <button type="submit">English</button>
    </form>
</div>

翻译文件结构示例

lang/
├── ja.json          # JSON（UI 文案）
├── en.json
├── ja/
│   └── validation.php   # PHP（校验相关）
└── en/
    └── validation.php

// lang/ja.json
{
    "Dashboard": "仪表盘",
    "Login": "登录",
    "Logout": "登出",
    "Welcome, :name!": "欢迎你，:name！",
    "Save": "保存",
    "Cancel": "取消",
    "Are you sure?": "确定吗？"
}

{{-- resources/views/layouts/app.blade.php --}}
<nav>
    <a href="{{ route('dashboard') }}">{{ __('Dashboard') }}</a>
    <span>{{ __('Welcome, :name!', ['name' => auth()->user()->name]) }}</span>

    <form method="POST" action="{{ route('logout') }}">
        @csrf
        <button type="submit">{{ __('Logout') }}</button>
    </form>
</nav>

小结

翻译字符串的定义方式

方式	文件路径	键示例	获取方式
PHP 文件	`lang/ja/messages.php`	`'welcome' => '...'`	`__('messages.welcome')`
JSON	`lang/ja.json`	`"Welcome": "..."`	`__('Welcome')`

常用函数与门面

函数 / 方法	用途
`__('key')`	获取翻译字符串
`trans('key')`	与 `__()` 等价
`trans_choice('key', $count)`	获取复数翻译
`App::setLocale('ja')`	按请求切换 locale
`App::currentLocale()`	获取当前 locale
`App::isLocale('ja')`	判断当前 locale

Blade 用法

{{-- 基础 --}}
{{ __('messages.welcome') }}

{{-- 含占位符 --}}
{{ __('messages.welcome', ['name' => $user->name]) }}

{{-- 复数 --}}
{{ trans_choice('messages.apples', $count) }}

​什么是本地化

​Locale 配置

​默认 Locale

​运行时修改 Locale

​检查当前 Locale

​创建语言文件

​PHP 文件形式

​JSON 形式

​PHP 与 JSON 的选择

​获取翻译字符串

​__() 辅助函数

​在 Blade 模板中使用

​占位符

​复数

​基本复数

​指定范围的复数

​复数中的占位符

​覆盖包的语言文件

​实践示例：中英切换中间件

​翻译文件结构示例

​小结

什么是本地化

Locale 配置

默认 Locale

运行时修改 Locale

检查当前 Locale

创建语言文件

PHP 文件形式

JSON 形式

PHP 与 JSON 的选择

获取翻译字符串

`__()` 辅助函数

在 Blade 模板中使用

占位符

复数

基本复数

指定范围的复数

复数中的占位符

覆盖包的语言文件

实践示例：中英切换中间件

翻译文件结构示例

小结