配置参考

@lingo.dev/compiler 所有配置选项的完整参考。

核心选项

选项类型默认值说明
sourceRootstring"src"包含待翻译源代码的根目录
lingoDirstring".lingo"存放翻译元数据和缓存的目录
sourceLocalestring(必填)源语言区域代码（例如，"en"、"en-US"）
targetLocalesstring[](必填)目标语言区域代码数组
useDirectivebooleanfalse是否要求使用 'use i18n' 指令进行选择性翻译
modelsstring | object"lingo.dev"翻译服务提供商配置（参见 Translation Providers）
promptstringundefined自定义翻译提示模板
buildMode"translate" | "cache-only""translate"构建模式（参见 Build Modes）

示例

{
  sourceRoot: "./app",
  lingoDir: ".lingo",
  sourceLocale: "en",
  targetLocales: ["es", "de", "fr", "ja"],
  useDirective: false,
  models: "lingo.dev",
  buildMode: "translate",
}

开发选项

通过 dev 对象配置开发相关行为：

选项类型默认值说明
dev.usePseudotranslatorbooleanfalse使用伪翻译替代真实 AI（推荐用于开发环境）
dev.translationServerStartPortnumber60000翻译服务器的起始端口（自动查找 60000-60099）
dev.translationServerUrlstringundefined自定义翻译服务器 URL（高级用法）

示例

{
  dev: {
    usePseudotranslator: true, // Fast fake translations
    translationServerStartPort: 60000, // Default port range
  }
}

为什么选择伪翻译器？ 它即时生效（无需 API 调用），能准确显示哪些内容被翻译，并可测试 UI 在不同文本长度下的表现——全部无需 API 成本。

语言环境持久化

配置语言环境更改的持久化方式：

选项类型默认值描述
localePersistence.type"cookie""cookie"当前仅支持基于 Cookie 的持久化
localePersistence.config.namestring"locale"Cookie 名称
localePersistence.config.maxAgenumber31536000Cookie 最大有效期（秒，默认：1 年）

示例

{
  localePersistence: {
    type: "cookie",
    config: {
      name: "user-locale",
      maxAge: 31536000, // 1 year
    },
  },
}

需要自定义持久化？ 实现 自定义语言环境解析器 以使用 localStorage、URL 参数或数据库持久化。

复数处理

配置自动复数检测：

选项类型默认值描述
pluralization.enabledbooleantrue启用自动 ICU MessageFormat 检测
pluralization.modelstring"groq:llama-3.1-8b-instant"用于复数形式检测的 LLM 模型

示例

{
  pluralization: {
    enabled: true,
    model: "groq:llama-3.1-8b-instant", // Fast model for plural detection
  },
}

工作原理： 编译器会检测文本中的复数形式（如“你有 5 个项目”），并将其转换为 ICU MessageFormat（{count, plural, one {1 item} other {# items}}）。

为提升性能可禁用： 如果不使用复数形式，可禁用此功能以跳过 LLM 复数检测调用。

翻译提供方

models 选项用于配置用于翻译的 LLM 提供方。

简单配置

为所有翻译使用单一提供方：

{
  models: "lingo.dev" // Recommended: Lingo.dev Engine
}

高级配置

使用 locale-pair 映射实现更精细的控制：

{
  models: {
    "en:es": "groq:llama-3.3-70b-versatile", // English to Spanish
    "en:de": "google:gemini-2.0-flash",      // English to German
    "*:fr": "openai:gpt-4o",                 // Any locale to French
    "*:*": "anthropic:claude-3-5-sonnet",    // Fallback for all others
  }
}

模式：

  • "source:target"：特定的语言对（例如，"en:es"）
  • "*:target"：任意源语言到特定目标语言（例如，"*:de"）
  • "source:*"：特定源语言到任意目标语言（例如，"en:*"）
  • "*:*"：所有语言对的回退

请参阅 Translation Providers 以获取提供方语法和 API 密钥设置。

自定义翻译提示

使用占位符自定义翻译提示：

{
  prompt: `Translate from {SOURCE_LOCALE} to {TARGET_LOCALE}.
Use a formal tone and preserve all technical terms.
Do not translate brand names or product names.`
}

可用占位符：

  • {SOURCE_LOCALE}：源语言代码（例如，"en"）
  • {TARGET_LOCALE}：目标语言代码（例如，"es"）

编译器会将关于被翻译文本的上下文（组件位置、周边元素）追加到您的自定义提示中。

环境变量覆盖

通过环境变量覆盖配置：

# Override build mode
LINGO_BUILD_MODE=cache-only npm run build

# Set API key
LINGODOTDEV_API_KEY=your_key_here
GROQ_API_KEY=gsk_...
GOOGLE_API_KEY=...
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
MISTRAL_API_KEY=...
OPENROUTER_API_KEY=...

完整示例

// next.config.ts
import type { NextConfig } from "next";
import { withLingo } from "@lingo.dev/compiler/next";

const nextConfig: NextConfig = {};

export default async function (): Promise<NextConfig> {
  return await withLingo(nextConfig, {
    // Core
    sourceRoot: "./app",
    lingoDir: ".lingo",
    sourceLocale: "en",
    targetLocales: ["es", "de", "fr", "ja"],
    useDirective: false,

    // Build mode
    buildMode: process.env.NODE_ENV === "production" ? "cache-only" : "translate",

    // Models
    models: {
      "en:es": "groq:llama-3.3-70b-versatile",
      "*:*": "lingo.dev",
    },

    // Custom prompt
    prompt: "Translate from {SOURCE_LOCALE} to {TARGET_LOCALE}. Use a professional tone.",

    // Development
    dev: {
      usePseudotranslator: true,
      translationServerStartPort: 60000,
    },

    // Locale persistence
    localePersistence: {
      type: "cookie",
      config: {
        name: "locale",
        maxAge: 31536000,
      },
    },

    // Pluralization
    pluralization: {
      enabled: true,
      model: "groq:llama-3.1-8b-instant",
    },
  });
}

TypeScript 类型

导入配置类型以保证类型安全：

import type { LingoConfig } from "@lingo.dev/compiler";

const config: LingoConfig = {
  // ...config
};

常见问题

我需要配置所有选项吗？ 不需要。只需配置 sourceLocale 和 targetLocales，其他选项都有合理的默认值。

sourceRoot 和 lingoDir 有什么区别？ sourceRoot 是您的源代码所在位置（例如，./app、src）。lingoDir 是存储翻译元数据的位置（默认值：.lingo）。

可以为不同语言配置不同的模型吗？ 可以。在 models 选项中使用 locale-pair 映射。参见 Translation Providers。

应该将 .lingo/ 提交到 git 吗？ 应该。.lingo/ 目录包含翻译元数据和缓存，应与代码一同进行版本控制。

如何禁用复数处理？ 设置 pluralization.enabled: false。这样会跳过复数形式检测，并减少 LLM 调用次数。

后续步骤