Laravel Lang 本地化代码(Locale)对照指南:128 个语言目录与翻译规则的完整映射

原创2026-09-26 15:44:241,749 阅读
文章标签:后端

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 排除清单:列出不应被翻译、应保留原样的字符串

三个要点值得展开:

  1. 排除清单的作用。_excludes.json 中收录的是需要保持原文的专有名词与品牌词。以 locales/zh_CN/_excludes.json 为例,其中包含 "API Token"、"API Tokens"、"CSV (.csv)"、"Email"、"email"、"Excel (.xlsx)"、"ID"、"Nova"。这类词一旦被强行翻译成"接口令牌""电子邮件",反而会破坏界面一致性与可识别性,因此翻译流水线会跳过它们。
  2. 占位符必须保留。翻译不是逐字替换,json-inline.json 中如 "The :attribute must be at least :length characters and contain at least one number." 译为「此项长度至少为 :length 个字符,并且至少包含一个数字」,:attribute、:length 等占位符原样保留,运行时由框架注入真实字段名与数值。
  3. 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 项目,典型流程如下:

  1. 安装:composer require --dev laravel-lang/lang(也可视需要放入 require)。安装后包内包含 locales/ 全套 128 语言文件与发布逻辑。
  2. 添加语言:使用发布器命令 php artisan lang:add zh_CN(或 lang:publish 发布全部语言、lang:update 更新既有翻译),将对应目录发布到应用的 lang/ 目录。仓库自身的同步脚本在 composer.json 的 format 脚本中以 vendor/bin/lang sync 体现,可据此推断发布器提供了同名 CLI 命令 lang,支持 sync 等子命令。
  3. 切换语言:在 config/app.php 中设置 'locale' => 'zh_CN'(取值必须与 locales/ 目录名完全一致),或在运行时通过 app()->setLocale('de_CH') 动态切换。
  4. 校验进度:仓库根目录 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、发布语言包与评估翻译完成度的第一手速查依据。

登录后查看全文
lang