Laravel Localizations 中的马尔加什语(mg)本地化状态解析:缺失词条清单、来源追踪与补全指南

原创2026-09-27 16:05:041,945 阅读
文章标签:后端

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 为例:

  1. 读取状态页 docs/statuses/mg.md,按 json / php-inline / php 三个小节收集缺失的 Key 与英文原文(即上文三张清单)。

  2. 定位待编辑文件:json 格式的词条写入 locales/mg/json.json,php 格式写入 locales/mg/php.json,php-inline 格式写入 locales/mg/php-inline.json。三个文件都是标准的键值对 JSON,翻译时只需将英文 Value 替换为马尔加什语译文,同时保留 Key 不变——因为 Key 是 Laravel 框架在运行时用于查找文案的标识符,绝不能改动。

  3. 保留占位符:php 格式的词条中包含 :attribute、:values 等占位符(如 The :attribute field must only contain the following keys: :values.),翻译时必须原样保留这些占位符,否则验证错误信息会丢失字段名等动态内容。可以参考同一文件内已翻译词条的处理方式,例如 locales/mg/php.json 中 "accepted" 译为 "Tsy maintsy ekena ny :attribute.",占位符被完整保留。

  4. 参考同族已译词条:对于 Passkeys 与加密环境文件这类功能家族,可以对照 locales/mg/json.json 中已翻译的同族词条保持术语一致。例如环境文件加密的 3 条缺失,可参考已翻译的 "Encrypted environment file already exists."(json.json#L252)所采用的术语风格。

  5. 核对排除清单:若某个 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 语言协作体系的"体检单"读取方法。

登录后查看全文
lang