最佳实践

@lingo.dev/compiler 推荐的模式与工作流。

开发工作流

默认使用伪翻译器

建议：

{
  dev: {
    usePseudotranslator: true, // Fast, free, instant feedback
  }
}

原因：

实时反馈，无 API 延迟
零成本，不消耗 API 配额
可视化标记显示哪些内容被翻译
可测试不同文本长度下的 UI 效果

仅在检查实际翻译质量时才禁用。

区分开发、CI 和生产环境

开发环境：

{
  buildMode: "translate",
  dev: {
    usePseudotranslator: true,
  }
}

CI：

{
  buildMode: "translate",
  dev: {
    usePseudotranslator: false,
  }
}

生产环境：

{
  buildMode: "cache-only",
}

此工作流可：

保持开发高效且低成本
每次部署时在 CI 中生成真实翻译
让生产构建可预测且高效

翻译策略

让 AI 处理大部分翻译

建议：

<p>Welcome to our application</p>

避免：

<p data-lingo-override={{ es: "...", de: "...", fr: "..." }}>
  Welcome to our application
</p>

仅在以下场景谨慎使用覆盖：

品牌名称
需要特定翻译的技术术语
需要认证的法律文本
需要人工审核的市场营销文案

一致地使用覆盖

建议：

// Consistent brand name across app
<h1 data-lingo-override={{ es: "Lingo.dev", de: "Lingo.dev" }}>
  Lingo.dev
</h1>

<p>
  Welcome to <span data-lingo-override={{ es: "Lingo.dev", de: "Lingo.dev" }}>
    Lingo.dev
  </span>
</p>

不要这样：

<h1 data-lingo-override={{ es: "Lingo.dev" }}>Lingo.dev</h1>
<p>Welcome to Lingo.dev</p> // Missing override—inconsistent

配置

从简单开始

推荐做法：

{
  sourceLocale: "en",
  targetLocales: ["es", "de"],
  models: "lingo.dev",
}

不要这样：

{
  sourceLocale: "en",
  targetLocales: ["es", "de", "fr", "pt", "it", "ja", "zh", "ar", "ru", "ko"],
  models: {
    "en:es": "groq:...",
    "en:de": "google:...",
    // Complex mappings for 10 locales
  },
  prompt: "Long custom prompt...",
  pluralization: { enabled: false },
}

建议先选择 2-3 个目标语言环境，按需逐步增加。避免过早优化。

使用 Lingo.dev Engine

推荐做法：

{
  models: "lingo.dev" // Simple, optimized, supports all features
}

不要这样：

{
  models: {
    "*:*": "groq:...", // Requires manual model selection
  }
}

Lingo.dev Engine 提供：

自动模型选择
回退处理
翻译记忆库
术语表支持

仅在需要完全控制或优化成本时，才建议直接使用 LLM 提供商。

语言环境检测

推荐做法：

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

自定义场景：

需要 localStorage（SPA 偏好）
基于 URL 的路由（/en/about）
子域名路由（es.example.com）
数据库驱动的用户偏好

仅当默认方案不适用时，才实现自定义语言环境解析器。

版本控制

提交 .lingo/ 目录

推荐做法：

git add .lingo/
git commit -m "chore: update translations"
git push

原因：

版本控制可追踪翻译变更
Team 可共享翻译内容
CI/CD 使用已提交的翻译
生产环境构建无需 API key

CI 执行后提交

（在 CI 中）推荐做法：

- name: Generate translations
  run: npm run build

- name: Commit translations
  run: |
    git add .lingo/
    git commit -m "chore: update translations" || exit 0
    git push

这样可以确保生产环境构建始终使用最新翻译。

CI/CD

在 CI 中生成翻译

推荐做法：

# GitHub Actions
- name: Generate translations
  env:
    LINGODOTDEV_API_KEY: ${{ secrets.LINGODOTDEV_API_KEY }}
  run: npm run build

不要这样：

# Production build without API key
- name: Build
  run: npm run build # Fails if translations missing

在 CI 中生成翻译（此时有 API key）。生产环境构建使用缓存的翻译。

生产环境仅使用缓存

推荐做法：

# Production build
LINGO_BUILD_MODE=cache-only npm run build

不要这样：

# Production build with translate mode
LINGO_BUILD_MODE=translate npm run build # Non-deterministic, requires API keys

性能

有选择地启用复数处理

如需使用复数形式时推荐做法：

{
  pluralization: {
    enabled: true,
  }
}

如不使用复数时推荐做法：

{
  pluralization: {
    enabled: false, // Skip plural detection—faster builds
  }
}

复数处理会带来少量开销（每个包含数字的文本需一次 LLM 调用）。如无需求可禁用。

为复数处理使用高效模型

