企业官网建设流程全解析

• 后端

本篇技术指南面向希望为 Laravel-Lang / lang 仓库贡献代码或翻译的开发者，系统讲解该仓库的运行时要求、安装与自动加载机制、Pint/Biome 代码风格工具链、PHPUnit 测试套件运行方式，以及从locales/en英文原文出发、经由docs/statuses状态文件驱动的完整翻译工作流。读完本文，你将能够独立完成环境配置、编写并运行测试、执行 locale 同步，以及按规范提交一份完整且通过状态校验的本地化翻译。

仓库定位与整体结构

Laravel-Lang / lang 是一个为 Laravel 框架及其官方一揽子组件（Laravel Framework、Jetstream、Fortify、Breeze、Cashier、Nova、Spark、UI 等）提供并维护多语言资源（language resources）的包。其核心产出是locales/目录下按语言代码组织的翻译产物，而source/目录保存用于生成/更新这些产物的数据源，自动化由 laravel-lang/publisher 及配套工具负责（见 composer.json 中require的laravel-lang/publisher）。

仓库顶层目录分工如下：

• src/—— 包运行时代码，包括 ServiceProvider 及运行时辅助逻辑；
• source/—— 生成翻译文件用的数据源（在理解生成管线前不要直接编辑生成产物）；
• locales/—— 按语言维护的翻译产物（如php-inline.json、json.json、_excludes.json），部分文件由机器维护，应通过 sync 工具更新；
• tests/—— 测试套件，目前包含依赖 status-generator 基础测试类的PluginTest；
• docs/—— 附加的项目/用户文档，其中docs/statuses/存放每个语言代码的翻译状态报告。

在src/Plugin.php中，插件通过继承LaravelLang\Publisher\Plugins\Provider声明了面向各组件（Breeze、Cashier/Stripe、Fortify、Jetstream、Laravel、Nova、Passkeys、Spark、UI）的 Master/版本化子插件列表，例如Plugins\Laravel\Master与Plugins\Laravel\V11/V12/V13，这些子插件定义了源文件到目标语言文件（如framework/master/framework.json→{locale}.json）的映射规则（见 src/Plugins/Laravel/Master.php）。

构建环境与安装

运行时要求

• PHP：^8.2。测试套件使用 PHPUnit^11.0 || ^12.0（见 composer.json 的require-dev）。低于 8.2 的 PHP 不受支持，这一点在 composer.json 的require段有硬性约束。
• PHP 扩展：ext-json。
• Composer 2.x。
• Node.js 为可选，仅当需要执行 Biome（JSON/JS 格式化）以及 npm 相关的代码风格任务时才需要。

安装步骤

按常规方式安装 PHP 与 Composer 后，在仓库根目录执行：

composer install

仓库自带composer.lock；若在 CI/CD 中希望加速安装，可附加--prefer-dist。若你打算在本地运行测试，请务必使用完整的composer install（不要加--no-dev），因为测试套件依赖 dev 依赖laravel-lang/status-generator提供的基础测试类。

自动加载与 Laravel 集成

• 生产代码：PSR-4 自动加载，命名空间LaravelLang\Lang\映射到src/（见 composer.json 的autoload段）。
• 测试代码：PSR-4 dev 自动加载，命名空间Tests\映射到tests/（autoload-dev段）。
• Laravel 集成：包在extra.laravel.providers中声明了LaravelLang\Lang\ServiceProvider，从而允许 Laravel 应用自动发现。该 ServiceProvider 在register()中检测LaravelLang\Publisher\Plugins\Provider类是否存在，存在时再注册Plugin（见 src/ServiceProvider.php），保证了与发布器组件的解耦。

工具链与代码风格

Composer 脚本

仓库在 composer.json 的scripts段定义了如下脚本：

• composer run format—— 依次执行vendor/bin/lang sync和@style（即 Pint）。从数据源同步 locale 文件时使用此命令。
• composer run style—— 执行vendor/bin/pint --parallel，应用 pint.json 中定义的 PHP 代码风格规则。
• post-update-cmd—— 在依赖更新后自动运行 codestyler 任务与composer normalize，一般无需直接调用。

