此页面的内容已使用 AI 翻译。

    查看英文原文的最新版本

    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: {    typesDir: "content/types", // 内容类型目录  },  middleware: {    noPrefix: false, // 是否禁用前缀  },};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 或 Header 中未指定语言时，用于确定语言。

    编辑器配置

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

    属性

    • 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 认证与后端进行身份验证。访问令牌用于验证与项目相关的用户。要获取访问令牌，请访问 /dashboard/project 并创建一个账户。
      • 示例: true
      • 注意: 重要：clientId 和 clientSecret 应该保密，不应公开共享。请确保将它们保存在安全的位置，例如环境变量中。

    • clientSecret:

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

    • hotReload:

      • 类型: boolean
      • 默认值: false
      • 描述: 指示应用程序是否在检测到更改时热加载语言配置。
      • 示例: true
      • 注意: 例如，当添加或更新新词典时，应用程序将更新页面中显示的内容。
      • 注意: 由于热加载需要与服务器的持续连接，因此仅适用于 enterprise 计划的客户。

    • dictionaryPriorityStrategy:

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

    中间件配置

    控制中间件行为的设置，包括应用程序如何处理 Cookies、Headers 和用于语言管理的 URL 前缀。

    属性

    • headerName:

      • 类型: string
      • 默认值: 'x-intlayer-locale'
      • 描述: 用于确定语言的 HTTP Header 名称。
      • 示例: 'x-custom-locale'

      • 注意: 这对于基于 API 的语言确定非常有用。

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

    • prefixDefault:

      • 类型: boolean
      • 默认值: true
      • 描述: 是否在 URL 中包含默认语言环境。
      • 示例: false
      • 注意: 如果为 false，默认语言环境的 URL 将不会有语言环境前缀。

    • basePath:

      • 类型: string
      • 默认值: ''
      • 描述: 应用程序 URL 的基础路径。
      • 示例: '/my-app'
      • 注意: 这会影响应用程序 URL 的构建方式。

    • serverSetCookie:

      • 类型: string
      • 默认值: 'always'
      • 描述: 在服务器上设置语言环境 Cookie 的规则。
      • 选项: 'always', 'never'
      • 示例: 'never'
      • 注意: 控制是否在每个请求上设置语言环境 Cookie 或从不设置。

    • noPrefix:

      • 类型: boolean
      • 默认值: false
      • 描述: 是否从 URL 中省略语言环境前缀。
      • 示例: true
      • 注意: 如果为 true，URL 将不包含语言环境信息。

    内容配置

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

    属性

    • 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']
      • 描述: 存储内容的目录路径。

    • 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 Dashboard 上注册，则此配置是可选的。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
      • 默认值: 无
      • 描述: 温度控制 AI 响应的随机性。
      • 示例: 0.1
      • 注意: 较高的温度会使 AI 更具创造性且更不可预测。

    • apiKey:

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

    • applicationContext:

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

    如果您有改善此文档的想法，请随时通过在GitHub上提交拉取请求来贡献。

    文档的 GitHub 链接
    Intlayer如何工作Intlayer的优势