@intlayer/docs 8.9.4-canary.0 → 8.9.4

package/docs/zh/plugins/sync-po.md

@@ -0,0 +1,354 @@
+---
+createdAt: 2026-05-10
+updatedAt: 2026-05-10
+title: Sync PO 插件
+description: 将 Intlayer 字典与 Gettext PO 文件同步。在使用 Intlayer 管理、翻译和测试消息的同时，保留现有的 i18n。
+keywords:
+  - Intlayer
+  - Sync PO
+  - Gettext
+  - i18n
+  - 翻译
+slugs:
+  - doc
+  - plugin
+  - sync-po
+youtubeVideo: https://www.youtube.com/watch?v=MpGMxniDHNg
+history:
+  - version: 8.9.4
+    date: 2026-05-10
+    changes: "初始 Sync PO 插件文档"
+---
+
+# Sync PO (i18n 桥接) - 支持 ICU / i18next 的 Sync PO
+
+将 Intlayer 作为现有 i18n 栈的补充。此插件使您的 Gettext PO 消息与 Intlayer 字典保持同步，以便您可以：
+
+- 保留现有的基于 PO 的翻译工作流。
+- 使用 Intlayer (CLI、CI、供应商、CMS) 管理和翻译您的消息，无需重构您的应用。
+- 发布针对各生态系统的教程和 SEO 内容，同时建议将 Intlayer 作为 PO 管理层。
+
+注意事项和当前范围：
+
+- 外部化到 CMS 适用于翻译和经典文本。
+- 尚不支持 PO 条目内部的插值、复数/ICU 或其他库的高级运行时功能。
+- 可视化编辑器尚不支持第三方 i18n 输出。
+
+### 何时使用此插件
+
+- 您已经在使用 Gettext PO 文件进行翻译。
+- 您希望在不更改渲染运行时的情况下，获得 AI 辅助填充、CI 测试和内容运营。
+
+## 安装
+
+```bash
+pnpm add -D @intlayer/sync-po-plugin
+# 或
+npm i -D @intlayer/sync-po-plugin
+```
+
+## 插件
+
+此包提供两个插件：
+
+- `loadPO`：将 PO 文件加载到 Intlayer 字典中。
+  - 此插件用于从源加载 PO 文件并将其载入 Intlayer 字典。它可以扫描整个代码库并搜索特定的 PO 文件。
+    此插件可用于：
+    - 如果您使用的 i18n 库强制要求 PO 文件的加载位置，但您希望将内容声明放在代码库中您喜欢的位置。
+    - 它也可以用于从远程源（如 CMS、API 等）获取消息并将消息存储在 PO 文件中。
+
+  > 在底层，此插件将扫描整个代码库并搜索特定的 PO 文件，并将其加载到 Intlayer 字典中。
+  > 请注意，此插件不会将输出和翻译写回 PO 文件。
+
+- `syncPO`：将 PO 文件与 Intlayer 字典同步。
+  - 此插件用于将 PO 文件与 Intlayer 字典同步。它可以扫描给定位置并加载与特定 PO 文件模式匹配的 PO。如果您想在使用另一个 i18n 库的同时获得 Intlayer 的优势，此插件非常有用。
+
+## 同时使用两个插件
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+import { loadPO, syncPO } from "@intlayer/sync-po-plugin";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+
+  // 使当前的 PO 文件与 Intlayer 字典保持同步
+  plugins: [
+    /**
+     * 将加载 src 中匹配 {key}.i18n.po 模式的所有 PO 文件
+     */
+    loadPO({
+      source: ({ key }) => `./src/**/${key}.i18n.po`,
+      locale: Locales.ENGLISH,
+      priority: 1, // 确保这些 PO 文件优先于 `./locales/en/${key}.po` 处的文件
+    }),
+    /**
+     * 将加载输出和翻译并将其写回 locales 目录中的 PO 文件
+     */
+    syncPO({
+      source: ({ key, locale }) => `./locales/${locale}/${key}.po`,
+      priority: 0,
+    }),
+  ],
+};
+
+export default config;
+```
+
+## `syncPO` 插件
+
+### 快速开始
+
+将插件添加到您的 `intlayer.config.ts` 并指向您现有的 PO 结构。
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+import { syncPO } from "@intlayer/sync-po-plugin";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+
+  // 使当前的 PO 文件与 Intlayer 字典保持同步
+  plugins: [
+    syncPO({
+      // 每个语言、每个命名空间的布局
+      source: ({ key, locale }) => `./locales/${locale}/${key}.po`,
+    }),
+  ],
+};
+
+export default config;
+```
+
+备选方案：每个语言一个文件：
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+import { syncPO } from "@intlayer/sync-po-plugin";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH],
+    defaultLocale: Locales.ENGLISH,
+  },
+  plugins: [
+    syncPO({
+      source: ({ locale }) => `./locales/${locale}.po`,
+    }),
+  ],
+};
+
+export default config;
+```
+
+#### 工作原理
+
+- 读取：插件从您的 `source` 构建器发现 PO 文件并将其作为 Intlayer 字典加载。
+- 写入：构建和填充后，它将本地化的 PO 写回相同的路径（带有正确的 Gettext 头）。
+- 自动填充：插件为每个字典声明一个 `autoFill` 路径。默认情况下，运行 `intlayer fill` 仅更新 PO 文件中缺失的翻译。
+
+API：
+
+```ts
+syncPO({
+  source: ({ key, locale }) => string, // 必填
+  location?: string, // 可选标签，默认："sync-po::path/to/source"
+  priority?: number, // 用于冲突解决的可选优先级，默认：0
+  format?: 'icu' | 'i18next' | 'vue-i18n', // 可选，仅当您的 msgstr 值使用特定插值语法时才需要
+});
+```
+
+#### `format` ('icu' | 'i18next' | 'vue-i18n')
+
+PO 文件始终是 Gettext Portable Object 文件 —— 这是固定的。此选项仅描述 `msgstr` 值内部使用的 **插值语法**，以便 Intlayer 可以在解析时（通过 `formatDictionary`）将其转换为自己的格式，并在写入输出时转换回来。
+
+- `undefined` _（默认）_：`msgstr` 值被视为普通字符串 —— 不进行转换。大多数 PO 文件使用此选项。
+- `'icu'`：`msgstr` 值使用 ICU 消息语法（例如 `{count, plural, one {# item} other {# items}}`）。
+- `'i18next'`：`msgstr` 值使用 i18next 插值语法（例如 `{{variable}}`）。
+- `'vue-i18n'`：`msgstr` 值使用 Vue I18n 语法。
+
+> 转换由 `@intlayer/chokidar` 的 `formatDictionary` 在加载时应用，并在写入时通过 `formatDictionaryOutput` 反转。对于像 ICU 复数这样的复杂规则，不保证往返的保真度。
+
+**示例 —— PO 文件包含 i18next 风格的插值：**
+
+```ts
+syncPO({
+  source: ({ key, locale }) => `./locales/${locale}/${key}.po`,
+  format: "i18next",
+}),
+```
+
+### 多个 PO 源和优先级
+
+您可以添加多个 `syncPO` 插件来同步不同的 PO 源。当您的项目中有多个翻译源或不同的 PO 结构时，这很有用。
+
+#### 优先级系统
+
+当多个插件针对同一个字典键时，`priority` 参数决定哪个插件优先：
+
+- 高优先级数字胜过低优先级数字
+- `.content` 文件的默认优先级为 `0`
+- 插件的默认优先级为 `0`
+- 具有相同优先级的插件按照它们在配置中出现的顺序进行处理
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+import { syncPO } from "@intlayer/sync-po-plugin";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH],
+    defaultLocale: Locales.ENGLISH,
+  },
+
+  plugins: [
+    // 主要 PO 源（最高优先级）
+    syncPO({
+      source: ({ key, locale }) => `./locales/${locale}/${key}.po`,
+      location: "main-translations",
+      priority: 10,
+    }),
+
+    // 后备 PO 源（较低优先级）
+    syncPO({
+      source: ({ locale }) => `./fallback-locales/${locale}.po`,
+      location: "fallback-translations",
+      priority: 5,
+    }),
+
+    // 遗留 PO 源（最低优先级）
+    syncPO({
+      source: ({ locale }) => `/my/other/app/legacy/${locale}/messages.po`,
+      location: "legacy-translations",
+      priority: 1,
+    }),
+  ],
+};
+
+export default config;
+```
+
+## Load PO 插件
+
+### 快速开始
+
+将插件添加到您的 `intlayer.config.ts` 以将现有的 PO 文件作为 Intlayer 字典摄取。此插件是只读的（不会写入磁盘）：
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+import { loadPO } from "@intlayer/sync-po-plugin";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+
+  plugins: [
+    // 摄取位于源树中任何位置的 PO 消息
+    loadPO({
+      source: ({ key }) => `./src/**/${key}.i18n.po`,
+      // 每个插件实例加载一个语言（默认为配置的 defaultLocale）
+      locale: Locales.ENGLISH,
+      priority: 0,
+    }),
+  ],
+};
+
+export default config;
+```
+
+备选方案：按语言布局，仍然是只读的（仅加载选定的语言）：
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+import { loadPO } from "@intlayer/sync-po-plugin";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH],
+    defaultLocale: Locales.ENGLISH,
+  },
+  plugins: [
+    loadPO({
+      // 只有 Locales.FRENCH 的文件将从此模式加载
+      source: ({ key, locale }) => `./locales/${locale}/${key}.po`,
+      locale: Locales.FRENCH,
+    }),
+  ],
+};
+
+export default config;
+```
+
+### 工作原理
+
+- 发现：从您的 `source` 构建器构建一个 glob 并收集匹配的 PO 文件。
+- 摄取：使用提供的 `locale` 将每个 PO 文件加载为 Intlayer 字典。
+- 只读：不写入或格式化输出文件；如果您需要双向同步，请使用 `syncPO`。
+- 自动填充准备：定义一个 `fill` 路径，以便 `intlayer content fill` 可以填充缺失的键。
+
+### API
+
+```ts
+loadPO({
+  // 构建指向您的 PO 的路径。如果您的结构没有语言段，则 `locale` 是可选的
+  source: ({ key, locale }) => string,
+
+  // 由此插件实例加载的字典的目标语言
+  // 默认为 configuration.internationalization.defaultLocale
+  locale?: Locale,
+
+  // 用于识别源的可选标签
+  location?: string, // 默认："plugin"
+
+  // 用于与其他源进行冲突解决的优先级
+  priority?: number, // 默认：0
+});
+```
+
+### 行为和约定
+
+- 如果您的 `source` 掩码包含语言占位符，则仅摄取所选 `locale` 的文件。
+- 如果掩码中没有 `{key}` 段，则字典键为 "index"。
+- 键通过替换 `source` 构建器中的 `{key}` 占位符从文件路径派生。
+- 插件仅使用发现的文件，不会伪造缺失的语言或键。
+- `fill` 路径从您的 `source` 推导出来，并在您选择启用时用于通过 CLI 更新缺失的值。
+
+## 冲突解决
+
+当多个 PO 源中存在相同的翻译键时：
+
+1. 具有最高优先级的插件决定最终值
+2. 较低优先级的源用作缺失键的后备
+3. 这允许您保留遗留翻译，同时逐步迁移到新结构
+
+## CLI
+
+同步的 PO 文件将被视为与其他 `.content` 文件相同。这意味着，所有 intlayer 命令都将可用于同步的 PO 文件。包括：
+
+- `intlayer content test` 测试是否有缺失的翻译
+- `intlayer content list` 列出同步的 PO 文件
+- `intlayer content fill` 填充缺失的翻译
+- `intlayer content push` 推送同步的 PO 文件
+- `intlayer content pull` 拉取同步的 PO 文件
+
+有关更多详细信息，请参阅 [Intlayer CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/cli/index.md)。
+
+## 局限性（当前）
+
+- 针对第三方库时不支持插值或复数/ICU。
+- 可视化编辑器尚不适用于非 Intlayer 运行时。
+- 仅限 PO 同步；不支持非 PO 目录格式。
+
+## 为什么这很重要
+
+- 我们可以推荐成熟的 i18n 解决方案，并将 Intlayer 定位为补充。
+- 我们通过教程利用他们的 SEO/关键词，教程最后建议使用 Intlayer 来管理 PO。
+- 将目标受众从“新项目”扩展到“任何已经在使用 i18n 的团队”。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intlayer/docs",
-  "version": "8.9.4-canary.0",
+  "version": "8.9.4",
   "private": false,
   "description": "Intlayer documentation",
   "keywords": [
@@ -72,13 +72,13 @@
     "watch": "webpack --config ./webpack.config.ts --watch"
   },
   "dependencies": {
-    "@intlayer/config": "8.9.4-canary.0",
-    "@intlayer/core": "8.9.4-canary.0",
-    "@intlayer/types": "8.9.4-canary.0"
+    "@intlayer/config": "8.9.4",
+    "@intlayer/core": "8.9.4",
+    "@intlayer/types": "8.9.4"
   },
   "devDependencies": {
-    "@intlayer/api": "8.9.4-canary.0",
-    "@intlayer/cli": "8.9.4-canary.0",
+    "@intlayer/api": "8.9.4",
+    "@intlayer/cli": "8.9.4",
     "@types/node": "25.6.2",
     "@utils/ts-config": "1.0.4",
     "@utils/ts-config-types": "1.0.4",

package/src/generated/docs.entry.ts

@@ -3316,6 +3316,26 @@ export const docsEntry = {
     vi: readLocale('plugins/sync-json.md', 'vi'),
     uk: readLocale('plugins/sync-json.md', 'uk'),
   } as unknown as Record<LocalesValues, Promise<string>>,
+  './docs/en/plugins/sync-po.md': {
+    en: readLocale('plugins/sync-po.md', 'en'),
+    ru: readLocale('plugins/sync-po.md', 'ru'),
+    ja: readLocale('plugins/sync-po.md', 'ja'),
+    fr: readLocale('plugins/sync-po.md', 'fr'),
+    ko: readLocale('plugins/sync-po.md', 'ko'),
+    zh: readLocale('plugins/sync-po.md', 'zh'),
+    es: readLocale('plugins/sync-po.md', 'es'),
+    de: readLocale('plugins/sync-po.md', 'de'),
+    ar: readLocale('plugins/sync-po.md', 'ar'),
+    it: readLocale('plugins/sync-po.md', 'it'),
+    'en-GB': readLocale('plugins/sync-po.md', 'en-GB'),
+    pt: readLocale('plugins/sync-po.md', 'pt'),
+    hi: readLocale('plugins/sync-po.md', 'hi'),
+    tr: readLocale('plugins/sync-po.md', 'tr'),
+    pl: readLocale('plugins/sync-po.md', 'pl'),
+    id: readLocale('plugins/sync-po.md', 'id'),
+    vi: readLocale('plugins/sync-po.md', 'vi'),
+    uk: readLocale('plugins/sync-po.md', 'uk'),
+  } as unknown as Record<LocalesValues, Promise<string>>,
   './docs/en/readme.md': {
     en: readLocale('readme.md', 'en'),
     ru: readLocale('readme.md', 'ru'),