Laravel 泰语本地化翻译缺口分析:基于 laravel-lang/lang 的 th 语言包状态解读与补全指南

原创2026-09-27 15:51:291,960 阅读
文章标签:后端

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 条翻译:

  1. 逐条翻译 json.json 中 13 条缺失:重点处理 8 条 Passkeys 相关文案(如 “Passkey not recognized.” → “ไม่รู้จักพาสคีนี้...”),以及 Framework 的环境加密错误提示与 “Reset your password” / “Verify your email address”;
  2. 翻译 php-inline.json 与 php.json 各 3 条:参照已翻译的 in_array_keys、required_array_keys 风格,完成 array_keys、base64、encoding 三组(php 版本记得保留 :attribute 占位符);
  3. 验证一致性:确认翻译后的键名与 source/framework/12.x/validation.php、source/passkeys/main/passkeys.json 中的英文源键完全一致,值中保留 :values、:encoding 等占位符;
  4. 重新生成状态报告:仓库通过 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 条即可让泰语本地化达到全量覆盖。

登录后查看全文
lang