Alpha
Lingo.dev Compiler 目前仍处于 Alpha 阶段，稳定性尚未完善，不建议用于生产环境，且 API 可能会在不同版本之间发生变化。
Lingo.dev Compiler 的配置对象决定了你的 React 应用在构建阶段如何完成翻译。此页面汇总了全部可用选项，包括类型、默认值和使用示例。
核心选项#
| 选项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
sourceRoot | string | "src" | 存放可翻译组件的目录，相对于项目根目录。 |
lingoDir | string | ".lingo" | 用于存放翻译元数据和缓存文件的目录。 |
sourceLocale | string | 必填 | 源内容的语言代码（例如 "en"）。 |
targetLocales | string[] | 必填 | 目标语言代码数组（例如 ["es", "de", "fr"]）。 |
useDirective | boolean | false | 当为 true 时，仅翻译带有 'use i18n' 指令的文件；当为 false 时，则会翻译 sourceRoot 中的所有文件。 |
models | string | object | "lingo.dev" | 翻译提供方配置。字符串可作为所有 locale 对的默认值；对象则可将不同 locale 对映射到指定提供方。 |
prompt | string | undefined | 用于翻译 LLM 的自定义 system prompt，支持 {SOURCE_LOCALE} 和 {TARGET_LOCALE} 占位符。 |
buildMode | "translate" | "cache-only" | "translate" | 控制 Compiler 是生成新翻译，还是只使用缓存中的翻译。 |
开发选项#
dev 键下的选项用于控制开发阶段的行为：
| 选项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
dev.usePseudotranslator | boolean | false | 生成即时伪翻译（例如 [!!! Welcome !!!]），无需调用 LLM，也不需要 API 密钥。 |
dev.translationServerStartPort | number | 60000 | 本地翻译服务器的起始端口。Compiler 会在 60000-60099 范围内自动寻找可用端口。 |
dev.translationServerUrl | string | undefined | 覆盖翻译服务器的 URL，适用于自定义部署或远程翻译服务器。 |
Locale 持久化#
localePersistence 下的选项用于控制如何存储和读取用户所选的 locale：
| 选项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
localePersistence.type | string | "cookie" | 持久化机制，目前支持 "cookie"。 |
localePersistence.config.name | string | "locale" | 用于存储 locale 的 Cookie 名称。 |
localePersistence.config.maxAge | number | 31536000 | Cookie 的 max-age（秒），默认值为 1 年。 |
如果你需要自定义持久化逻辑（localStorage、基于 URL 或请求头），请参阅 Custom Locale Resolvers。
复数处理#
pluralization 下的选项用于控制复数形式的自动检测与生成：
| 选项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
pluralization.enabled | boolean | true | 启用或关闭自动复数检测。 |
pluralization.model | string | "groq:llama-3.1-8b-instant" | 用于检测源文本复数形式的 LLM 模型。由于检测比翻译更简单，建议使用更小、更快的模型。 |
想了解复数检测的工作方式，请参阅 Automatic Pluralization。
环境变量#
环境变量可用于覆盖或补充配置：
| 变量 | 何时需要 | 说明 |
|---|---|---|
LINGO_BUILD_MODE | 可选 | 覆盖 buildMode 配置项。可设置为 "translate" 或 "cache-only"。 |
LINGODOTDEV_API_KEY | 使用 "lingo.dev" 模型时 | Lingo.dev 本地化引擎的 API 密钥，可通过 npx lingo.dev@latest login 获取。 |
OPENAI_API_KEY | 使用 "openai:*" 模型时 | OpenAI API 密钥。 |
ANTHROPIC_API_KEY | 使用 "anthropic:*" 模型时 | Anthropic API 密钥。 |
GOOGLE_API_KEY | 使用 "google:*" 模型时 | Google AI API 密钥。 |
GROQ_API_KEY | 使用 "groq:*" 模型时 | Groq API 密钥。 |
MISTRAL_API_KEY | 使用 "mistral:*" 模型时 | Mistral API 密钥。 |
OPENROUTER_API_KEY | 使用 "openrouter:*" 模型时 | OpenRouter API 密钥。 |
完整示例#
ts
// 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, {
sourceRoot: "./app",
lingoDir: ".lingo",
sourceLocale: "en",
targetLocales: ["es", "de", "fr", "ja"],
useDirective: false,
models: {
"*:*": "lingo.dev",
"*:ja": "anthropic:claude-3-5-sonnet",
},
prompt: "Translate UI text from {SOURCE_LOCALE} to {TARGET_LOCALE}. Keep it concise.",
buildMode: "translate",
dev: {
usePseudotranslator: true,
translationServerStartPort: 60000,
},
localePersistence: {
type: "cookie",
config: {
name: "locale",
maxAge: 31536000,
},
},
pluralization: {
enabled: true,
model: "groq:llama-3.1-8b-instant",
},
});
}