# 翻译

Blockstudio 将翻译文件放在 `languages` 文件夹中。当站点语言或用户个人资料中的语言与其中一种语言匹配时，WordPress 就会使用相应翻译。无论 Blockstudio 作为插件、必需插件还是 Composer 软件包运行，工作方式都相同。

## 可用语言

Blockstudio 包含其随附 `languages/locales.json` 中记录的 WordPress 种语言区域设置的翻译，包括地区变体以及正式和非正式语体变体。英语（`en_US`）是源语言，无需翻译文件。该列表合并了 GlotPress 支持的 WordPress 语言区域设置，以及 WordPress 核心翻译 API 中提供的变体。

现有的德语（`de_DE`）和正式德语（`de_DE_formal`）翻译会予以保留。新增翻译由 GPT-6 Luna 生成，并在其 `.po` 标头中标记为机器生成。这些翻译通过了自动完整性和格式检查，但并非全部经过母语人士审校。欢迎提交修正。

这些翻译涵盖区块编辑器中的字段控件、管理页面、画布、开发工具叠加层，以及 REST 端点的消息。你自己的 `block.json` 文件中的标签和帮助文本属于你的主题或插件，并使用其文本域。

在 **设置 > 常规 > 站点语言** 中选择语言，或在你的 WordPress 个人资料中选择个人语言。Blockstudio 会自动使用该语言区域设置。它不会在 WordPress 语言选择器中添加语言：语言区域设置还必须在你的 WordPress 安装中可用。你的网站无需调用 AI、订阅翻译服务或额外设置运行时选项。

## 覆盖翻译

`wp-content/languages/plugins` 中的翻译文件优先于随附文件，适用于 PHP 字符串（`blockstudio-de_DE.mo` 或 `blockstudio-de_DE.l10n.php`），也适用于脚本（每个脚本句柄对应一个文件，例如 `blockstudio-de_DE-blockstudio-blocks.json`）。

## 参与翻译

每种语言都对应一个 `.po` 文件，你可以使用任何文本编辑器或 Poedit 等翻译工具编辑。欢迎通过拉取请求提交修正和新增语言。

1. 要添加语言，请将 `languages/blockstudio.pot` 复制到 `languages/blockstudio-<locale>.po`，例如 `blockstudio-fr_FR.po`，并设置 `Language` 和 `Plural-Forms` 标头。要改进某种语言，请编辑其现有的 `.po` 文件。
2. 翻译字符串。请在译文中保留 `%1$s` 等占位符。
3. 运行 `npm run i18n`。它会写入 `.mo`、`.l10n.php` 和 `.json` 文件，供 WordPress 加载。
4. 将 `.po` 文件与生成的文件一同提交，然后创建拉取请求。

如果你无法运行 `npm`，只提交包含 `.po` 文件的拉取请求也可以。生成的文件可以在合并前添加。

## 生成缺失的翻译

维护者可以使用已认证的 Codex CLI 生成缺失条目。这是可选的开发命令，WordPress 不会运行它：

```bash
npm run i18n:translate -- --dry-run
npm run i18n:translate
```

默认模型是 `gpt-6-luna`。要处理单个语言区域设置，请使用 `npm run i18n:translate -- --locale fr_FR`。该命令会提取最新源字符串、补齐缺失的翻译，然后编译 `.mo`、`.l10n.php` 和每个脚本对应的 `.json` 文件。发送给 Codex 的只有公开界面字符串、其上下文和现有译文，不包括站点内容或用户数据。

已有的非空译文绝不会被替换。已完成的批次会保存，因此中断后重新运行即可继续处理缺失内容。保存前会验证 `%1$s` 等占位符、HTML 标记、技术标识符和必需的复数形式。模糊条目和已更改的源复数形式会留待译者审阅。如果请求的模型不可用，则不会回退到其他模型。

`npm run i18n:locales` 会从 WordPress/GlotPress 显式刷新语言区域设置列表和复数规则。`npm run i18n:coverage` 会检查检入的列表中每种语言区域设置是否都已完整翻译。覆盖率检查和常规 CI 均不会调用 AI 或获取语言区域设置数据。批处理、并发和恢复选项请参阅代码库中的 README。

## 代码中的可翻译字符串

- PHP：使用 `blockstudio` 文本域中的 WordPress 函数，例如 `__( 'Invalid block.', 'blockstudio' )`。
- JavaScript：从 `@/utils/__` 导入 `__` 并传入字面字符串，例如 `__( 'Add row' )`。运行时拼接的字符串无法翻译，因此每个变体都要使用一个字面字符串。
- 包含可翻译字符串的新脚本包需要在 `scripts/i18n.ts` 中添加条目，并调用 `wp_set_script_translations()`，且使用相同的句柄和 `Translations::script_path()`。

更改字符串后，运行 `npm run i18n`。它会更新 `languages/blockstudio.pot` 和所有 `.po` 文件。新字符串在翻译人员或 `npm run i18n:translate` 填写之前会保持英文。CI 会运行 `npm run i18n:check` 和 `npm run i18n:coverage`，以拒绝过时的编译文件、提取问题或不完整的语言区域覆盖。生成操作仍由维护人员明确执行。