Laravel 本地化完成度分析:sr_Latn_ME(黑山塞尔维亚语拉丁字母)语言包缺失词条全解读
Laravel 本地化完成度分析:sr_Latn_ME(黑山塞尔维亚语拉丁字母)语言包缺失词条全解读
本文聚焦于 Laravel 官方多语言生态仓库中 sr_Latn_ME(黑山塞尔维亚语、拉丁字母变体)语言包的翻译完成度报告,逐条解析当前缺失的 19 个词条——包括 Passkey 登录错误提示、加密环境文件命令消息与新增验证规则——并借助仓库源码定位它们的真实来源,给出可直接套用的补译方案,帮助维护者快速将这一区域语言包的完成度提升到 100%。
一、文档背景:状态报告如何生成
仓库根目录下的 docs/status.md 是全项目 128 种语言本地化完成度的总览页面,它统计了 Laravel Framework、Jetstream、Fortify、Breeze、Cashier、Nova 与 UI 等组件的全部词条,并给出总完成率(当前约为 97.82%)。每种语言对应一份独立的报告,存放于 docs/statuses/ 目录,例如本文讨论的 sr_Latn_ME 状态报告。
这份报告的核心逻辑是:以仓库根目录 locales/ 下的真实语言包为基准,逐 key 比对上游英文原文(位于 source/ 目录),凡是在语言包中缺失、或仍保留英文原文未翻译的词条,都会在报告中按格式分组列出。因此,sr_Latn_ME 报告中的每一个缺失词条,都对应一个可以在 locales/sr_Latn_ME/ 目录中实际查证的状态。
二、sr_Latn_ME 语言包整体完成度概览
sr_Latn_ME 代表黑山使用的塞尔维亚语拉丁字母变体(Latin script, Montenegro 区域变体)。与同属塞尔维亚语族的 sr_Cyrl(西里尔字母)和 sr_Latn(通用拉丁字母)不同,它在用词和拼写习惯上带有黑山本地特征。
根据 sr_Latn_ME 状态报告 的头部统计,该语言包当前共有 19 个缺失词条,按文件格式分为三组:
| 文件格式 | 缺失数量 | 用途 |
|---|---|---|
json |
13 | 面向 Vue/JS 前端的界面文案 |
php-inline |
3 | 验证器"行内"短消息(不包含字段名) |
php |
3 | 验证器完整消息(包含 :attribute 字段名) |
对应到仓库中的真实文件:locales/sr_Latn_ME/json.json、locales/sr_Latn_ME/php-inline.json 与 locales/sr_Latn_ME/php.json。其中 json.json 已翻译 800+ 条(涵盖国家列表、订阅计费、团队协作、双因素认证等),说明该语言包整体成熟度较高,剩余缺口集中在较新的功能模块上。
三、json 格式缺失的 13 个词条:三大来源逐一解析
3.1 来源一:Laravel Passkeys(通行密钥)错误消息
json 组中超过半数的缺失词条来自 Laravel 新引入的 Passkeys 通行密钥认证功能,对应上游原文 source/passkeys/main/passkeys.json,共 7 条:
| Key | 英文原文 |
|---|---|
Passkey not recognized. It may have been removed from your account. |
未识别的通行密钥,可能已从账户中移除 |
Passkey registration session expired. Please try again. |
通行密钥注册会话已过期 |
Passkey verification session expired. Please try again. |
通行密钥验证会话已过期 |
Unable to register passkey. Please try again. |
无法注册通行密钥 |
Unable to register this passkey. |
无法注册此通行密钥 |
Unable to sign in with this account. |
无法使用此账户登录 |
Unable to verify passkey. Please try again. |
无法验证通行密钥 |
这一类词条直接服务于 WebAuthn/Passkey 登录流程的前端交互,属于安全认证模块的核心提示,缺失会导致黑山用户在通行密钥注册、登录、验证失败时看到英文原文。
3.2 来源二:加密环境文件命令(Encrypted Environment File)
另有 4 条来自 Laravel 内置的 .env 加密相关命令(env:encrypt / env:decrypt / env:update)抛出的异常消息:
| Key | 英文原文 |
|---|---|
Invalid credential format. |
凭据格式无效 |
The existing encrypted environment file is not in readable format. Use --force to overwrite it. |
现有加密环境文件无法读取,请使用 --force 覆盖 |
The existing encryption key is required to update the encrypted environment file. |
更新加密环境文件需要现有加密密钥 |
Unable to write the encrypted environment file. |
无法写入加密环境文件 |
这组消息提醒使用者:在更新加密的 .env 文件时必须提供旧密钥,且当文件损坏时需要用 --force 参数强制覆盖,属于运维向的 CLI 错误提示。
3.3 来源三:认证与邮箱验证流程
最后 2 条来自通用认证流程:
| Key | 英文原文 |
|---|---|
Reset your password |
重置您的密码 |
Verify your email address |
验证您的电子邮件地址 |
这两条通常出现在密码重置邮件与邮箱验证邮件的主题行或按钮文案中。
四、php / php-inline 格式缺失的 3 个验证规则词条
php 与 php-inline 两组缺失的词条完全相同,都是三个较新的 Laravel 验证规则:array_keys、base64、encoding。区别仅在于消息模板中是否携带 :attribute 字段名占位符:
| 规则 | php 完整消息(含字段名) | php-inline 行内消息(不含字段名) |
|---|---|---|
array_keys |
The :attribute field must only contain the following keys: :values. |
This field must only contain the following keys: :values. |
base64 |
The :attribute field must be a valid Base64 string. |
This field must be a valid Base64 string. |
encoding |
The :attribute field must be encoded in :encoding. |
This field must be encoded in :encoding. |
对照上游英文原稿 source/framework/master/validation.php 可以确认:
array_keys规则要求数组字段只能包含指定的键集合,占位符:values会填充允许的键列表;base64规则校验字段是否为合法的 Base64 字符串;encoding规则校验字段是否按指定字符编码(占位符:encoding)编码。
值得注意的是,在 locales/sr_Latn_ME/php.json 中,这三个 key 当前的值仍是英文原文(尚未翻译),而同文件内的其他 140+ 条验证规则(required、email、numeric 等)均已译为黑山塞尔维亚语拉丁字母,例如 "accepted": "Polje :attribute mora biti prihvaćeno."。因此,只需补译这 3 个 key 即可让验证消息全部本地化。
五、从源码到语言包的完整调用链
要准确补译,有必要理解这些词条在 Laravel 中的真实使用场景:
- 验证规则消息由 Laravel Framework 的 Validator 组件按需加载。
php.json中的消息在服务端渲染表单错误时使用(如$errors变量输出),而php-inline.json用于同一规则的"行内"变体。二者必须保持语义一致,仅差一个:attribute前缀。这与 source/framework/master/validation.php 中定义的英文原文一一对应。 - json 消息面向浏览器端。Passkey 词条由 source/passkeys/main/passkeys.json 生成;加密环境文件词条由 Laravel 框架命令层抛出,最终通过
lang()或前端翻译函数取词。 - 仓库通过
source/与locales/双目录结构实现了"原文-译文"的可比对维护,状态报告正是基于这种结构自动计算缺失项。
六、补译实操:将 sr_Latn_ME 完成度提升至 100%
以下是根据黑山塞尔维亚语拉丁字母的既有翻译风格拟定的补译建议,可直接写入 locales/sr_Latn_ME/json.json、locales/sr_Latn_ME/php.json 与 locales/sr_Latn_ME/php-inline.json:
json 组(13 条):
"Invalid credential format.": "Format akreditiva nije ispravan.",
"Passkey not recognized. It may have been removed from your account.": "Passkey nije prepoznat. Možda je uklonjen sa vašeg naloga.",
"Passkey registration session expired. Please try again.": "Sesija registracije passkey-a je istekla. Pokušajte ponovo.",
"Passkey verification session expired. Please try again.": "Sesija verifikacije passkey-a je istekla. Pokušajte ponovo.",
"Reset your password": "Resetujte svoju lozinku",
"The existing encrypted environment file is not in readable format. Use --force to overwrite it.": "Postojeći šifrovani fajl okruženja nije u čitljivom formatu. Koristite --force da biste ga prepisali.",
"The existing encryption key is required to update the encrypted environment file.": "Postojeći ključ za šifrovanje je potreban za ažuriranje šifrovanog fajla okruženja.",
"Unable to register passkey. Please try again.": "Nije moguće registrovati passkey. Pokušajte ponovo.",
"Unable to register this passkey.": "Nije moguće registrovati ovaj passkey.",
"Unable to sign in with this account.": "Nije moguće prijaviti se sa ovim nalogom.",
"Unable to verify passkey. Please try again.": "Nije moguće verifikovati passkey. Pokušajte ponovo.",
"Unable to write the encrypted environment file.": "Nije moguće upisati šifrovani fajl okruženja.",
"Verify your email address": "Potvrdite svoju adresu e-pošte"
php 组(3 条,含 :attribute):
"array_keys": "Polje :attribute može sadržati samo sledeće ključeve: :values.",
"base64": "Polje :attribute mora biti validan Base64 string.",
"encoding": "Polje :attribute mora biti kodirano u :encoding."
php-inline 组(3 条,不含 :attribute):
"array_keys": "Ovo polje može sadržati samo sledeće ključeve: :values.",
"base64": "Ovo polje mora biti validan Base64 string.",
"encoding": "Ovo polje mora biti kodirano u :encoding."
翻译时需注意两点:其一,保持占位符(:values、:encoding、:attribute)原样不动,它们是 Laravel 运行时替换的参数;其二,延续该语言包已有的风格——沿用 Polje ... mora ... 的句式与 e-pošte(电子邮件)、nalog(账户)等既有用词,保证黑山本地用户阅读体验一致。
七、结语:用状态报告驱动本地化闭环
sr_Latn_ME 的 19 个缺失词条并非随机分散,而是集中于 Passkeys 认证、环境加密命令与新增验证规则这三类新特性上,这正反映了语言包维护的典型节奏:上游 Laravel 每新增一个功能,各语言包便会出现一批待补词条。借助 docs/statuses/sr_Latn_ME.md 这类自动生成的状态报告,配合 source/ 目录下的英文原文与 locales/sr_Latn_ME/ 下的既有译文,任何维护者都可以在几分钟内完成缺口排查与补译,让黑山塞尔维亚语(拉丁字母)用户获得与英语完全一致的使用体验。对于需要同时维护多语言的团队,同样的方法也适用于仓库中其余 127 种语言的完成度管理。