Pint 规则（pint.json）

Pint 配置 采用laravel预设，并叠加若干项目专属规则，要点包括：

• declare_strict_types：PHP 文件顶部应包含declare(strict_types=1);；
• fully_qualified_strict_types：统一导入并使用完全限定类名（FQCN）；
• php_unit_method_casing = camel_case：测试方法必须使用 camelCase 命名；
• binary_operator_spaces：默认align_single_space_minimal（对齐最小化）；
• 引入多套 PHP 迁移规则集（@PHP7x1Migration、@PHP7x3Migration、@PHP7x4Migration、@PHP8x0Migration、@PHP8x1Migration、@PHP8x2Migration）；
• 面向可读性的 phpdoc 与空行规则（blank_line_before_statement针对declare/phpdoc/continue/return）；
• 类布局与类型排序偏好（class_attributes_separation、class_definition、ordered_types等）；
• exclude排除了tests/Fixtures，该目录不做风格检查。

Biome 配置（biome.json）

Biome 配置 用于vendor/、node_modules/之外的 JSON/JS 格式化与 lint：

• VCS 集成被禁用（vcs.enabled = false、useIgnoreFile = false），因此默认不会遵循.gitignore；
• files.includes显式排除了node_modules、vendor以及若干根目录文件（如composer.json、composer.lock、package.json、package-lock.json等）；
• 格式化采用 4 空格缩进；JS 使用双引号（quoteStyle: "double"）；JSON 格式化开启bracketSpacing与expand: "always"。

格式化命令示例：

npx @biomejs/biome format .

测试：配置、运行与编写

PHPUnit 配置

phpunit.xml 位于仓库根目录：

• Bootstrap：vendor/autoload.php；
• 环境变量：APP_KEY已在 phpunit.xml 中预设（值为AckfSECXIvnK5r28GVIWUAxmbBSjTsmF），测试时通常无需自行导出环境变量；
• 测试套件目录：./tests；
• 覆盖率/解析来源包含./src。

运行测试

运行完整测试套件（带测试名输出）：

# *nix vendor/bin/phpunit -c phpunit.xml --testdox # Windows PowerShell（注意反斜杠路径） vendor\bin\phpunit -c phpunit.xml --testdox

按类名或测试名过滤（适合快速反馈）：

vendor/bin/phpunit -c phpunit.xml --filter PluginTest --testdox

说明：Windows PowerShell 下路径使用反斜杠，*nix 下使用正斜杠。该指南验证记录显示，全套测试在 PHP 8.4 与 PHPUnit 12 环境下（Windows）执行成功。

添加测试

测试文件置于tests/下，命名空间为Tests，由 composer.json 的autoload-dev自动加载。基础测试类有两种选择：

1. 仓库内部、与框架无关的检查：直接继承PHPUnit\Framework\TestCase；
2. 与 locale/status 基础设施集成的测试：继承LaravelLang\StatusGeneratorTests\TestCase（参见 tests/PluginTest.php，其通过protected string $base_path = __DIR__ . '/../'指向仓库根），以复用 status-generator 包提供的助手与 fixtures。

命名与风格约定：

• 测试方法使用 camelCase（由 Pint 规则php_unit_method_casing=camel_case强制）；
• 测试文件顶部声明严格类型declare(strict_types=1);。

最小示例（仅依赖 PHPUnit）：

<?php declare(strict_types=1); namespace Tests; use PHPUnit\Framework\TestCase; final class DemoExampleTest extends TestCase { public function test_it_runs_a_trivial_assertion(): void { $this->assertSame(2, 1 + 1); } }

仅运行该测试：

vendor/bin/phpunit -c phpunit.xml --filter DemoExampleTest --testdox

（该示例在编写本指南时被创建并执行验证，随后已删除以保持仓库整洁。）

本地化文件同步与格式化

locales/下的翻译产物属于生成/维护型文件，不应脱离生成管线手工编辑。更新翻译数据的推荐流程是：

composer run format