推荐做法：

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

不要这样：

{
  pluralization: {
    model: "openai:gpt-4o", // Expensive overkill for plural detection
  }
}

优化语种映射

推荐做法（成本优化）：

{
  models: {
    "en:es": "groq:llama-3.3-70b-versatile", // Fast & cheap
    "en:ja": "openai:gpt-4o", // High quality for complex language
    "*:*": "lingo.dev", // Fallback
  }
}

对于相近语言（如 Romance、Germanic），使用快速/低成本模型。对于复杂语言（如 CJK、阿拉伯语），使用高质量模型。

测试

首先用伪翻译器测试

推荐做法：

启用伪翻译器
测试所有 UI 组件
修复布局问题（溢出、截断）
再生成真实翻译

原因：

伪翻译即时生成
可及早发现布局问题
节省 API 成本

测试所有目标语种

推荐做法：

// Test with locale switcher
<LanguageSwitcher /> // Switch between all locales

// Or manually test
setLocale("es"); // Spanish
setLocale("de"); // German
setLocale("fr"); // French

验证每个语种：

翻译内容正确显示
布局能适应文本长度
无未翻译文本
RTL 语言正确渲染（如适用）

错误处理

优雅处理缺失翻译

如有缺失翻译，编译器会导致构建失败。这是有意为之——及早发现缺失翻译优于发布有问题的 UI。

如构建失败：

使用 buildMode: "translate" 生成缺失翻译
提交 .lingo/metadata.json
使用 buildMode: "cache-only" 重新尝试生产构建

监控翻译失败

在 CI 中检查翻译错误：

- name: Generate translations
  run: npm run build 2>&1 | tee build.log

- name: Check for translation errors
  run: |
    if grep -q "Failed to generate translation" build.log; then
      echo "Translation generation failed"
      exit 1
    fi

维护

定期清理

定期移除未使用的翻译：

# Backup first
cp .lingo/metadata.json .lingo/metadata.backup.json

# Manual: Search for each hash in codebase, remove if not found

# Automated (coming soon):
npx @lingo.dev/compiler clean

监控文件大小

.lingo/metadata.json 会随着应用增长而变大。如果文件过大（>5 MB）：

考虑拆分为多个应用
归档旧翻译
使用自动清理

常见反模式

不要过度使用覆盖

错误示例：

<p data-lingo-override={{ es: "...", de: "...", fr: "..." }}>
  Welcome to our app
</p>

让 AI 处理常规文本。覆盖仅用于特殊情况。

不要提交 API 密钥

错误示例：

// next.config.ts
{
  models: "lingo.dev",
  apiKey: "your-api-key-here", // NEVER commit API keys
}

正确示例：

# .env (not committed)
LINGODOTDEV_API_KEY=your_key_here

不要在生产环境中使用 translate 模式

错误示例：

// production config
{
  buildMode: "translate", // Non-deterministic, requires API keys
}

正确示例：

{
  buildMode: "cache-only", // Deterministic, no API keys
}

不要跳过版本控制

错误示例：

# .gitignore
.lingo/ # DON'T ignore translations

正确示例：

# .gitignore
.env # Ignore API keys only

迁移策略

渐进式发布

将编译器集成到现有应用时：

先支持 1-2 个 locale
启用伪翻译器
测试所有页面
修复布局问题
增加更多 locale
生成真实翻译
部署

不要在第一天就尝试翻译 20 个 locale。

增量采纳

无需一次性翻译整个应用：

{
  useDirective: true, // Opt-in per file
}

在需要翻译的文件中添加 'use i18n' 指令：

'use i18n'; // This file gets translated

export function HomePage() {
  return <h1>Welcome</h1>;
}

其他文件保持未翻译状态，直到你选择加入。

下一步

迁移指南 — 从旧编译器迁移
故障排查 — 常见问题与解决方案
配置参考 — 所有选项说明

开发工作流

默认使用伪翻译器

区分开发、CI 和生产环境

翻译策略

让 AI 处理大部分翻译

一致地使用覆盖

配置

从简单开始

使用 Lingo.dev Engine

语言环境检测

使用默认的 Cookie 持久化方式

版本控制

提交 .lingo/ 目录

CI 执行后提交

CI/CD

在 CI 中生成翻译

生产环境仅使用缓存

性能

有选择地启用复数处理

为复数处理使用高效模型

优化语种映射

测试

首先用伪翻译器测试

测试所有目标语种

错误处理

优雅处理缺失翻译

监控翻译失败

维护

定期清理

监控文件大小

常见反模式

不要过度使用覆盖

不要提交 API 密钥

不要在生产环境中使用 translate 模式

不要跳过版本控制

迁移策略

渐进式发布

增量采纳

下一步