Laravel 13 多语言与国际化详解

摘要

Laravel 提供了强大的多语言和国际化支持。本文将深入讲解 Laravel 13 的多语言功能，包括：

  • 语言文件配置
  • 翻译字符串
  • 复数形式处理
  • 日期与数字格式化
  • 实战案例与最佳实践

本文适合希望构建多语言应用的 Laravel 开发者。

1. 配置

1.1 语言配置

1
2
3
4
// config/app.php
'locale' => 'en',
'fallback_locale' => 'en',
'available_locales' => ['en', 'zh', 'ja'],

1.2 语言文件

1
2
3
4
5
6
7
8
9
10
lang/
├── en/
│   ├── messages.php
│   └── validation.php
├── zh/
│   ├── messages.php
│   └── validation.php
└── ja/
    ├── messages.php
    └── validation.php

2. 翻译字符串

2.1 使用 __ 辅助函数

1
2
3
4
echo __('messages.welcome');

// 带参数
echo __('messages.welcome', ['name' => 'John']);

2.2 使用 @lang 指令

1
2
3
@lang('messages.welcome')

@lang('messages.welcome', ['name' => 'John'])

2.3 语言文件格式

1
2
3
4
5
// lang/en/messages.php
return [
    'welcome' => 'Welcome, :name!',
    'goodbye' => 'Goodbye!',
];

3. JSON 翻译文件

3.1 创建 JSON 文件

1
2
3
4
5
// lang/zh.json
{
    "Welcome": "欢迎",
    "Hello, :name!": "你好, :name!"
}

3.2 使用 JSON 翻译

1
2
echo __('Welcome');
echo __('Hello, :name!', ['name' => 'John']);

4. 复数形式

4.1 复数定义

1
2
// lang/en/messages.php
'apples' => '{0} There are none|{1} There is one|[2,*] There are many',

4.2 使用复数

1
2
3
echo trans_choice('messages.apples', 0); // There are none
echo trans_choice('messages.apples', 1); // There is one
echo trans_choice('messages.apples', 5); // There are many

4.3 带参数的复数

1
2
3
'apples' => '{0} :count apples|{1} :count apple|[2,*] :count apples',

echo trans_choice('messages.apples', $count, ['count' => $count]);

5. 切换语言

5.1 运行时切换

1
app()->setLocale('zh');

5.2 中间件切换

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
<?php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Support\Facades\App;

class SetLocale
{
    public function handle($request, Closure $next)
    {
        if ($request->user()) {
            App::setLocale($request->user()->locale);
        } elseif (session()->has('locale')) {
            App::setLocale(session('locale'));
        }
        
        return $next($request);
    }
}

5.3 路由切换

1
2
3
4
5
6
7
Route::get('/locale/{locale}', function ($locale) {
    if (in_array($locale, config('app.available_locales'))) {
        session()->put('locale', $locale);
    }
    
    return redirect()->back();
});

6. 日期格式化

6.1 Carbon 本地化

1
2
3
4
5
6
use Carbon\Carbon;

Carbon::setLocale('zh');

$date = Carbon::now()->translatedFormat('l, F j, Y');
// 星期一, 三月 20, 2026

6.2 相对时间

1
2
3
4
Carbon::setLocale('zh');

echo Carbon::now()->diffForHumans(); // 刚刚
echo Carbon::now()->addHour()->diffForHumans(); // 1 小时后

7. 数字格式化

7.1 货币格式

1
2
3
4
use Illuminate\Support\Number;

Number::currency(1000, 'USD'); // $1,000.00
Number::currency(1000, 'CNY'); // ¥1,000.00

7.2 数字格式

1
2
Number::format(1000.123); // 1,000.123
Number::format(1000.123, precision: 2); // 1,000.12

8. 实战案例

8.1 多语言模型

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class Post extends Model
{
    public function translations()
    {
        return $this->hasMany(PostTranslation::class);
    }
    
    public function translation($locale = null)
    {
        return $this->translations()
            ->where('locale', $locale ?? app()->getLocale())
            ->first();
    }
}

8.2 语言切换组件

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
<?php

namespace App\Http\Livewire;

use Livewire\Component;
use Illuminate\Support\Facades\App;

class LanguageSwitcher extends Component
{
    public string $currentLocale;
    
    public function mount()
    {
        $this->currentLocale = App::getLocale();
    }
    
    public function switchLocale($locale)
    {
        session()->put('locale', $locale);
        App::setLocale($locale);
        $this->currentLocale = $locale;
        
        $this->redirect(request()->header('Referer'));
    }
    
    public function render()
    {
        return view('livewire.language-switcher', [
            'locales' => config('app.available_locales'),
        ]);
    }
}

9. 最佳实践

9.1 使用翻译键

1
2
3
4
5
// 推荐：使用翻译键
__('messages.welcome')

// 不推荐：硬编码
echo 'Welcome';

9.2 组织语言文件

1
2
3
4
5
6
lang/
├── en/
│   ├── auth.php      // 认证相关
│   ├── messages.php  // 通用消息
│   ├── validation.php // 验证消息
│   └── pagination.php // 分页

10. 总结

Laravel 的多语言支持提供了强大的国际化能力：

  1. 翻译文件：灵活的翻译管理
  2. 复数处理：智能的复数形式
  3. 日期格式化：本地化的日期显示
  4. 数字格式化：货币和数字格式

参考资料