企业官网建设流程全解析

• 后端

导读

本文围绕 docs/statuses/bg.md 展开，逐项拆解 Laravel Lang 项目中保加利亚语（bg）语言包的翻译缺口：当前共有 15 个未翻译条目（json 11 个、php 2 个、php-inline 2 个），覆盖 Laravel Passkeys、框架环境文件加密命令与表单验证规则三个来源。读者读完本文，将能读懂状态报告中的每个缺失项从哪个源码文件而来、对应仓库中哪个语言文件、以及如何快速补全并验证翻译。

一、背景：bg 状态报告在 Laravel Lang 项目中的定位

laravel-lang/lang是一个为 Laravel 生态提供多语言翻译的 Composer 包，覆盖 Laravel Framework、Jetstream、Fortify、Breeze、Cashier、Nova、Spark 与 UI 等组件（参见 composer.json 中的description）。每个语言目录（如 locales/bg）下都存放着json.json、json-inline.json、php.json、php-inline.json四类语言文件。

docs/statuses/目录为每种语言生成一份翻译完成状态报告，docs/status.md 是汇总入口，当前整体完成度为97.82%（147.1K / 150.4K）。而 docs/statuses/bg.md 正是保加利亚语的明细报告：它不展示已翻译内容，而是精确列出**仍然缺失（未翻译）**的 key，作为维护者补全翻译的行动清单。

这类状态文件由laravel-lang/status-generator自动生成（见 composer.json 的require-dev配置），它会把每种语言的翻译与英文源文件逐 key 比对，凡是值仍为英文原文（即尚未翻译）的条目，都会落入对应语言的 status 报告中。

二、bg 缺失全景：15 个待翻译条目总览

根据 docs/statuses/bg.md 的统计，保加利亚语包共缺 15 个条目，按文件类型分布如下：

三类文件各司其职：

• json系列（locales/bg/json.json）：Laravel 应用中通过__()/trans()使用的键值对，包含 Passkeys 与框架环境加密等新特性的消息；
• php系列（locales/bg/php.json）：供lang/目录下 PHP 语言文件使用的验证规则消息，key 为array_keys、base64这类规则名；
• php-inline系列：验证规则的内联（inline）变体，即验证规则直接写在字段上时展示的短消息，key 与php相同，但文案以 "This field ..." 而非 "The :attribute field ..." 开头。

值得注意：php与php-inline缺失的 key 完全一致（都是array_keys与base64），说明这两条规则在两个格式中均未翻译，补全时需两处同时处理。

三、json 缺失项溯源：Passkeys 与 env 加密命令

3.1 八个 Passkeys 相关消息

json 缺失的 11 个条目中，有 8 个来自 Laravel Passkeys 功能。它们分布在两份源文件中：

源文件一：source/passkeys/main/passkeys.json（3 个）

源文件二：source/passkeys/extended.json（5 个）

这些消息在 locales/bg/json.json 中仍然保留英文原文（例如第 340、502-504、777-781 行），因此被状态生成器判定为缺失。它们全部与 Passkeys（无密码登录）的用户交互流程相关：注册、验证、会话过期、凭据无法识别等场景，是保加利亚语用户在无密码登录时直接会看到的提示文案。

3.2 三个环境文件加密相关消息

其余 3 个缺失条目来自 Laravel Framework 的环境文件加密功能（env:encrypt/env:decrypt命令）：

这几条是 Laravel 11.0.7 之后新增的环境加密错误消息——这也解释了为什么 composer.json 中声明了"conflict": { "laravel/framework": "<11.0.7" }：该项目要求的最低框架版本恰好包含这些新消息。框架侧对应的基础键（如Encrypted environment file already exists.、A decryption key is required.等）可见于 source/framework/master/framework.json，而上述三条属于较新的错误分支，bg 语言包尚未跟进翻译。

四、php 与 php-inline 缺失项：验证规则 array_keys 与 base64

php 与 php-inline 各缺 2 个 key，均为框架验证器（Validator）的规则消息。它们对应的英文源文本在框架验证语言文件中可以精确找到：source/framework/master/validation.php 第 16 行定义了array_keys（The :attribute field must only contain the following keys: :values.），第 19 行定义了base64（The :attribute field must be a valid Base64 string.）。

array_keys：要求字段必须只包含指定的键集合，用于校验关联数组的键名，:values会被替换为允许的键列表。

base64：要求字段必须是合法的 Base64 编码字符串，常用于文件上传或二进制数据的校验。

在 locales/bg/php.json 中，这两条规则的值仍是英文（第 12、15 行）：

"array_keys": "The :attribute field must only contain the following keys: :values.", "base64": "The :attribute field must be a valid Base64 string."

补全时可按保加利亚语习惯译为类似形式，并保留:attribute、:values占位符：

"array_keys": "Полето :attribute трябва да съдържа само следните ключове: :values.", "base64": "Полето :attribute трябва да бъде валиден Base64 низ."

