laravel-i18n

介绍 Laravel 本地化：PHP 与 JSON 翻译文件、复数规则、Blade 翻译辅助函数、语言环境检测中间件、日期／数字／货币格式化、第三方包翻译，以及大型应用的翻译组织方式。还包括在 Laravel 13 中通过 Context::add() 安全地将语言环境传递到队列。

Laravel 国际化

Agent 工作流（强制）

任何实现开始之前，必须并行启动 3 个 Agent，每个 Agent 调用一次，并设置 name：

1. fuse-ai-pilot:explore-codebase - 检查现有翻译模式
2. fuse-ai-pilot:research-expert - 通过 Context7 验证 Laravel 国际化最佳实践
3. mcp__context7__query-docs - 查阅 Laravel 本地化文档

实现之后，运行 fuse-ai-pilot:sniper 进行验证。

---

概述

功能	PHP 文件	JSON 文件
键	短键（messages.welcome）	完整文本
嵌套	支持	仅扁平结构
最适用于	结构化翻译	大型应用

---

关键规则

1. 绝不拼接字符串 - 使用 :placeholder 占位符替换
2. 复数规则始终处理零
3. 按功能分组 - auth.login.title、auth.login.button
4. 尽早提取字符串 - 视图中不得硬编码文本
5. 验证语言环境 - 使用枚举或允许列表

---

选择指南

Translation task?
├── Basic string → __('key')
├── With variables → __('key', ['name' => $value])
├── Pluralization → trans_choice('key', $count)
├── In Blade → @lang('key') or {{ __('key') }}
├── Locale detection → Middleware
├── Format date/money → LocalizationService
└── Package strings → trans('package::key')

---

参考指南

概念（原因与架构）

主题	参考资料	适用场景
设置	localization.md	初始配置
复数规则	pluralization.md	基于数量的翻译
Blade	blade-translations.md	视图翻译
中间件	middleware.md	语言环境检测
格式化	formatting.md	日期／数字／货币
包	packages.md	第三方包翻译
最佳实践	best-practices.md	大型应用组织方式

模板（完整代码）

模板	使用场景
SetLocaleMiddleware.php.md	URL／会话语言环境检测
lang-files.md	翻译文件示例
LocaleServiceProvider.php.md	集中式本地化服务
LocaleRoutes.php.md	URL 前缀语言环境路由

---

快速参考

// Basic translation
__('messages.welcome')

// With replacement
__('Hello :name', ['name' => 'John'])

// Pluralization
trans_choice('messages.items', $count)

// Runtime locale
App::setLocale('es');
App::currentLocale();  // 'es'

---

最佳实践

应该

• 使用 :placeholder 表示动态值
• 在复数规则中处理零的情况
• 按功能模块分组键
• 使用 Locale 枚举确保类型安全
• 在中间件中设置 Carbon 语言环境

不应该

• 拼接已翻译的字符串
• 在视图中硬编码文本
• 不经验证就接受任意语言环境
• 创建基于数据库的翻译（使用文件）

---

Laravel 13 说明

本地化 API（__()、trans_choice()、App::setLocale()）在 Laravel 13 中保持不变。具体说明：

• Context::add('locale', $locale) 会将语言环境传递到队列任务中（修复了 L12 中 ShouldQueue 任务丢失语言环境的问题）
• cache.serializable_classes（L13 中默认为 false）：如果缓存 Locale 对象，请将其列入其中
• SetLocale 中间件：与来自 [[laravel-auth]] 的新 PreventRequestForgery 中间件兼容

// app/Jobs/SendNotification.php
public function handle(): void
{
    App::setLocale(Context::get('locale', 'en'));
    Notification::send($this->user, new OrderShipped());
}