Intlayer 配置文档

概述

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

配置文件支持

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

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

示例配置文件

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

• detectLocaleOnPrefetchNoPrefix:

  • 类型: boolean
  • 默认值: false
  • 描述: 控制是否在 Next.js 预取请求期间进行语言环境检测。
  • 示例: true
  • 说明: 此设置影响 Next.js 如何处理语言环境预取：
    • 示例场景：
      • 用户浏览器语言为 'fr'
      • 当前页面为 /fr/about
      • 链接预取 /about
    • 当 detectLocaleOnPrefetchNoPrefix: true 时：
      • 预取从浏览器检测到 'fr' 语言环境
      • 将预取重定向到 /fr/about
    • 当 detectLocaleOnPrefetchNoPrefix: false（默认）时：
      • 预取使用默认语言环境
      • 将预取重定向到 /en/about（假设 'en' 是默认语言）
    • 何时使用 true：
      • 您的应用使用非本地化的内部链接（例如 <a href="/about">）
      • 您希望常规请求和预取请求之间的语言检测行为保持一致
    • 何时使用 false（默认值）：
      • 您的应用使用带语言前缀的链接（例如 <a href="/fr/about">）
      • 您希望优化预取性能
      • 您希望避免潜在的重定向循环

内容配置

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

属性

• 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 模式。

文档历史

• 描述: 定义在优化过程中应遍历哪些文件的模式。
• 示例: ['src/**/*.{ts,tsx}', '../ui-library/**/*.{ts,tsx}', '!**/node_modules/**']
• 注意: 使用此选项限制优化范围到相关代码文件，以提升构建性能。
• 注意: 如果禁用 optimize，此选项将被忽略。
• 注意: 使用 glob 模式。

文档历史