企业官网建设流程全解析

• 后端

本篇指南以 docs/statuses/cs.md 状态报告为骨架，深入剖析laravel-lang/lang仓库中捷克语（cs）语言包的翻译完成度现状：15 个尚未翻译的键分布在 json、php、php-inline 三种格式中，分别关联 Laravel Passkeys（WebAuthn 无密码登录）、加密环境文件命令与验证规则。读完本文，你将掌握这些缺失键的准确来源、在仓库中的对应实现，以及如何按官方流程补齐并验证翻译。

一、cs 语言包翻译状态总览

在laravel-lang/lang项目中，每种语言的翻译进度会由laravel-lang/status-generator自动生成状态报告，统一汇总在 docs/status.md，每个语言对应一个独立页面（如 docs/statuses/cs.md）。

根据 docs/statuses/cs.md 的统计，捷克语（cs）语言包当前共有15 个键尚未翻译，分布如下：

其中 json 格式的翻译文件位于 locales/cs/json.json，php 格式位于 locales/cs/php.json，php-inline 格式位于 locales/cs/php-inline.json。对比这三个文件可以发现，"缺失"的含义是：键已经存在于语言文件中，但值仍是英文原文，尚未翻译成捷克语——例如 locales/cs/json.json 中的"Invalid credential format.": "Invalid credential format."即为典型的未翻译状态。

二、json 格式：11 个缺失键全清单

cs 语言包中 json 格式共缺失 11 个键，可细分为两大来源：Passkeys（WebAuthn 无密码登录）相关错误消息 8 条，以及 Laravel 加密环境文件命令相关错误 3 条。完整清单如下：

2.1 Passkeys：WebAuthn 无密码登录的 8 条错误消息

前 8 条消息全部来自 Laravel Passkeys 扩展包（source/passkeys），该扩展为 Laravel 应用引入基于 WebAuthn 标准的无密码登录能力。其基础消息定义在 source/passkeys/main/passkeys.json 中，例如：

{ "Invalid credential format.": "Invalid credential format.", "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." }

从消息文案可以推断，这 8 条覆盖了 Passkey 全生命周期的错误场景：凭证格式非法（Invalid credential format.）、注册会话过期（Passkey registration session expired...）、验证会话过期（Passkey verification session expired...）、注册失败（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.）。其中 "Passkey not recognized. It may have been removed from your account." 提示用户凭证可能已从账户中移除，属于安全提示类文案。

值得注意的是，cs 语言包的 json.json 中这些键的值仍与英文键名完全一致，说明 Passkeys 相关文案尚未完成捷克语本地化。而 locales/cs/php.json 中已翻译的 "A decryption key is required."（"Je vyžadován dešifrovací klíč."）等键表明，同一文件里与安全相关的其余键大多已有翻译，这 8 条属于新增键的翻译缺口。

2.2 加密环境文件命令的 3 条错误消息

另外 3 条消息与 Laravel 框架的加密环境文件命令（php artisan env:encrypt/env:decrypt/env:update）相关，属于框架级基础文案，可在 source/framework 目录下各版本的 framework.json 中溯源。它们描述的是操作加密.env文件时的异常场景：

• 已存在的加密环境文件不可读，需要用--force覆盖（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.）。

作为对照，同一文件 locales/cs/json.json 中同主题的 "Encrypted environment file already exists."（"Soubor zašifrovaného prostředí již existuje."）与 "Encrypted environment file not found."（"Soubor zašifrovaného prostředí nebyl nalezen."）已完成翻译，可见这 3 条同样属于新增文案的待翻译项。

三、php 与 php-inline：array_keys、base64 验证规则缺口

cs 语言包的 PHP 验证消息分为两种格式：

• php 格式（locales/cs/php.json）：消息中带:attribute占位符，用于在错误消息中插入字段名；
• php-inline 格式（locales/cs/php-inline.json）：直接面向单字段的内联消息，不含:attribute占位符。

这两种格式各自缺失相同的 2 个键：array_keys与base64。它们在两种格式下的英文原文如下：

这两个键对应 Laravel 验证器中相对较新的规则：

• array_keys：校验数组字段只能包含指定的一组键名，:values为允许的键列表；
• base64：校验字段值必须是合法的 Base64 编码字符串。

