Intlayer 编译器 | 用于 i18n 的自动内容提取

什么是 Intlayer 编译器？

Intlayer 编译器 是一个强大的工具，旨在自动化您应用程序中的国际化（i18n）流程。它会扫描您的源代码（JSX、TSX、Vue、Svelte）中的内容声明，提取它们，并自动生成所需的字典文件。这使您能够将内容与组件放置在一起，而 Intlayer 则负责管理和同步您的字典。

为什么使用 Intlayer 编译器？

• 自动化: 消除了手动将内容复制粘贴到字典中的需要。

• Speed: 优化的内容提取，确保您的构建过程保持快速。

• 自动化：消除手动将内容复制粘贴到字典中的步骤。
• 速度：优化的内容提取，确保构建过程保持快速。
• 开发者体验：将内容声明保留在使用它们的位置，提高可维护性。

• 实时更新：支持热模块替换（HMR），在开发过程中即时反馈。

• Live Updates: 支持 Hot Module Replacement (HMR)，在开发过程中提供即时反馈。

请参阅Compiler vs. Declarative i18n博客文章，了解更深入的比较。

为什么不使用 Intlayer 编译器？

编译器虽然提供了一个优秀的"开箱即用"的体验，但它也引入了一些你应该了解的权衡：

虽然编译器提供了出色的"开箱即用"体验，但它也引入了一些您应该了解的权衡：

• 启发式歧义：编译器必须猜测什么是面向用户的内容，什么是应用程序逻辑（例如，className="active"、状态代码、产品 ID）。在复杂的代码库中，这可能导致误报或遗漏的字符串，需要手动注释和异常处理。
• 仅静态提取：基于编译器的提取依赖于静态分析。仅在运行时存在的字符串（API 错误代码、CMS 字段等）无法被编译器单独发现或翻译，因此您仍然需要补充的运行时 i18n 策略。

有关更深入的架构比较，请参阅博客文章Compiler vs. Declarative i18n。

作为替代方案，为了在保持对内容的完全控制的同时自动化您的 i18n 流程，Intlayer 还提供了自动提取命令 intlayer extract（请参阅CLI 文档），或 Intlayer VS Code 扩展的 Intlayer: extract content to Dictionary 命令（请参阅VS Code 扩展文档）。

使用方法

The quickest way to wire the compiler in is the interactive setup: run npx intlayer init --interactive and select Compiler. On Vite there is nothing to configure — the compiler is plugged in directly through the intlayerCompiler() plugin. On Next.js the command scaffolds the babel.config.js shown below. The non-interactive intlayer init leaves the compiler setup untouched.

npm install vite-intlayer

import { defineConfig } from "vite";
import { intlayer } from "vite-intlayer";

export default defineConfig({
  plugins: [
    intlayer({
      proxy: {
        ignore: (req) => req.url?.startsWith("/api"),
      },
    }),
  ],
});

# Vue 使用
npm install @intlayer/vue-compiler

# Svelte 使用
npm install @intlayer/svelte-compiler

npm install @intlayer/babel

const {
  intlayerExtractBabelPlugin,
  intlayerOptimizeBabelPlugin,
  getExtractPluginOptions,
  getOptimizePluginOptions,
} = require("@intlayer/babel");

module.exports = {
  presets: ["next/babel"],
  plugins: [
    // 从组件提取内容到字典
    [intlayerExtractBabelPlugin, getExtractPluginOptions()],
    // 通过将 useIntlayer 替换为直接字典导入来优化导入
    [intlayerOptimizeBabelPlugin, getOptimizePluginOptions()],
  ],
};

自定义配置

要自定义编译器的行为，您可以更新项目根目录中的 intlayer.config.ts 文件。

import { type IntlayerConfig, Locales } from "intlayer";