该命令会先执行vendor/bin/lang sync从source/同步 locale 文件，再经由style脚本应用 Pint 保持代码风格一致。对翻译数据做出改动后，始终运行composer run style以确保风格统一。若修改了 JSON/JS 配置或 locale JSON，还需运行 Biome 规范化格式。

本地化翻译规则

本仓库的翻译工作遵循一套严格的规则（见指南 "Localization translation rules" 一节），核心原则如下：

• 按 ISO-639-1 语言代码翻译：目标语言由locales/下的文件夹名决定，翻译成与该 locale 代码对应的语言；
• 不翻译以_开头的文件（如_excludes.json、_not_translatable.json）；
• key 本身保持不译，即使 key 看起来像句子；
• 若译文与英文原值完全相同，将该值加入_excludes.json；
• 以:占位符开头的句子，译文以大写字母开头，例如":Attribute est déjà attaché(e)."；
• 考虑使用上下文：这些值会展示在网站页面的选择字段、信息通知、UI 元素等处；
• 翻译完成后，将修改过的 JSON 文件内容按字母序排序；
• 翻译后不运行单元测试和/或代码风格检查；
• 严格遵循当前英文措辞，保留占位符（如:attribute、:value等）。

inline 与普通文件之别

*-inline.json与其他文件的区别在于：它们提供的译文不提及属性或字段名。例如：

• *.json：
  • The :attribute field must only contain letters.
  • The :attribute field must have :value items or more.
• *-inline.json：
  • The value must only contain letters.
  • This field must contain :value items or more.

参考原文与状态文件

翻译时以locales/en/下的英文文件为原文参照（见 locales/en），按文件类型一一对应：

• locales/*/json.json↔locales/en/json.json
• locales/*/json-inline.json↔locales/en/json-inline.json
• locales/*/php.json↔locales/en/php.json
• locales/*/php-inline.json↔locales/en/php-inline.json

只翻译以英文书写的短语；此前已翻译的短语无需重述（除非另有说明）。所有指定文件应在同一个提交中完成翻译。

各语言尚未翻译的单词与短语清单位于docs/statuses/文件夹，文件名与locales/中的语言代码一一对应（如 docs/statuses/zh_CN.md）。每个文件内部是一个 HTML 表格：第一列为 JSON 文件中的 key 名，第二列为待翻译的值。

如何翻译词汇和短语

注意：最重要的一条规则是——不要删除文件中的 key。

完整的翻译操作流程如下：

1. 打开docs/statuses中对应语言代码的文件，仔细研读；
2. 在待翻译的本地化 JSON 文件中定位这些短语；
3. 翻译单词与短语，写回它们原先所在的 JSON 文件位置；
4. 运行控制台命令更新翻译状态（必须执行）：

vendor/bin/lang sync && vendor/bin/lang status

5. 根据命令输出，检查docs/statuses下该语言 Markdown 文件的内容；
6. 若 Markdown 文件包含All missed: 0，则翻译工作完成；否则继续翻译文件中列出的短语，并从第 2 步起重复。

例如 docs/statuses/zh_CN.md 当前显示All missed: 7，其中json部分缺失 3 条（如The existing encrypted environment file is not in readable format. Use --force to overwrite it.等），这些条目正是下一步需要补齐翻译的目标。

常见陷阱与提交卫生

• 确保 PHP >= 8.2，旧版本 PHP 不受支持（见 composer.jsonrequire段）；
• 本地运行测试前必须安装 dev 依赖（composer install不加--no-dev），否则laravel-lang/status-generator的基础测试类不可用；
• 部分目录/文件是生成的，除非清楚生成流程，否则避免手工编辑 locale 生成文件；优先更新source/数据并运行composer run format；
• 提交前保持 diff 最小，运行composer run style以满足 Pint 规则；
• 若修改 JSON/JS 配置或 locale JSON，运行 Biome 规范化格式；
• 若向 upstream 贡献，遵循 conventional commit 约定。

通过遵循上述环境搭建、测试、同步与翻译规则，贡献者可以高效地为 128 种语言的 Laravel 生态翻译资源库提交高质量改动，并确保每次翻译都通过lang status的完整性校验。

• 后端