接收有关即将发布的Intlayer的通知
    Creation:2024-08-13Last update:2025-09-16

    Intlayer 配置文档

    概述

    Intlayer 配置文件允许自定义插件的各个方面，例如国际化、中间件和内容处理。本文档详细描述了配置中的每个属性。

    配置文件支持

    Intlayer 支持 JSON、JS、MJS 和 TS 配置文件格式：

    • intlayer.config.ts
    • intlayer.config.js
    • intlayer.config.json
    • intlayer.config.cjs
    • intlayer.config.mjs
    • .intlayerrc

    示例配置文件

    intlayer.config.ts
    import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [Locales.ENGLISH], // 支持的语言列表  },  content: {    autoFill: "./{{fileName}}.content.json", // 自动填充内容文件路径模板    contentDir: ["src", "../ui-library"], // 内容目录  },  middleware: {    noPrefix: false, // 是否禁用前缀  },  editor: {    applicationURL: "https://example.com", // 编辑器应用程序 URL  },  ai: {    apiKey: process.env.OPENAI_API_KEY, // AI 接口密钥    applicationContext: "This is a test application", // 应用上下文描述  },  build: {    importMode: "dynamic", // 构建时的导入模式  },};export default config;

    配置参考

    以下部分描述了 Intlayer 可用的各种配置设置。

    国际化配置

    定义与国际化相关的设置，包括可用的语言环境和应用的默认语言环境。

    属性

    • locales：

      • 类型：string[]
      • 默认值：['en']
      • 描述：应用中支持的语言环境列表。
      • 示例：['en', 'fr', 'es']
    • requiredLocales：
      • 类型：string[]
      • 默认值：[]
      • 描述：应用中必需的语言环境列表。
      • 示例：[]
      • 注意：如果为空，则在 strict 模式下所有语言环境都是必需的。
      • 注意：确保必需的语言环境也在 locales 字段中定义。

    • strictMode：

      • 类型：string
      • 默认值：inclusive
      • 描述：确保使用 TypeScript 强化国际化内容的实现。
      • 注意：如果设置为 "strict"，翻译函数 t 将要求每个声明的语言环境都必须定义。如果缺少某个语言环境，或者配置中未声明某个语言环境，将抛出错误。
      • 注意：如果设置为 "inclusive"，翻译函数 t 将要求每个声明的语言环境都必须定义。如果缺少某个语言环境，将发出警告。但如果配置中未声明某个语言环境但该语言环境存在，则接受。
      • 注意: 如果设置为 "loose"，翻译函数 t 将接受任何存在的语言环境。

    • defaultLocale:

      • 类型: string
      • 默认值: 'en'
      • 描述: 当请求的语言环境未找到时，使用的默认语言环境作为回退。
      • 示例: 'en'
      • 注意: 用于在 URL、cookie 或请求头中未指定语言环境时确定语言环境。

    编辑器配置

    定义与集成编辑器相关的设置，包括服务器端口和激活状态。

    属性

    • applicationURL:
      • 类型: string
      • 默认值: http://localhost:3000
      • 描述: 应用程序的 URL。用于出于安全原因限制编辑器的来源。
      • 示例:
        • 'http://localhost:3000'
        • 'https://example.com'

    • process.env.INTLAYER_EDITOR_URL

      • 注意: 应用程序的 URL。用于出于安全原因限制编辑器的来源。如果设置为 '*'，则编辑器可从任何来源访问。

    • port:

      • 类型: number
      • 默认值: 8000
      • 描述: 可视化编辑器服务器使用的端口。

    • editorURL:

      • 类型: string
      • 默认值: 'http://localhost:8000'
      • 描述: 编辑器服务器的 URL。用于出于安全原因限制编辑器的来源。
        • 'http://localhost:3000'
        • 'https://example.com'
        • process.env.INTLAYER_EDITOR_URL
      • 注意：应用程序访问的编辑器服务器的 URL。用于限制可以与应用程序交互的来源以确保安全。如果设置为 '*'，编辑器可以从任何来源访问。如果端口更改或编辑器托管在不同域名上，应设置此项。

    • cmsURL：

      • 类型：string
      • 默认值：'https://intlayer.org'
      • 描述：Intlayer CMS 的 URL。
      • 示例：'https://intlayer.org'
      • 注意：Intlayer CMS 的 URL。

    • backendURL：

      • 类型：string
      • 默认值：https://back.intlayer.org
      • 描述：后端服务器的 URL。
      • 示例：http://localhost:4000

    • enabled：

      • 类型：boolean
      • 默认值：true
      • 描述：指示应用程序是否与可视化编辑器交互。
      • 示例：process.env.NODE_ENV !== 'production'
      • 注意：如果为 true，编辑器将能够与应用程序交互。如果为 false，编辑器将无法与应用程序交互。无论如何，编辑器只能由可视化编辑器启用。在特定环境中禁用编辑器是一种加强安全性的方式。

    • clientId:

      • 类型：string | undefined
      • 默认值：undefined
      • 描述: clientId 和 clientSecret 允许 intlayer 包使用 oAuth2 认证与后端进行身份验证。访问令牌用于验证与项目相关的用户。要获取访问令牌，请访问 https://intlayer.org/dashboard/project 并创建一个账户。
      • 示例: true
      • 注意: 重要提示：clientId 和 clientSecret 应保持机密，不得公开共享。请确保将它们保存在安全的位置，例如环境变量中。

    • clientSecret:

      • 类型: string | undefined
      • 默认值: undefined
      • 描述: clientId 和 clientSecret 允许 intlayer 包使用 oAuth2 认证与后端进行身份验证。访问令牌用于验证与项目相关的用户。要获取访问令牌，请访问 https://intlayer.org/dashboard/project 并创建一个账户。
      • 示例: true
      • 注意: 重要提示：clientId 和 clientSecret 应保持机密，不得公开共享。请确保将它们保存在安全的位置，例如环境变量中。

    • dictionaryPriorityStrategy:

      • 类型: string
      • 默认值: 'local_first'
      • 描述: 当本地和远程词典同时存在时，优先使用词典的策略。如果设置为 'distant_first'，应用程序将优先使用远程词典而非本地词典。如果设置为 'local_first'，应用程序将优先使用本地词典而非远程词典。
      • 示例: 'distant_first'

    • liveSync:

      • 类型: boolean
      • 默认值: false
      • 描述: 指示当检测到 CMS / 可视化编辑器 / 后端内容发生变化时，应用服务器是否应热重载应用内容。
      • 示例: true
      • 备注: 例如，当添加或更新新的词典时，应用程序会更新页面中显示的内容。
      • 注意: 实时同步需要将应用内容外部化到另一个服务器。这意味着它可能会稍微影响应用的性能。为限制这种影响，我们建议将应用和实时同步服务器托管在同一台机器上。此外，实时同步与 optimize 的组合可能会对实时同步服务器产生大量请求。根据您的基础设施，我们建议测试这两种选项及其组合。

    • liveSyncPort:

      • 类型: number
      • 默认值: 4000
      • 描述: 实时同步服务器的端口。
      • 示例: 4000
      • 注意: 实时同步服务器的端口。

    • liveSyncURL:

      • 类型: string
      • 默认值: 'http://localhost:{liveSyncPort}'
      • 描述: 实时同步服务器的 URL。
      • 示例: 'https://example.com'
      • 备注: 默认指向 localhost，但在远程实时同步服务器的情况下可以更改为任何 URL。

    中间件配置

    控制中间件行为的设置，包括应用如何处理 cookie、头信息以及用于区域管理的 URL 前缀。

    属性

    • headerName:

      • 类型: string
      • 默认值: 'x-intlayer-locale'
      • 描述: 用于确定区域的 HTTP 头名称。
      • 示例: 'x-custom-locale'
      • 备注: 这对于基于 API 的区域确定非常有用。

    • cookieName:

      • 类型: string
      • 默认值: 'intlayer-locale'
      • 描述: 用于存储区域的 cookie 名称。
      • 示例: 'custom-locale'
      • 说明: 用于在会话之间保持语言环境。

    • prefixDefault:

      • 类型: boolean
      • 默认值: false
      • 说明: 是否在 URL 中包含默认语言环境。
      • 示例: true
      • 说明:
        • 如果为 true 且 defaultLocale = 'en'：路径为 /en/dashboard 或 /fr/dashboard
        • 如果为 false 且 defaultLocale = 'en'：路径为 /dashboard 或 /fr/dashboard

    • basePath:

      • 类型: string
      • 默认值: ''
      • 说明: 应用程序 URL 的基础路径。
      • 示例: '/my-app'
      • 说明:
        • 如果应用托管在 https://example.com/my-app
        • 基础路径为 '/my-app'
        • URL 将是 https://example.com/my-app/en
        • 如果未设置基础路径，URL 将是 https://example.com/en

    • serverSetCookie：

      • 类型：string
      • 默认值：'always'
      • 描述：服务器端设置语言环境 Cookie 的规则。
      • 选项：'always'，'never'
      • 示例：'never'
      • 说明：控制是否在每次请求时设置语言环境 Cookie，或者从不设置。

    • noPrefix：

      • 类型：boolean
      • 默认值：false
      • 描述：是否在 URL 中省略语言环境前缀。
      • 示例：true
      • 说明：
        • 如果为 true：URL 中无前缀
        • 如果为 false：URL 中有前缀
        • 以 basePath = '/my-app' 为例：
          • 如果 noPrefix = false：URL 将是 https://example.com/my-app/en
          • 如果 noPrefix = true：URL 将是 https://example.com

    内容配置

    与应用内内容处理相关的设置，包括目录名称、文件扩展名及派生配置。

    属性

    • autoFill：

      • 类型：boolean | string | { [key in Locales]?: string }
      • 默认值：undefined
      • 描述：指示内容应如何使用 AI 自动填充。可以在 intlayer.config.ts 文件中全局声明。
      • 示例：true
      • 示例：'./{{fileName}}.content.json'
      • 示例：{ fr: './{{fileName}}.fr.content.json', es: './{{fileName}}.es.content.json' }
      • 备注：自动填充配置。它可以是：
        • boolean：为所有语言启用自动填充
        • string：单个文件路径或带变量的模板路径
        • object：每个语言的文件路径

    • watch:

      • 类型：boolean
      • 默认值：process.env.NODE_ENV === 'development'
      • 描述：指示 Intlayer 是否应监视应用中内容声明文件的更改，以重建相关字典。

    • fileExtensions:

      • 类型：string[]
      • 默认值: ['.content.ts', '.content.js', '.content.cjs', '.content.mjs', '.content.json', '.content.tsx', '.content.jsx']
      • 描述: 构建字典时要查找的文件扩展名。
      • 示例: ['.data.ts', '.data.js', '.data.json']
      • 备注: 自定义文件扩展名可以帮助避免冲突。

    • baseDir:

      • 类型: string
      • 默认值: process.cwd()
      • 描述: 项目的基础目录。
      • 示例: '/path/to/project'
      • 备注: 用于解析所有与 Intlayer 相关的目录。

    • dictionaryOutput:

      • 类型: string[]
      • 默认值: ['intlayer']
      • 描述: 使用的字典输出类型，例如 'intlayer' 或 'i18next'。

    • contentDir:

      • 类型: string[]
      • 默认值: ['.']
      • 示例: ['src', '../../ui-library', require.resolve("@my-package/content")]
      • 描述: 存储内容的目录路径。

    • dictionariesDir:

      • 类型: string
      • 默认: '.intlayer/dictionaries'
      • 描述: 用于存储中间结果或输出结果的目录路径。

    • moduleAugmentationDir:

      • 类型: string
      • 默认: '.intlayer/types'
      • 描述: 模块增强目录，允许更好的 IDE 提示和类型检查。
      • 示例: 'intlayer-types'
      • 注意: 确保在 tsconfig.json 中包含此目录。

    • unmergedDictionariesDir:

      • 类型: string
      • 默认: '.intlayer/unmerged_dictionary'
      • 描述: 用于存储未合并字典的目录。
      • 示例: 'translations'

    • dictionariesDir:

      • 类型: string
      • 默认值: '.intlayer/dictionary'
      • 描述: 用于存储本地化词典的目录。
      • 示例: 'translations'

    • i18nextResourcesDir:

      • 类型: string
      • 默认值: 'i18next_dictionary'
      • 描述: 用于存储 i18n 词典的目录。
      • 示例: 'translations'
      • 注意: 确保该目录已为 i18next 输出类型进行配置。

    • typesDir:

      • 类型: string
      • 默认值: 'types'
      • 描述: 用于存储词典类型的目录。
      • 示例: 'intlayer-types'

    • mainDir:

      • 类型: string
      • 默认值: 'main'
      • 描述: 存放主应用程序文件的目录。
      • 示例: 'intlayer-main'

    • excludedPath:

      • 类型: string[]
      • 默认值: ['node_modules']
      • 描述: 排除内容搜索的目录。
      • 备注: 此设置尚未使用，但计划在未来实现。

    日志配置

    控制日志记录器的设置，包括使用的前缀。

    属性

    • mode:

      • 类型: string
      • 默认值: default
      • 描述: 指示日志记录器的模式。
      • 选项: default，verbose，disabled
      • 示例: default
      • 备注: 日志记录器的模式。详细模式将记录更多信息，可用于调试。禁用模式将关闭日志记录器。

    • prefix:

      • 类型: string
      • 默认值: '[intlayer] '
      • 描述: 日志记录器的前缀。
      • 示例: '[my custom prefix] '
      • 注释: 日志器的前缀。

    AI 配置

    控制 Intlayer AI 功能的设置，包括提供商、模型和 API 密钥。

    如果您已使用访问密钥在Intlayer 控制面板注册，则此配置是可选的。Intlayer 会自动管理最有效且具有成本效益的 AI 解决方案以满足您的需求。使用默认选项可确保更好的长期可维护性，因为 Intlayer 会持续更新以使用最相关的模型。

    如果您希望使用自己的 API 密钥或特定模型，可以定义自定义的 AI 配置。 此 AI 配置将在整个 Intlayer 环境中全局使用。CLI 命令将使用这些设置作为命令的默认值（例如 fill），同时 SDK、可视化编辑器和 CMS 也会使用这些默认值。您可以通过命令参数覆盖这些默认值以满足特定用例。

    Intlayer 支持多个 AI 提供商，以增强灵活性和选择。目前支持的提供商有：

    • OpenAI（默认）
    • Anthropic Claude
    • Mistral AI
    • DeepSeek
    • Google Gemini
    • Meta Llama

    属性

    • provider：

      • 类型：string
      • 默认值：'openai'
      • 描述：用于 Intlayer AI 功能的提供商。
      • 选项：'openai'、'anthropic'、'mistral'、'deepseek'、'gemini'
      • 示例：'anthropic'
      • 注意: 不同的提供商可能需要不同的 API 密钥，并且有不同的定价模型。

    • model:

      • 类型: string
      • 默认值: 无
      • 描述: 用于 Intlayer AI 功能的模型。
      • 示例: 'gpt-4o-2024-11-20'
      • 注意: 具体使用的模型因提供商而异。

    • temperature:

      • 类型: number
      • 默认值: 无
      • 描述: temperature 控制 AI 回答的随机性。
      • 示例: 0.1
      • 注意: 较高的 temperature 会使 AI 更具创造性且不可预测。

    • apiKey:

      • 类型: string
      • 默认值: 无
      • 描述: 你为所选提供商提供的 API 密钥。
      • 示例: process.env.OPENAI_API_KEY
      • 注意: 重要提示：API 密钥应保密，切勿公开共享。请确保将其保存在安全的位置，例如环境变量中。

    • applicationContext:

      • 类型: string
      • 默认值: 无
      • 描述: 向 AI 模型提供有关您的应用程序的额外上下文，帮助其生成更准确且符合上下文的翻译。这可以包括您的应用领域、目标受众、语气或特定术语的信息。

    构建配置

    控制 Intlayer 如何优化和构建您的应用程序国际化的设置。

    构建选项适用于 @intlayer/babel 和 @intlayer/swc 插件。

    在开发模式下，Intlayer 使用静态导入字典，以简化开发体验。
    在优化模式下，Intlayer 会替换字典调用以优化代码分块，因此最终打包只会导入实际使用的字典。

    属性

    • optimize：

      • 类型：boolean
      • 默认值：process.env.NODE_ENV === 'production'
      • 描述：控制构建是否应进行优化。
      • 示例：true
      • 注意：启用时，Intlayer 会替换所有字典调用以优化代码分块。这样最终打包只会导入被使用的字典。所有导入将保持为静态导入，以避免加载字典时的异步处理。
      • 注意: Intlayer 会根据 importMode 选项定义的模式替换所有 useIntlayer 的调用，并将 getIntlayer 替换为 getDictionary。
      • 注意: 此选项依赖于 @intlayer/babel 和 @intlayer/swc 插件。
      • 注意: 确保所有键在 useIntlayer 调用中是静态声明的。例如 useIntlayer('navbar')。

    • importMode:

      • 类型: 'static' | 'dynamic' | 'live'
      • 默认值: 'static'
      • 描述: 控制字典的导入方式。
      • 示例: 'dynamic'
      • 注意: 可用模式：
        • "static"：字典以静态方式导入。将 useIntlayer 替换为 useDictionary。
        • "dynamic"：字典通过 Suspense 动态导入。将 useIntlayer 替换为 useDictionaryDynamic。
      • "live"：字典通过实时同步 API 动态获取。将 useIntlayer 替换为 useDictionaryFetch。
      • 注意：动态导入依赖 Suspense，可能会略微影响渲染性能。
      • 注意：如果禁用，所有语言环境将一次性加载，即使未被使用。
      • 注意：此选项依赖 @intlayer/babel 和 @intlayer/swc 插件。
      • 注意：确保在 useIntlayer 调用中所有键都是静态声明的。例如 useIntlayer('navbar')。
      • 注意：如果禁用 optimize，此选项将被忽略。
      • 注意: 如果设置为 "live"，只有包含远程内容且标记为 "live" 的字典会被转换为实时模式。其他字典将以 "dynamic" 模式动态导入，以优化请求次数和加载性能。
      • 注意: 实时模式将使用实时同步 API 来获取字典。如果 API 调用失败，字典将以 "dynamic" 模式动态导入。
      • 注意: 此选项不会影响 getIntlayer、getDictionary、useDictionary、useDictionaryAsync 和 useDictionaryDynamic 函数。

    • traversePattern:

      • 类型: string[]
      • 默认值: ['**/*.{js,ts,mjs,cjs,jsx,tsx,mjx,cjx}', '!**/node_modules/**']
      • 描述：定义在优化过程中应遍历哪些文件的模式。
        • 示例：['src/**/*.{ts,tsx}', '../ui-library/**/*.{ts,tsx}', '!**/node_modules/**']
      • 注意：使用此选项限制优化范围到相关代码文件，以提升构建性能。
      • 注意：如果禁用 optimize，此选项将被忽略。
      • 注意：使用 glob 模式。
    Intlayer如何工作
    CLI
    接收有关即将发布的Intlayer的通知