Laravel Localizations 中的马尔加什语(mg)本地化状态解析:缺失词条清单、来源追踪与补全指南
Laravel Localizations 中的马尔加什语(mg)本地化状态解析:缺失词条清单、来源追踪与补全指南
马尔加什语(Malagasy,代码 mg)是 Laravel Localizations 项目(laravel-lang/lang)所维护的 128 种语言之一。本文以仓库内的状态报告 docs/statuses/mg.md 为核心,逐条核对 mg 语言包当前仍未翻译的 15 条词条——涉及 JSON、PHP、PHP Inline 三种格式——并结合 locales/mg 目录下的实际翻译文件与 source 目录中的英文源词条,说明这些缺失项分别来自 Laravel 框架、Passkeys 扩展等哪个模块,以及如何解读状态报告并完成补全。读完本文,你将能读懂任何一门语言的本地化状态页,并能直接定位到缺失词条的源文件与待翻译位置。
状态报告是什么:mg.md 在项目中的位置
整个仓库的翻译完成度由一个总览页 docs/status.md 汇总,页首标注了整体进度:
Translation of localizations is completed by 97.82% (147.1K / 150.4K)。
总览页以 8 列 × 多行的表格列出全部 128 种语言,mg 以 ❗ 标记(表示尚有缺失),并链接到其专属状态页 docs/statuses/mg.md。例如在 docs/status.md 中可以看到 <a href="https://link.gitcode.com/i/a431f2e2fc9ac01d1b8b2ebaadbf4bf1" target="_blank">mg ❗</a> 的入口。
每一份 docs/statuses/<语言>.md 都是自动化生成的"待办清单":它不列出已翻译的内容,而是精确列出当前仍为英文原文、尚未翻译的词条,并按文件格式分类。对 mg 而言,报告首页给出的结论是:
All missed: 15(共缺失 15 条)
这 15 条分布在三个文件中:
| 文件格式 | 缺失条数 | 对应实际文件 |
|---|---|---|
json |
11 | locales/mg/json.json |
php-inline |
2 | locales/mg/php-inline.json |
php |
2 | locales/mg/php.json |
也就是说,缺失并非集中在单一文件,而是三种输出格式各自有未翻译词条。下面分别核对。
json 格式缺失的 11 条:Passkeys 与加密环境文件文案
状态报告 docs/statuses/mg.md 的 json 小节列出了 11 条缺失词条。逐一对照实际翻译文件 locales/mg/json.json,可以确认这些词条仍然保留英文原文作为占位值。完整清单如下:
| Key(英文原文) | Value(当前值) |
|---|---|
| Invalid credential format. | Invalid credential format. |
| Passkey not recognized. It may have been removed from your account. | Passkey not recognized. It may have been removed from your account. |
| Passkey registration session expired. Please try again. | Passkey registration session expired. Please try again. |
| Passkey verification session expired. Please try again. | Passkey verification session expired. Please try again. |
| 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. |
| The existing encryption key is required to update the encrypted environment file. | The existing encryption key is required to update the encrypted environment file. |
| Unable to register passkey. Please try again. | Unable to register passkey. Please try again. |
| Unable to register this passkey. | Unable to register this passkey. |
| Unable to sign in with this account. | Unable to sign in with this account. |
| Unable to verify passkey. Please try again. | Unable to verify passkey. Please try again. |
| Unable to write the encrypted environment file. | Unable to write the encrypted environment file. |
这 11 条可以清晰归为两组,分别对应 Laravel 生态中两个不同来源:
(1)Passkeys(通行密钥)相关,共 8 条。 包括 "Invalid credential format."、"Passkey not recognized. ..."、"Passkey registration session expired. ..."、"Passkey verification session expired. ..." 以及 4 条 "Unable to ..." 系列。从源码结构看,这些词条与 source/passkeys 目录中的扩展词条对应——例如 source/passkeys/extended.json 中收录了 "Passkey not recognized. It may have been removed from your account."、"Unable to register passkey. Please try again." 等 5 条英文源文案。Passkeys 是 Laravel 11+ 引入的无密码登录能力,其前端错误提示即通过这些词条渲染。
(2)加密环境文件(encrypted environment file)相关,共 3 条。 包括 "The existing encrypted environment file is not in readable format. Use --force to overwrite it."、"The existing encryption key is required to update the encrypted environment file."、"Unable to write the encrypted environment file."。这组文案属于 Laravel 框架层 env:encrypt / env:decrypt 命令(自 Laravel 11 起支持加密 .env 文件)的输出提示,其英文源词条分布在 source/framework 目录下多个版本分支(11.x、12.x、13.x、master)的 framework.json 中。对照同族的已翻译词条可以佐证:例如 locales/mg/json.json 中 "Encrypted environment file already exists." 和 "Encrypted environment file not found." 已翻译为马尔加什语,而上述 3 条恰好仍是英文,属于同一功能家族中尚未覆盖的部分。
从文件内部看,这 11 条缺失也符合一个规律:mg 的 json 词条总数约 875 行(locales/mg/json.json),绝大多数已翻译,唯独这批较新的功能(Passkeys、环境文件加密)词条未被覆盖。
php 与 php-inline 格式缺失的 2 条:验证器新规则
php 与 php-inline 两个小节各缺失 2 条,且缺失的 Key 完全相同——array_keys 与 base64,只是文案形态不同:
php 格式(带 :attribute 占位符,用于传统验证错误输出):
| Key | Value |
|---|---|
| array_keys | The :attribute field must only contain the following keys: :values. |
| base64 | The :attribute field must be a valid Base64 string. |
php-inline 格式(面向单字段内联提示,省略 :attribute):
| Key | Value |
|---|---|
| array_keys | This field must only contain the following keys: :values. |
| base64 | This field must be a valid Base64 string. |
这两条均可在英文源文件 source/framework/master/validation.php 中找到对应定义:
array_keys(validation.php#L16):The :attribute field must only contain the following keys: :values.,用于校验数组只能包含指定键名;base64(validation.php#L19):The :attribute field must be a valid Base64 string.,用于校验 Base64 字符串。
array_keys 与 base64 都是 Laravel 较新版本验证器补充的规则,因此 mg 语言包中这两条仍为英文。核对实际文件可以确认:locales/mg/php.json 与 locales/mg/php-inline.json 中 array_keys 的值仍是英文,base64(php.json#L15、php-inline.json#L15)同理。而同一文件中的其他验证规则(如 accepted、email、required 等)均已翻译为马尔加什语,说明这两条属于验证器新规则补丁未跟上的典型缺口。
未缺失的部分:_excludes.json 与排除机制
状态报告只统计"该翻译而未翻译"的词条。有一类词条虽然也没有马尔加什语译文,却不会被计入缺失——它们被列在 locales/mg/_excludes.json 中,由项目明确排除在翻译范围之外。
该文件包含 96 个 Key,例如 "Albania"、"Angola"、"API Token"、"CSV (.csv)"、"Log Viewer"、"Password" 等。这类词条通常是:
- 国家/地区名称(Albania、Angola、Vanuatu……),多数语言直接沿用或仅做音译,项目选择统一排除;
- 产品专有名词("API Token"、"Log Viewer"、"Nova"),保持英文更符合惯例;
- 通用界面词("Loading"、"OK"、"Total:"、"Type"、"Whoops" 等)。
因此,在判断一门语言的完成度时,docs/statuses/*.md 的 "All missed" 数字是净缺失数——它已经扣除了 _excludes.json 的豁免项。这也是为什么整体完成度高达 97.82%,而各语言仍能精确统计出少量残留缺口。
如何解读与补全:从状态页到翻译文件的操作路径
理解了状态报告的生成逻辑后,补全一门语言的翻译就变成了一条可复现的操作路径。以 mg 为例:
-
读取状态页 docs/statuses/mg.md,按
json/php-inline/php三个小节收集缺失的 Key 与英文原文(即上文三张清单)。 -
定位待编辑文件:
json格式的词条写入 locales/mg/json.json,php格式写入 locales/mg/php.json,php-inline格式写入 locales/mg/php-inline.json。三个文件都是标准的键值对 JSON,翻译时只需将英文 Value 替换为马尔加什语译文,同时保留 Key 不变——因为 Key 是 Laravel 框架在运行时用于查找文案的标识符,绝不能改动。 -
保留占位符:
php格式的词条中包含:attribute、:values等占位符(如The :attribute field must only contain the following keys: :values.),翻译时必须原样保留这些占位符,否则验证错误信息会丢失字段名等动态内容。可以参考同一文件内已翻译词条的处理方式,例如 locales/mg/php.json 中 "accepted" 译为 "Tsy maintsy ekena ny :attribute.",占位符被完整保留。 -
参考同族已译词条:对于 Passkeys 与加密环境文件这类功能家族,可以对照 locales/mg/json.json 中已翻译的同族词条保持术语一致。例如环境文件加密的 3 条缺失,可参考已翻译的 "Encrypted environment file already exists."(json.json#L252)所采用的术语风格。
-
核对排除清单:若某个 Key 出现在 locales/mg/_excludes.json 中,则无需翻译,也不会计入缺失。
补全后重新生成状态报告,docs/statuses/mg.md 中的缺失数字即会相应减少,直至 "All missed: 0",届时该语言在 docs/status.md 总览中的标记会由 ❗ 变为 ✔(目前 128 种语言中仅 ko 达到这一状态,参见 status.md#L238)。
小结:状态报告是本地化工作的"体检单"
docs/statuses/mg.md 这份文档的价值在于精确、可执行:它以 15 条缺失词条为核心,将马尔加什语语言包与 Laravel 生态最新功能(Passkeys 无密码登录、加密环境文件、验证器新规则)之间的差距量化呈现。配合 locales/mg 的实际文件与 source 的英文源词条,开发者可以在几分钟内定位全部缺口并完成补全。对于 Laravel 本地化贡献者而言,读懂这类状态页,就等于掌握了整个 128 语言协作体系的"体检单"读取方法。