在 source/framework/12.x/validation.php 等框架验证规则定义中，可以找到同一批验证规则的完整结构（如accepted、array、in_array_keys等约 160 条规则），array_keys与base64即是在此基础上的新增规则。cs 语言包中大多数验证规则已完成翻译（例如 locales/cs/php.json 中"alpha_dash": ":Attribute může obsahovat pouze písmena, číslice, pomlčky a podtržítka. České znaky (á, é, í, ó, ú, ů, ž, š, č, ř, ď, ť, ň) nejsou podporovány."还针对捷克语字符做了细致说明），而这两个键仍保留英文，是典型的"新规则加入、翻译未跟上"的缺口。

四、补齐翻译的实操方法

4.1 翻译三个文件中的对应键

补齐流程非常简单：直接编辑 cs 语言包的三个 JSON 文件，将缺失键的值从英文替换为捷克语即可。以base64为例：

php 格式（locales/cs/php.json）：

{ "base64": "Pole :attribute musí být platný Base64 řetězec." }

php-inline 格式（locales/cs/php-inline.json）：

{ "base64": "Toto pole musí být platný Base64 řetězec." }

json 格式（locales/cs/json.json），以 Passkey 消息为例：

{ "Invalid credential format.": "Neplatný formát pověření." }

注意保持键名（英文原文）不变，只替换值；同时保留:attribute、:values等占位符，确保 Laravel 在渲染错误消息时能正确注入动态内容。翻译风格可参考文件中已完成的同类消息，例如 locales/cs/php.json 中的"integer": ":Attribute musí být celé číslo."等既有译法，以保持术语一致性。

4.2 理解文件结构：json、php、php-inline 的分工

在动手翻译前，建议先理解这三种格式在项目中的分工：

• json：面向界面 UI 组件（如 Nova、Jetstream 的前端文案）以及框架命令输出等场景，键为完整英文句子；
• php：返回lang/{locale}.php形式的一维数组，供后端验证器与页面渲染使用，消息带:attribute占位符；
• php-inline：同样是一维数组，但面向内联验证场景（表单字段逐项报错），不含:attribute。

仓库通过 src/Plugin.php 中的插件注册机制，将各扩展包（Breeze、Cashier、Fortify、Jetstream、Nova、Passkeys、Spark、UI 等）的语言文件统一打包分发，composer.json 中的laravel-lang/publisher负责将语言包发布到目标 Laravel 应用的lang/目录。

4.3 验证翻译是否生效

翻译完成后，可以通过项目的自动化脚本来校验与重新生成状态报告：

1. 运行语言同步命令：vendor/bin/lang sync（见 composer.json 中的format脚本），将新增/修改的翻译同步到各扩展包；
2. 状态报告由laravel-lang/status-generator自动生成，重新生成后 docs/statuses/cs.md 中的缺失数量应从 15 降为 0，缺失表格将完全消失；
3. 运行测试套件：vendor/bin/phpunit --colors=always（即 composer 的test脚本），确保语言包结构合法、无键冲突（测试位于 tests/PluginTest.php）。

需要注意的是，翻译是否被实际应用取决于你使用的 Laravel 版本：本项目要求php: ^8.2且与laravel/framework >= 11.0.7兼容（见 composer.json 的require与conflict声明），不同框架版本对应 source/framework 目录下的 11.x、12.x、13.x、master 等不同版本的语言文件。

五、小结：从状态报告反推本地化工作流

docs/statuses/cs.md 这类状态报告的价值在于：它以精确的键级粒度暴露了每个语言包的翻译缺口，让维护者可以按图索骥，快速定位"新增了什么功能但还没翻译"的模块。就 cs 语言包而言，15 个缺口的指向非常明确：

• 8 条 Passkeys 消息→ Laravel 无密码登录功能上线但捷克语翻译未跟上；
• 3 条环境文件加密命令消息→ 框架新增命令文案未同步；
• 4 条验证规则消息（array_keys、base64各 2 条）→ 新验证规则未本地化。

对于想要参与翻译贡献的开发者，最直接的入手方式就是对照本文第三、四节，补齐 locales/cs/json.json、locales/cs/php.json、locales/cs/php-inline.json 中的对应键，然后通过vendor/bin/lang sync同步并重新生成状态文档，即可让 docs/statuses/cs.md 从"All missed: 15"变为完全通过。

• 后端