Laravel Lang 本地化代码(Locale)对照指南:128 个语言目录与翻译规则的完整映射
Laravel Lang 本地化代码(Locale)对照指南:128 个语言目录与翻译规则的完整映射
本指南以 Laravel Lang 仓库中的本地化规则文档(.aiassistant/rules/locales.md)为骨架,系统梳理仓库全部 128 个 locales/ 语言目录与其对应语言的映射关系,并结合 source/ 源字符串、src/ 插件注册与 docs/status.md 翻译进度等仓库证据,讲清楚「哪个目录只能翻译成哪种语言」「区域/脚本变体如何命名」以及「这些目录在 Laravel 项目中如何被消费」。读完本文,你将掌握 Laravel Lang 本地化目录的完整编目,并能正确选择、配置和扩展多语言语言包。
一、背景:为什么需要一份「本地化代码 ↔ 语言」的严格对照表
laravel-lang/lang 是一个为 Laravel Framework、Jetstream、Fortify、Breeze、Cashier、Nova、Spark 与 UI 提供多语言语言包的仓库(见 composer.json 中的 description)。它的核心资产全部存放在根目录 locales/ 下——每支持一种语言,就有一个以本地化代码(locale code)命名的目录。
本地化代码是计算机与人共同约定的一套语言标识符:zh_CN 表示简体中文、de_CH 表示瑞士德语、pt_BR 表示巴西葡萄牙语。代码中的下划线把「语言」和「地区/文字变体」分开,避免翻译歧义——同样是葡萄牙语,巴西与葡萄牙的用词差异显著,必须拆成两个目录分别维护。
仓库中的规则文档(.aiassistant/rules/locales.md)正是把这条约束写成了机器可读的 128 条硬性规定:locales/<code> 目录的内容永远只允许翻译成 <language> 这一种语言。这份规则的价值在于:
- 对人工译者与 AI 辅助翻译而言,它锁定了每个目录的目标语言,防止把翻译内容错配进错误的语言目录;
- 对自动化流水线(如
composer.json中定义的vendor/bin/lang sync同步脚本)而言,它提供了目录与语言一一对应的权威编目,便于批量校验与生成; - 对应用开发者而言,它是选择
config/app.php中locale取值时的速查表。
二、完整映射表:128 个本地化代码与语言的对应关系
以下四个表格按字母序完整收录规则文档中的全部 128 个条目(保持原文档 af → zu 的排列顺序),代码列即仓库根目录 locales/ 下的实际目录名。
2.1 A–D:从 Afrikaans 到 Dogri
| 目录(locale) | 对应语言 |
|---|---|
af |
Afrikaans(南非荷兰语) |
ak |
Akan(阿肯语) |
am |
Amharic(阿姆哈拉语) |
ar |
Arabic(阿拉伯语) |
as |
Assamese(阿萨姆语) |
az |
Azerbaijani(阿塞拜疆语) |
be |
Belarusian(白俄罗斯语) |
bg |
Bulgarian(保加利亚语) |
bho |
Bhojpuri(博杰普尔语) |
bm |
Bambara(班巴拉语) |
bn |
Bangla(孟加拉语) |
bs |
Bosnian(波斯尼亚语) |
ca |
Catalan(加泰罗尼亚语) |
ceb |
Cebuano(宿务语) |
ckb |
Central Kurdish(中库尔德语) |
cs |
Czech(捷克语) |
cy |
Welsh(威尔士语) |
da |
Danish(丹麦语) |
de_CH |
German (Switzerland)(瑞士德语) |
de |
German(德语) |
doi |
Dogri(多格拉语) |
2.2 E–L:从 Ewe 到 Latvian
| 目录(locale) | 对应语言 |
|---|---|
ee |
Ewe(埃维语) |
el |
Greek(希腊语) |
en_CA |
English (Canada)(加拿大英语) |
en |
English(英语) |
eo |
Esperanto(世界语) |
es |
Spanish(西班牙语) |
et |
Estonian(爱沙尼亚语) |
eu |
Basque(巴斯克语) |
fa |
Persian(波斯语) |
fi |
Finnish(芬兰语) |
fil |
Filipino(菲律宾语) |
fr |
French(法语) |
fy |
Western Frisian(西弗里斯兰语) |
ga |
Irish(爱尔兰语) |
gd |
Scottish Gaelic(苏格兰盖尔语) |
gl |
Galician(加利西亚语) |
gu |
Gujarati(古吉拉特语) |
ha |
Hausa(豪萨语) |
haw |
Hawaiian(夏威夷语) |
he |
Hebrew(希伯来语) |
hi |
Hindi(印地语) |
hr |
Croatian(克罗地亚语) |
ht |
Haitian Creole(海地克里奥尔语) |
hu |
Hungarian(匈牙利语) |
hy |
Armenian(亚美尼亚语) |
id |
Indonesian(印度尼西亚语) |
ig |
Igbo(伊博语) |
is |
Icelandic(冰岛语) |
it |
Italian(意大利语) |
ja |
Japanese(日语) |
ka |
Georgian(格鲁吉亚语) |
kk |
Kazakh(哈萨克语) |
km |
Khmer(高棉语) |
kn |
Kannada(卡纳达语) |
ko |
Korean(韩语) |
ku |
Kurdish(库尔德语) |
ky |
Kyrgyz(吉尔吉斯语) |
lb |
Luxembourgish(卢森堡语) |
lg |
Ganda(干达语) |
ln |
Lingala(林加拉语) |
lo |
Lao(老挝语) |
lt |
Lithuanian(立陶宛语) |
lv |
Latvian(拉脱维亚语) |
2.3 M–Q:从 Maithili 到 Quechua
| 目录(locale) | 对应语言 |
|---|---|
mai |
Maithili(迈蒂利语) |
mg |
Malagasy(马达加斯加语) |
mi |
Māori(毛利语) |
mk |
Macedonian(马其顿语) |
ml |
Malayalam(马拉雅拉姆语) |
mn |
Mongolian(蒙古语) |
mni_Mtei |
Manipuri(曼尼普尔语,Meitei 文字) |
mr |
Marathi(马拉地语) |
ms |
Malay(马来语) |
mt |
Maltese(马耳他语) |
my |
Burmese(缅甸语) |
nb |
Norwegian Bokmål(挪威书面语) |
ne |
Nepali(尼泊尔语) |
nl |
Dutch(荷兰语) |
nn |
Norwegian Nynorsk(挪威新挪威语) |
oc |
Occitan(奥克语) |
om |
Oromo(奥罗莫语) |
or |
Odia(奥里亚语) |
pa |
Punjabi(旁遮普语) |
pl |
Polish(波兰语) |
ps |
Pashto(普什图语) |
pt_BR |
Portuguese (Brazil)(巴西葡萄牙语) |
pt |
Portuguese(葡萄牙语) |
qu |
Quechua(克丘亚语) |
2.4 R–Z:从 Romanian 到 Zulu
| 目录(locale) | 对应语言 |
|---|---|
ro |
Romanian(罗马尼亚语) |
ru |
Russian(俄语) |
rw |
Kinyarwanda(基尼亚卢旺达语) |
sa |
Sanskrit(梵语) |
sc |
Sardinian(撒丁语) |
sd |
Sindhi(信德语) |
si |
Sinhala(僧伽罗语) |
sk |
Slovak(斯洛伐克语) |
sl |
Slovenian(斯洛文尼亚语) |
sn |
Shona(绍纳语) |
so |
Somali(索马里语) |
sq |
Albanian(阿尔巴尼亚语) |
sr_Cyrl |
Serbian(塞尔维亚语,西里尔文字) |
sr_Latn_ME |
Serbian (Montenegro)(黑山塞尔维亚语) |
sr_Latn |
Serbian(塞尔维亚语,拉丁文字) |
su |
Sundanese(巽他语) |
sv |
Swedish(瑞典语) |
sw |
Swahili(斯瓦希里语) |
ta |
Tamil(泰米尔语) |
te |
Telugu(泰卢固语) |
tg |
Tajik(塔吉克语) |
th |
Thai(泰语) |
ti |
Tigrinya(提格里尼亚语) |
tk |
Turkmen(土库曼语) |
tl |
Tagalog(他加禄语) |
tr |
Turkish(土耳其语) |
tt |
Tatar(鞑靼语) |
ug |
Uyghur(维吾尔语) |
uk |
Ukrainian(乌克兰语) |
ur |
Urdu(乌尔都语) |
uz_Cyrl |
Uzbek (Cyrillic)(乌兹别克语,西里尔文字) |
uz_Latn |
Uzbek (Latin)(乌兹别克语,拉丁文字) |
vi |
Vietnamese(越南语) |
xh |
Xhosa(科萨语) |
yi |
Yiddish(意第绪语) |
yo |
Yoruba(约鲁巴语) |
zh_CN |
Chinese (China)(简体中文) |
zh_HK |
Chinese (Hong Kong Sar China)(繁体中文,中国香港) |
zh_TW |
Chinese (Taiwan)(繁体中文,中国台湾) |
zu |
Zulu(祖鲁语) |
三、细说变体:区域、文字与方言的编码规律
通读上表可以发现,128 个目录并非简单的一语言一目录,其中有约 20 个目录属于「同一语言、不同区域/文字」的细分变体。理解这些变体的命名规律,是正确选择 locale 的关键:
- 区域变体(语言_地区):
de_CH(瑞士德语)与de(标准德语)分开维护;en_CA(加拿大英语)与en分开;pt_BR(巴西葡语)与pt(葡萄牙葡语)分开;zh_CN、zh_HK、zh_TW分别对应中国大陆简体、香港繁体与台湾繁体。这类拆分的原因很实际:地区间的用词、拼写与习惯差异巨大,合并翻译会导致界面语言"水土不服"。 - 文字变体(语言_文字):塞尔维亚语同时支持
sr_Cyrl(西里尔文字)与sr_Latn(拉丁文字)两套目录;乌兹别克语同样拆为uz_Cyrl与uz_Latn;曼尼普尔语mni_Mtei明确限定为 Meitei(Mtei)文字。文字后缀保证了同一语言在不同书写系统下都能有准确的翻译。 - 方言/区域叠加变体:
sr_Latn_ME(黑山,拉丁文字)在语言、文字之上再叠加了地区维度,属于最细粒度的命名。 - 同一语言的双目录:挪威语
nb(Bokmål 书面语)与nn(Nynorsk 新挪威语)虽然都以no为语言根,但属于两种不同的书面标准,故拆成两个独立目录。
应用侧用法很简单:在 Laravel 项目中把 config/app.php 的 'locale' 设置为上表中的任意目录名(例如 'zh_CN'),框架即会从 lang/zh_CN/ 目录加载对应翻译。
四、目录内部结构:五种语言文件的职责分工
以 locales/zh_CN/ 为例,每个语言目录内通常包含 5 个文件,共同承载不同类型组件的翻译内容:
| 文件 | 职责 |
|---|---|
json.json |
面向 JSON 语言文件(如 Nova、Jetstream、Fortify 等组件的键值字符串)的完整翻译表,zh_CN 下共 876 行 |
json-inline.json |
仅含内联验证规则字符串(含 :attribute、:length 等占位符),专用于密码/字段规则类提示,见 locales/zh_CN/json-inline.json |
php.json |
对应 Laravel 传统 PHP 语言文件内容的 JSON 化翻译 |
php-inline.json |
内联验证规则在 PHP 语言文件体系中的对应翻译 |
_excludes.json |
排除清单:列出不应被翻译、应保留原样的字符串 |
三个要点值得展开:
- 排除清单的作用。
_excludes.json中收录的是需要保持原文的专有名词与品牌词。以 locales/zh_CN/_excludes.json 为例,其中包含"API Token"、"API Tokens"、"CSV (.csv)"、"Email"、"email"、"Excel (.xlsx)"、"ID"、"Nova"。这类词一旦被强行翻译成"接口令牌""电子邮件",反而会破坏界面一致性与可识别性,因此翻译流水线会跳过它们。 - 占位符必须保留。翻译不是逐字替换,
json-inline.json中如"The :attribute must be at least :length characters and contain at least one number."译为「此项长度至少为 :length 个字符,并且至少包含一个数字」,:attribute、:length等占位符原样保留,运行时由框架注入真实字段名与数值。 - JSON 键的完整性。
json.json的键必须是源语言字符串的精确副本(例如"(and :count more errors)"),值才是本地化文本;键一旦改动,Laravel 的__()辅助函数将无法命中翻译。
五、翻译从哪来:source 目录与插件映射的底层机制
locales/ 中的 128 套翻译并非手工零散堆砌,而是由仓库 source/ 目录下的源字符串与 src/Plugins/ 中的插件映射驱动生成的。
source/ 按组件组织,每个组件目录存放该组件在特定版本下的原始英文字符串,包括 breeze、cashier、fortify、framework(含 master/、11.x/、12.x/、13.x/ 与 extended.json)、jetstream、nova、passkeys、spark、ui。翻译流水线以这些英文源为基准,按规则文档锁定的语言逐一产出 128 套本地化文件。
组件与版本之间的对应关系集中在 src/Plugin.php 的 $plugins 数组中,它注册了面向各组件/版本的插件:
- Breeze
Master、V2; - Cashier Stripe
Master、V15; - Fortify
Master、V1; - Jetstream
Master、V5; - Laravel
Master、V11、V12、V13; - Nova
V4、V5、LogViewer、DuskSuite; - Passkeys
Main; - Spark
Paddle、Stripe; - UI
Master、V4。
每个插件内部定义「源文件 → 目标 {locale} 文件」的映射。以 src/Plugins/Laravel/Master.php 的 files() 方法为例:
framework/master/framework.json与framework/extended.json→{locale}.json;framework/master/auth.php、pagination.php、passwords.php、validation.php→{locale}/auth.php等。
{locale} 正是上表 128 个目录名,Plugin.php 汇总全部映射后,由 LaravelLang\Publisher 插件系统在发布阶段把源字符串与本地化翻译装配到目标项目。整个包通过 src/ServiceProvider.php 在 Laravel 启动时注册(class_exists(Provider::class) 时才挂载 Plugin),并以 laravel-lang/publisher 为运行时依赖(见 composer.json 的 require 段),PHP 版本要求 ^8.2。
六、在 Laravel 项目中落地使用
将这套语言包接入自己的 Laravel 项目,典型流程如下:
- 安装:
composer require --dev laravel-lang/lang(也可视需要放入require)。安装后包内包含locales/全套 128 语言文件与发布逻辑。 - 添加语言:使用发布器命令
php artisan lang:add zh_CN(或lang:publish发布全部语言、lang:update更新既有翻译),将对应目录发布到应用的lang/目录。仓库自身的同步脚本在 composer.json 的format脚本中以vendor/bin/lang sync体现,可据此推断发布器提供了同名 CLI 命令lang,支持sync等子命令。 - 切换语言:在
config/app.php中设置'locale' => 'zh_CN'(取值必须与locales/目录名完全一致),或在运行时通过app()->setLocale('de_CH')动态切换。 - 校验进度:仓库根目录 docs/status.md 汇总了全部语言的整体完成度,当前仓库快照显示翻译完成 97.82%(147.1K / 150.4K 条字符串);每个语言还有独立的
docs/statuses/<code>.md页面(如 docs/statuses/zh_CN.md)可查看单语言明细。
七、总结
Laravel Lang 的多语言能力建立在严格的目录编目之上:128 个 locales/ 目录、每个目录锁定唯一的目标语言,区域与文字变体(de_CH、pt_BR、sr_Cyrl、uz_Latn、zh_HK 等)通过下划线后缀精确区分;目录内部以 json.json、json-inline.json、php.json、php-inline.json 与 _excludes.json 分工承载不同组件的翻译,并由 source/ 源字符串与 src/Plugins/ 版本映射驱动生成。无论是人工翻译、AI 辅助翻译还是自动化流水线,这张「目录 ↔ 语言」对照表都是保证翻译不串语言、不错配的基准;对应用开发者而言,它则是配置 locale、发布语言包与评估翻译完成度的第一手速查依据。