高级配置

Lingo.dev 编译器 提供了广泛的配置选项，用于自定义翻译行为并优化您的本地化工作流程。

配置设置

在项目中实现编译器时，可以传递一个包含以下选项的设置对象：

// 默认配置
const compilerConfig = {
  sourceRoot: "src",
  lingoDir: "lingo",
  sourceLocale: "en",
  targetLocales: ["es"],
  rsc: false,
  debug: false,
  models: {
    // 自定义模型配置
    "*:fr": "mistral-saba-24b",
    "en:es": "meta-llama/llama-4-maverick-17b-128e-instruct",
    "*:*": "mistral-saba-24b",
  },
  prompt:
    "You are AI translator. You translate from {SOURCE_LOCALE} to {TARGET_LOCALE}.",
};

// Next.js
lingoCompiler.next(compilerConfig)(nextConfig);

// Vite/React Router
lingoCompiler.vite(compilerConfig)(viteConfig);

配置选项

  • sourceRoot - 源目录的路径，其中将存储 lingo/ 目录
  • lingoDir - 包含翻译文件的目录名称（默认值："lingo"）
  • sourceLocale - 应用程序的源语言（默认值："en"）
  • targetLocales - 要翻译成的目标语言数组
  • rsc - 启用 React 服务器组件支持（默认值：false）
  • debug - 启用调试日志以进行故障排除（默认值：false）
  • models - 特定语言对的自定义 AI 模型配置（可选）
  • prompt - 带有占位符的自定义翻译提示（可选）

推荐的 Groq 模型

为了获得最佳效果，我们测试并验证了以下 GROQ 模型 在特定语言环境中的质量：

mistral-saba-24b

  • ar - 阿拉伯语
  • de - 德语
  • fr - 法语
  • pt-BR - 葡萄牙语（巴西）

meta-llama/llama-4-maverick-17b-128e-instruct

  • es - 西班牙语
  • ja - 日语
  • ko - 韩语
  • ru - 俄语
  • zh - 中文

文件处理控制

跳过翻译

在不需要翻译的元素中添加 data-lingo-skip 属性：

<div data-lingo-skip>此内容不会被翻译</div>

翻译覆盖

使用 data-lingo-override- 属性为特定语言环境覆盖翻译：

<button data-lingo-override-es="¡Hola!" data-lingo-override-fr="Bonjour!">
  Hello
</button>

自定义模型配置

您可以直接在编译器配置中自定义 AI 模型和提示：

const compilerConfig = {
  sourceLocale: "en",
  targetLocales: ["es", "fr", "de"],
  models: {
    "*:fr": "mistral-saba-24b",
    "en:es": "meta-llama/llama-4-maverick-17b-128e-instruct",
    "es:fr": "meta-llama/llama-4-maverick-17b-128e-instruct",
    "*:*": "mistral-saba-24b",
  },
  prompt:
    "You are a professional translator specializing in technical documentation. Translate from {SOURCE_LOCALE} to {TARGET_LOCALE} while maintaining technical accuracy.",
};

模型配置

  • 将语言环境对定义为 source-locale:target-locale
  • 使用 * 作为通配符表示任意语言环境
  • 使用 *:* 作为所有翻译的回退选项
  • 查看 GROQ 模型 了解可用选项

自定义提示

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

  • {SOURCE_LOCALE} - 源语言代码
  • {TARGET_LOCALE} - 目标语言代码

为了构建自定义术语表，请在提示中包含术语。参考 默认编译器提示 以获取最佳实践。

构建规范化

在提交更改之前，请始终在本地运行生产构建：

npm run build

这可确保 lingo/ 目录中的 meta.json 和 dictionary.js 文件仅包含您的应用中存在的字符串，并且格式正确。

提交前钩子设置

使用 husky 设置自动规范化：


# 安装 husky

npm install --save-dev husky

# 添加提交前钩子

npx husky add .husky/pre-commit "npm run build"

环境特定配置

开发环境

const isDev = process.env.NODE_ENV === "development";

const compilerConfig = {
  debug: isDev,
  targetLocales: isDev ? ["es"] : ["es", "fr", "de", "ja"],
};

CI/CD 集成

对于自动化构建，请确保您的 CI 环境可以访问 GROQ API 密钥：


# GitHub Actions

GROQ_API_KEY: ${{ secrets.GROQ_API_KEY }}

# Vercel

GROQ_API_KEY=gsk_...

# Netlify

GROQ_API_KEY=gsk_...

性能优化

增量构建

编译器会自动：

  • 通过文件指纹跟踪内容更改
  • 仅翻译新的或修改过的内容
  • 对未更改的内容重用现有翻译

包优化

  • 按语言环境的包 - 仅加载活动语言环境的翻译
  • Tree shaking - 从生产构建中移除未使用的翻译
  • 代码分割 - 为基于路由的应用按需加载翻译

疑难解答

调试模式

启用调试日志以排查问题：

const compilerConfig = {
  debug: true,
  // ... 其他选项
};

常见问题

缺失翻译：确保您已在本地运行 npm run build 并提交了 lingo/ 目录。如果您使用的是 NextJS，可能需要删除 .next/ 目录以确保所有文件被重新构建。

构建错误：检查您的环境变量中是否正确设置了 GROQ_API_KEY。

性能问题：启用调试模式以识别编译过程中的瓶颈。

下一步