const config: IntlayerConfig = {
  compiler: {
    /**
     * 指示是否应启用编译器。
     * 设置为 “build-only” 以在开发期间跳过编译器并加快启动速度。
     */
    enabled: true,

    /**
     * 定义输出文件路径。替换 `outputDir`。
     *
     * - 以 `./` 开头的路径相对于组件目录解析。
     * - 以 `/` 开头的路径相对于项目根目录 (`baseDir`) 解析。
     *
     * - 在路径中包含 `{{locale}}` 变量将启用按语言分离开的字典生成。
     *
     * 示例：
     * ```ts
     * {
     *   // 在组件旁边创建多语言 .content.ts 文件
     *   output: ({ fileName, extension }) => `./${fileName}${extension}`,
     *
     *   // output: './{{fileName}}{{extension}}', // 使用字符串模板的等效写法
     * }
     * ```
     *
     * ```ts
     * {
     *   // 在项目根目录下创建按语言集中的 JSON 文件
     *   output: ({ key, locale }) => `/locales/${locale}/${key}.content.json`,
     *
     *   // output: '/locales/{{locale}}/{{key}}.content.json', // 使用字符串模板的等效写法
     * }
     * ```
     *
     * 变量列表：
     *   - `fileName`: 文件名。
     *   - `key`: 内容键。
     *   - `locale`: 内容语言。
     *   - `extension`: 文件扩展名。
     *   - `componentFileName`: 组件文件名。
     *   - `componentExtension`: 组件文件扩展名。
     *   - `format`: 字典格式。
     *   - `componentFormat`: 组件字典格式。
     *   - `componentDirPath`: 组件目录路径。
     */
    output: ({ fileName, extension }) => `./${fileName}${extension}`,

    /**
     * 指示在转换后是否应保存组件。
     *
     * - 如果为 `true`，编译器将重写磁盘中的组件文件。因此转换将是永久性的，编译器将跳过下一次进程的转换。这样，编译器可以在转换应用后被移除。
     *
     * - 如果为 `false`，编译器仅在构建输出中将 `useIntlayer()` 函数调用注入代码中，并保持基础代码库不变。转换将仅在内存中进行。
     */
    saveComponents: false,

    /**
     * 仅在生成的文件中插入内容。对于每种语言的 i18next 或 ICU MessageFormat JSON 输出非常有用。
     *
     * - `output: ({ locale, key }) => `./locale/${locale}/${key}.json`,`
     */
    noMetadata: false,

    /**
     * 字典键前缀
     */
    dictionaryKeyPrefix: "", // 为提取的字典键添加可选前缀
  },
};

export default config;

编译器配置参考

可以在 intlayer.config.ts 文件的 compiler 块中配置以下属性：

• enabled:

  • 类型: boolean | 'build-only'
  • 默认值: true
  • 描述: 指示是否应启用编译器。

• dictionaryKeyPrefix:

  • 类型: string
  • 默认值: ''
  • 描述: 提取的字典键的前缀。

• transformPattern:

  • 类型: string | string[]
  • 默认值: ['**/*.{js,ts,mjs,cjs,jsx,tsx,vue,svelte}', '!**/node_modules/**']
  • 描述: (已弃用：请改为使用 build.traversePattern) 遍历代码进行优化的模式。

• excludePattern:

  • 类型: string | string[]
  • 默认值: ['**/node_modules/**']
  • 描述: (已弃用：请改为使用 build.traversePattern) 优化中排除的模式。

• output:

  • 类型: FilePathPattern
  • 默认值: ({ key }) => 'compiler/${key}.content.json'
  • 描述: 定义输出文件路径。替换 outputDir。处理动态变量，如 {{locale}}、{{key}}、{{fileName}}、{{extension}}、{{format}}、{{dirPath}}、{{componentFileName}}、{{componentExtension}}、{{componentFormat}}。可以设置为字符串（使用 'my/{{var}}/path' 格式）或函数。
  • 注意: ./**/* 路径相对于组件解析。/**/* 路径相对于 Intlayer 的 baseDir 解析。
  • 注意: 如果路径中定义了语言，字典将按语言生成。
  • 示例: output: ({ locale, key }) => 'compiler/${locale}/${key}.json'

• noMetadata:

  • 类型: boolean
  • 默认值: false
  • 描述: 指示是否应在文件中保存元数据。如果为 true，编译器将不会保存字典的元数据（键、内容包装器）。
  • 注意: 如果与 loadJSON 插件一起使用，则非常有用。
  • 示例: 如果为 true： json { "key": "value" } 如果为 false： json { "key": "value", "content": { "key": "value" } }

• saveComponents:

  • 类型: boolean
  • 默认值: false
  • 描述: 指示在转换后是否应保存组件。
    • 如果为 true，编译器将重写磁盘中的组件文件。转换将是永久性的，编译器随后可以被移除。
    • 如果为 false，编译器仅在构建输出中将 useIntlayer() 函数调用注入代码中，并保持基础代码库不变。转换将仅在内存中进行。

填充缺失的翻译

Intlayer 提供了一个 CLI 工具来帮助您填充缺失的翻译。您可以使用 intlayer 命令来测试并从代码中填充缺失的翻译。

npx intlayer test         # 测试是否存在缺失的翻译

npx intlayer fill         # 填充缺失的翻译

提取

Intlayer 提供了一个 CLI 工具来从您的代码中提取内容。您可以使用 intlayer extract 命令从代码中提取内容。

npx intlayer extract

有关更多详细信息，请参阅 CLI 文档