Laravel 泰语本地化翻译缺口分析:基于 laravel-lang/lang 的 th 语言包状态解读与补全指南
Laravel 泰语本地化翻译缺口分析:基于 laravel-lang/lang 的 th 语言包状态解读与补全指南
本篇技术指南以 laravel-lang/lang 仓库中 docs/statuses/th.md 状态报告为骨架,深入剖析泰语(th)语言包的翻译完成度、三类缺失条目(json / php-inline / php)的具体内容及其来源组件,并结合仓库中的翻译文件、英文源文件与插件注册源码,给出可落地的补全方案。读完本文,你将掌握如何读懂语言包状态报告、定位缺失翻译的源头,以及如何在 Laravel 项目中正确接入与验证泰语翻译。
一、状态报告是什么:lang 仓库的“翻译体检单”
docs/statuses/th.md 是 laravel-lang/lang 仓库自动生成的语言包完成度报告之一。该仓库为 Laravel 生态(Framework、Jetstream、Fortify、Breeze、Cashier、Nova、Spark、UI 等)维护了 126 种语言的全量翻译,每个语言目录(如 locales/th/)下存放着实际可用的翻译文件,而 docs/statuses/ 下的每个 .md 文件则记录该语言还有多少条目未完成翻译。
从报告头部可以看到关键指标:
##### All missed: 19
即泰语语言包当前共有 19 条翻译缺失,分布在三种文件类型中:
| 文件类型 | 缺失数量 | 对应实际文件 |
|---|---|---|
| json | 13 | locales/th/json.json |
| php-inline | 3 | locales/th/php-inline.json |
| php | 3 | locales/th/php.json |
这三种类型分别对应 Laravel 生态中不同的翻译载体:json.json 承载 JSON 键值形式的翻译(用于 Vue/前端组件与 Nova 等);php-inline.json 承载内联(inline)校验消息;php.json 承载 :attribute 形式的 PHP 校验消息。仓库的完整进度总览可查看 docs/status.md,其中列出了所有语言的状态入口。
需要说明的是:该状态文件是仓库维护流程自动生成的结果(相关生成工具 laravel-lang/status-generator 在 composer.json 的 require-dev 中声明),它面向语言包维护者,作用是精确暴露“还差哪几句没翻译”,而非面向最终用户的安装文档。
二、json 类型缺失条目详解:13 条未翻译
th.md 中 json 部分列出了 13 条缺失项,其规律是英文键与英文值完全相同——这正意味着该条目尚未被翻译为泰语。逐条拆解如下:
| 缺失键 | 英文源值 | 所属组件 |
|---|---|---|
| Invalid credential format. | Invalid credential format. | Passkeys |
| Passkey not recognized. It may have been removed from your account. | Passkey not recognized. It may have been removed from your account. | Passkeys |
| Passkey registration session expired. Please try again. | Passkey registration session expired. Please try again. | Passkeys |
| Passkey verification session expired. Please try again. | Passkey verification session expired. Please try again. | Passkeys |
| Reset your password | Reset your password | Framework(认证) |
| The existing encrypted environment file is not in readable format. Use --force to overwrite it. | The existing encrypted environment file is not in readable format. Use --force to overwrite it. | Framework(环境文件加密) |
| The existing encryption key is required to update the encrypted environment file. | The existing encryption key is required to update the encrypted environment file. | Framework(环境文件加密) |
| Unable to register passkey. Please try again. | Unable to register passkey. Please try again. | Passkeys |
| Unable to register this passkey. | Unable to register this passkey. | Passkeys |
| Unable to sign in with this account. | Unable to sign in with this account. | Passkeys |
| Unable to verify passkey. Please try again. | Unable to verify passkey. Please try again. | Passkeys |
| Unable to write the encrypted environment file. | Unable to write the encrypted environment file. | Framework(环境文件加密) |
| Verify your email address | Verify your email address | Framework(邮箱验证) |
这些条目在 locales/th/json.json 中确实以“英文键 = 英文值”的原样形式存在(例如第 340、502-504、563、777-780、814 行),印证了状态报告与翻译文件的一致性。
其中 Passkeys 相关条目占据 8/13,来源组件是 source/passkeys/main/passkeys.json。该源文件只有 3 个键(Invalid credential format.、Passkey registration session expired.、Passkey verification session expired.),而泰语缺失的 Passkeys 条目却包含 8 条——从仓库结构看,其余条目(如 Passkey not recognized、Unable to register passkey 等)应来自更高版本或扩展源(source/passkeys/extended.json),这体现了该仓库“按组件 + 版本组织源文件”的管理方式。
Framework 相关的 5 条缺失则与 source/framework/12.x/framework.json 这类按大版本(11.x、12.x、13.x、master)划分的源文件对应,其中包括 Laravel 的环境文件加密命令(php artisan env:encrypt / env:decrypt)出错提示,以及“Reset your password”“Verify your email address”等认证与邮箱验证文案。
三、php-inline 与 php 类型缺失条目:3 + 3 条校验消息
th.md 后半部分列出了两类 PHP 校验消息的缺失,二者内容一一对应、仅措辞模板不同:
php-inline 缺失(3 条)——无 :attribute 前缀,适用于内联消息场景:
| 键 | 源值 |
|---|---|
| array_keys | This field must only contain the following keys: :values. |
| base64 | This field must be a valid Base64 string. |
| encoding | This field must be encoded in :encoding. |
php 缺失(3 条)——带 :attribute 占位符,适用于标准校验场景:
| 键 | 源值 |
|---|---|
| array_keys | The :attribute field must only contain the following keys: :values. |
| base64 | The :attribute field must be a valid Base64 string. |
| encoding | The :attribute field must be encoded in :encoding. |
这些条目在翻译文件中同样处于“英文原样”状态:locales/th/php-inline.json 第 12、15、41 行,以及 locales/th/php.json 第 12、15、42 行。对应英文源可在 source/framework/12.x/validation.php 中查到(array_keys、base64、encoding 三个校验规则键),说明它们是 Laravel 框架校验器(Validator)新增规则 array_keys、base64、encoding 的官方提示文案。
值得注意的是,泰语语言包中同族校验规则已有翻译,可作为补全时的语言风格参照:
in_array_keys(php-inline):ช่องข้อมูลนี้ต้องมีคีย์อย่างน้อยหนึ่งรายการดังต่อไปนี้: :values(必须至少包含以下键之一)required_array_keys(php-inline):ช่องข้อมูลนี้ต้องประกอบด้วยรายการสำหรับ: :values
可见缺失的 array_keys 与其语义相近,补全时应保持一致的泰语表达风格。
四、从源码看泰语包的接入方式与结构
泰语语言包目录 locales/th/ 共包含 5 个文件,结构如下:
_excludes.json:排除清单,列出泰语包不翻译的条目(如CSV (.csv)、Excel (.xlsx)、Nova),这些条目会保持英文原样;json.json:JSON 键值翻译,主要服务前端组件与 Nova 场景;json-inline.json:JSON 内联消息;php.json:带:attribute的标准 PHP 校验消息;php-inline.json:内联 PHP 校验消息。
整个仓库通过 src/Plugin.php 中的 Plugin 类向 Laravel 发布翻译,其 $plugins 数组注册了 Breeze、Cashier、Fortify、Jetstream、Laravel(V11/V12/V13)、Nova、Passkeys、Spark、UI 等全部子插件,并通过 LaravelLang\Publisher 机制(见 composer.json 中 laravel-lang/publisher: ^16.0 依赖)在安装时按需发布对应组件的语言文件。
在 Laravel 项目中安装并使用泰语本地化,标准流程为:
composer require --dev laravel-lang/lang
php artisan lang:add th
此后 th 语言文件会被发布到项目的 lang/th/ 目录,应用只需将 config/app.php 中的 locale 设为 th,即可启用泰语界面与校验消息。由于 php-inline.json 与 php.json 中缺失的 3 条校验消息当前仍为英文,泰语用户会在触发 array_keys、base64、encoding 校验规则时看到英文提示——这正是状态报告提示的“待翻译空白区”。
五、补全建议:给语言包维护者的实操清单
若你是该语言包的维护者,可按以下步骤补齐这 19 条翻译:
- 逐条翻译 json.json 中 13 条缺失:重点处理 8 条 Passkeys 相关文案(如 “Passkey not recognized.” → “ไม่รู้จักพาสคีนี้...”),以及 Framework 的环境加密错误提示与 “Reset your password” / “Verify your email address”;
- 翻译 php-inline.json 与 php.json 各 3 条:参照已翻译的
in_array_keys、required_array_keys风格,完成array_keys、base64、encoding三组(php 版本记得保留:attribute占位符); - 验证一致性:确认翻译后的键名与 source/framework/12.x/validation.php、source/passkeys/main/passkeys.json 中的英文源键完全一致,值中保留
:values、:encoding等占位符; - 重新生成状态报告:仓库通过
vendor/bin/lang sync(见 composer.json 的 scripts 配置)同步语言文件,随后由laravel-lang/status-generator重新生成docs/statuses/th.md,届时 “All missed: 19” 的计数应相应下降。
六、小结
docs/statuses/th.md 虽是一份自动生成的缺口清单,却是理解 laravel-lang/lang 仓库运作方式的最佳入口:它以文件类型(json / php-inline / php)为维度精确暴露未翻译条目,让维护者可以按组件溯源(Passkeys、Framework 校验、环境加密等)、按源文件对照(source/framework、source/passkeys)、按风格参照补全。对于应用开发者而言,读懂这份报告同样有价值——它直接告诉你“泰语用户在使用到哪些功能时会看到英文提示”,从而决定是否需要自行覆盖翻译。
泰语包的 19 条缺口全部集中在较新加入的功能文案上,核心翻译体系(876 行 json 翻译、140 行 php-inline、140 行 php)已相当完整,补全这最后 19 条即可让泰语本地化达到全量覆盖。