laravel-i18n

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Laravel Internationalization

Laravel 国际化

Agent Workflow (MANDATORY)

Agent 工作流（强制要求）

Before ANY implementation, use

TeamCreate

to spawn 3 agents:

fuse-ai-pilot:explore-codebase - Check existing translation patterns
fuse-ai-pilot:research-expert - Verify Laravel i18n best practices via Context7
mcp__context7__query-docs - Check Laravel localization documentation

After implementation, run fuse-ai-pilot:sniper for validation.

在进行任何实现之前，使用

TeamCreate

生成3个Agent：

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

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

Overview

概述

Feature	PHP Files	JSON Files
Keys	Short ( `messages.welcome` )	Full text
Nesting	Supported	Flat only
Best for	Structured translations	Large apps

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

Critical Rules

核心规则

Never concatenate strings - Use
```
:placeholder
```
replacements
Always handle zero in pluralization
Group by feature -
```
auth.login.title
```
,
```
auth.login.button
```
Extract strings early - No hardcoded text in views
Validate locales - Use enum or whitelist

切勿拼接字符串 - 使用
```
:placeholder
```
进行替换
务必处理零值 在复数逻辑中
按功能分组 - 例如
```
auth.login.title
```
、
```
auth.login.button
```
提前提取字符串 - 视图中不要硬编码文本
验证语言区域 - 使用枚举或白名单

Decision Guide

决策指南

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')

翻译任务?
├── 基础字符串 → __('key')
├── 带变量 → __('key', ['name' => $value])
├── 复数处理 → trans_choice('key', $count)
├── 在Blade中 → @lang('key') or {{ __('key') }}
├── 语言区域检测 → 中间件
├── 日期/货币格式化 → LocalizationService
└── 扩展包字符串 → trans('package::key')

Reference Guide

参考指南

Concepts (WHY & Architecture)

概念（设计原因与架构）

Topic	Reference	When to Consult
Setup	localization.md	Initial configuration
Pluralization	pluralization.md	Count-based translations
Blade	blade-translations.md	View translations
Middleware	middleware.md	Locale detection
Formatting	formatting.md	Date/number/currency
Packages	packages.md	Vendor translations
Best Practices	best-practices.md	Large app organization

主题	参考文档	查阅时机
配置	localization.md	初始配置阶段
复数处理	pluralization.md	基于数量的翻译场景
Blade模板	blade-translations.md	视图翻译场景
中间件	middleware.md	语言区域检测场景
格式化	formatting.md	日期/数字/货币格式化场景
扩展包	packages.md	第三方包翻译场景
最佳实践	best-practices.md	大型应用架构组织场景

Templates (Complete Code)

模板（完整代码）

Template	When to Use
SetLocaleMiddleware.php.md	URL/session locale detection
lang-files.md	Translation file examples
LocaleServiceProvider.php.md	Centralized localization service
LocaleRoutes.php.md	URL prefix locale routing

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

Quick Reference

快速参考

php

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

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

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

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

php

// 基础翻译
__('messages.welcome')

// 带变量替换
__('Hello :name', ['name' => 'John'])

// 复数处理
trans_choice('messages.items', $count)

// 运行时语言区域
App::setLocale('fr');
App::currentLocale();  // 'fr'

Best Practices

最佳实践

DO

建议做法

Use
```
:placeholder
```
for dynamic values
Handle zero case in pluralization
Group keys by feature module
Use Locale enum for type safety
Set Carbon locale in middleware

为动态值使用
```
:placeholder
```
在复数逻辑中处理零值场景
按功能模块对键进行分组
使用Locale枚举保证类型安全
在中间件中设置Carbon语言区域

DON'T

禁止做法

Concatenate translated strings
Hardcode text in views
Accept any locale without validation
Create DB-based translations (use files)

拼接翻译后的字符串
在视图中硬编码文本
不验证就接受任意语言区域
创建基于数据库的翻译（请使用文件存储）