php-inline 变体（locales/bg/php-inline.json）则使用This field句式，且无需:attribute占位符，例如This field must only contain the following keys: :values.。

五、源码侧工作机制：Plugin 映射与发布流程

状态报告中每个缺失项都能在源码侧找到对应"发布映射"，这是理解整个翻译流水线的关键。Laravel Lang 通过插件（Plugin）机制把source/下的英文源文件按版本发布到目标语言目录：

src/Plugins/Passkeys/Main.php 声明了 Passkeys 的映射规则：

public function files(): array { return [ 'passkeys/main/passkeys.json' => '{locale}.json', 'passkeys/extended.json' => '{locale}.json', ]; }

即source/passkeys/main/passkeys.json与source/passkeys/extended.json会合并进各语言（含 bg）的{locale}.json文件——这正是 8 个 Passkeys 缺失项进入 bg 语言包的路径。

src/Plugins/Laravel/Master.php 则映射框架内容：

'framework/master/framework.json' => '{locale}.json', 'framework/extended.json' => '{locale}.json', 'framework/master/auth.php' => '{locale}/auth.php', 'framework/master/validation.php' => '{locale}/validation.php', ...

其中framework/master/validation.php对应 php 语言文件，framework/master/framework.json与framework/extended.json合并进 json 语言文件。这两个插件共同决定了 bg 语言包中 json/php 文件的最终键集合，也即状态报告比对的基准。

插件由 src/ServiceProvider.php 在运行时注册：当检测到LaravelLang\Publisher\Plugins\Provider类存在时，自动注册Plugin，从而将各插件的映射加载到发布流程中（依赖laravel-lang/publisher ^16.0，见 composer.json）。

六、_excludes.json 与语言包边界

保加利亚语包的 locales/bg/_excludes.json 中声明了 3 个被排除的 key：

[ "CSV (.csv)", "Excel (.xlsx)", "Nova" ]

这意味着这 3 个条目不参与bg 语言包的翻译与统计，因此也不会出现在 docs/statuses/bg.md 的缺失清单中。这类排除通常是因为目标语言环境下该文案保持原文更合适（例如文件格式名称），或者该功能（Nova）对特定语言采用不同的本地化策略。理解_excludes.json有助于解释"为什么某个英文词条既不在语言文件中、也不在缺失列表中"。

七、如何补全并验证翻译

7.1 定位待翻译文件

根据状态报告的缺失清单，逐项在对应语言文件中补全：

7.2 补全要点

1. 保留占位符：json消息中的:count、:date、:amount等参数必须原样保留，否则运行时替换会失效；
2. 保留复数形式：如(and :count more errors)这类带|分隔的复数形式，需按保加利亚语复数规则（通常 1 / 其他 两组）保持对应结构；
3. 区分两种验证文案：php使用The :attribute field ...句式，php-inline使用This field ...句式，两者占位符不同，不可混用；
4. 参照邻近语言：同为西里尔字母语系的其他语言（如 locales/ru/json.json）可作为翻译风格的参考，但不可直接照搬。

7.3 验证流程

补全后可运行项目自带的 Composer 脚本（见 composer.json）验证：

composer run format # 执行 vendor/bin/lang sync 同步翻译并运行代码风格检查 composer test # 运行 PHPUnit 测试套件

vendor/bin/lang sync会把source/的最新英文源同步进各语言文件并执行格式化；随后laravel-lang/status-generator重新生成状态报告，docs/statuses/bg.md 中的缺失数量会相应减少，直到归零。

八、环境与依赖要求

参与该项目翻译补全需要满足以下环境条件（以 composer.json 为准）：

• PHP：^8.2；
• 扩展：ext-json；
• 核心依赖：laravel-lang/publisher ^16.0；
• 冲突限制：laravel/framework < 11.0.7（因为 env 加密相关的新消息依赖 11.0.7+ 的框架版本）；
• 开发依赖：laravel-lang/status-generator ^2.11（生成 status 报告）、phpunit/phpunit ^11.0 || ^12.0（测试）、dragon-code/codestyler ^6.0与laravel/pint（代码风格）。

安装方式为标准的 Composer 开发依赖引入（composer require --dev laravel-lang/lang），安装后即可在 Laravel 应用中把config/app.php的locale设为bg使用该语言包。

九、小结

通过 docs/statuses/bg.md 这份状态报告，可以完整梳理保加利亚语语言包的补全路线：8 个 Passkeys 交互消息 + 3 个环境文件加密消息补齐 json 缺口，array_keys与base64两条验证规则同时补齐 php 与 php-inline 缺口，即可使 bg 语言包达到 100% 完成度。过程中结合 source/、src/Plugins 与 locales/bg 的源码证据，可以清晰地理解 Laravel Lang"英文源文件 → 插件映射 → 语言文件 → 状态报告"的完整翻译流水线，这套方法论同样适用于仓库中其余 127 种语言的维护工作。

• 后端