Lingo.dev - 面向LLM本地化的开源i18n工具套件

MCP • CLI • CI/CD • SDK • 编译器

快速入门

Lingo.dev MCP

在React应用中配置i18n极易出错——即使对经验丰富的开发者也是如此。AI编程助手反而让情况更糟：它们会幻想出不存在的API、忘记中间件配置、破坏路由，或者在迷失前只实现半套方案。问题在于i18n配置需要在多个文件（路由、中间件、组件、配置）中进行一系列精确协调的修改，而LLM难以维持这种上下文。

Lingo.dev MCP通过让AI助手结构化访问框架特定的i18n知识来解决这个问题。您的助手不再需要猜测，而是遵循Next.js、React Router和TanStack Start的已验证实现模式。

支持的IDE：

• Claude Code
• Cursor
• GitHub Copilot代理
• Codex (OpenAI)

支持的框架：

• Next.js（App路由和Pages路由 v13-16）
• TanStack Start (v1)
• React Router (v7)

使用方法：

在IDE中配置MCP服务器后（查看快速入门指南），向助手输入提示：

设置i18n，支持以下语言环境：en、es和pt-BR。默认语言环境是'en'。

助手将：

1. 配置基于语言环境的路由（如/en、/es、/pt-BR）
2. 设置语言切换组件
3. 实现自动语言环境检测
4. 生成必要的配置文件

注意： AI生成的代码具有不确定性，提交前请仔细审查。

阅读文档

Lingo.dev CLI

保持翻译同步是件苦差事。您添加了新字符串却忘记翻译，导致国际用户看到残缺的UI。或者您将JSON文件发送给翻译人员，等待数天后又需要手动合并他们的工作。扩展到10+种语言意味着管理数百个不断失同步的文件。

Lingo.dev CLI自动化了这个过程。指向您的翻译文件，运行一个命令，所有语言环境都会更新。锁文件跟踪已完成翻译的内容，因此您只需为新增或更改的内容付费。支持JSON、YAML、CSV、PO文件和markdown。

设置：

# 初始化项目
npx lingo.dev@latest init

# 运行翻译
npx lingo.dev@latest run

工作原理：

1. 从配置文件中提取可翻译内容
2. 将内容发送至LLM提供商进行翻译
3. 将翻译后的内容写回文件系统
4. 创建i18n.lock文件跟踪已完成翻译（避免重复处理）

配置：

init命令会生成i18n.json文件。配置语言环境和存储桶：

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "de"]
  },
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"]
    }
  }
}

provider字段可选（默认为Lingo.dev引擎）。如需自定义LLM提供商：

{
  "provider": {
    "id": "openai",
    "model": "gpt-4o-mini",
    "prompt": "从{source}翻译到{target}"
  }
}

支持的LLM提供商：

• Lingo.dev引擎（推荐）
• OpenAI
• Anthropic
• Google
• Mistral
• OpenRouter
• Ollama

阅读文档

Lingo.dev CI/CD

翻译功能总是"快完成了"。工程师合并代码时忘记更新语言包。QA在预发布环境发现缺失翻译——更糟的是用户在生产环境发现。根本原因：翻译是容易在截止压力下被忽略的手动步骤。

Lingo.dev CI/CD使翻译自动化。每次推送都会触发翻译。缺失的字符串在代码进入生产环境前就被补全。无需纪律约束——流水线会处理一切。

支持平台：

• GitHub Actions
• GitLab CI/CD
• Bitbucket Pipelines

GitHub Actions设置：

创建.github/workflows/translate.yml：

name: 翻译
on:
  push:
    branches: [main]
permissions:
  contents: write
jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Lingo.dev
        uses: lingodotdev/lingo.dev@main
        with:
          api-key: ${{ secrets.LINGODOTDEV_API_KEY }}

设置要求：

1. 添加LINGODOTDEV_API_KEY到仓库密钥（设置 > 密钥和变量 > Actions）
2. 对于PR工作流：在设置 > Actions > 常规中启用"允许GitHub Actions创建和批准拉取请求"

工作流选项：

直接提交翻译：

uses: lingodotdev/lingo.dev@main
with:
  api-key: ${{ secrets.LINGODOTDEV_API_KEY }}

创建包含翻译的拉取请求：

uses: lingodotdev/lingo.dev@main
with:
  api-key: ${{ secrets.LINGODOTDEV_API_KEY }}
  pull-request: true
env:
  GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

可用输入：

阅读文档

Lingo.dev SDK

静态翻译文件适用于UI标签，但用户生成的内容呢？聊天消息、产品描述、支持工单——这些构建时不存在的动态内容无法预翻译。您要么展示未翻译文本，要么构建自定义翻译管道。

Lingo.dev SDK在运行时翻译内容。传入任何文本、对象或HTML，即可获得本地化版本。适用于实时聊天、动态通知或任何部署后才到达的内容。支持JavaScript、PHP、Python和Ruby。

安装：

npm install lingo.dev

使用方法：

import { LingoDotDevEngine } from "lingo.dev/sdk";

const lingoDotDev = new LingoDotDevEngine({
  apiKey: process.env.LINGODOTDEV_API_KEY,
});

// 翻译对象（保持结构）
const translated = await lingoDotDev.localizeObject(
  { greeting: "Hello", farewell: "Goodbye" },
  { sourceLocale: "en", targetLocale: "es" },
);
// { greeting: "Hola", farewell: "Adiós" }

// 翻译文本
const text = await lingoDotDev.localizeText("Hello!", {
  sourceLocale: "en",
  targetLocale: "fr",
});

// 批量翻译到多语言
const results = await lingoDotDev.batchLocalizeText("Hello!", {
  sourceLocale: "en",
  targetLocales: ["es", "fr", "de"],
});

// 翻译聊天记录（保留发言者名称）
const chat = await lingoDotDev.localizeChat(
  [{ name: "Alice", text: "Hello!" }],
  { sourceLocale: "en", targetLocale: "es" },
);

// 翻译HTML（保留标记）
const html = await lingoDotDev.localizeHtml("<h1>欢迎</h1>", {
  sourceLocale: "en",
  targetLocale: "de",
});

// 检测语言
const locale = await lingoDotDev.recognizeLocale("你好世界");
// "zh"

可用SDK：

• JavaScript SDK - Web应用、Node.js
• PHP SDK - PHP、Laravel
• Python SDK - Django、Flask
• Ruby SDK - Rails

阅读文档

Lingo.dev 编译器

传统国际化方案侵入性强。你需要用t()函数包裹每个字符串，发明翻译键名（如home.hero.title.v2），维护并行JSON文件，看着组件因本地化样板代码而膨胀。这个过程如此繁琐，以至于团队往往将国际化推迟到不得不进行大规模重构时。

Lingo.dev编译器消除了这些繁文缛节。直接用英文编写React组件，编译器会在构建时自动检测可翻译字符串并生成本地化变体。无需键名、无需JSON文件、无需包装函数——只需编写普通的React代码，就能自然支持多语言。

安装：

pnpm install @lingo.dev/compiler

认证：

# 推荐：在lingo.dev注册并登录
npx lingo.dev@latest login

# 替代方案：在.env中添加API密钥
LINGODOTDEV_API_KEY=你的密钥

# 或直接使用LLM提供商（Groq、OpenAI、Anthropic、Google）
GROQ_API_KEY=你的密钥

配置（Next.js）：

// 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",
    sourceLocale: "en",
    targetLocales: ["es", "fr", "de"],
    models: "lingo.dev",
    dev: { usePseudotranslator: true },
  });
}

配置（Vite）：

// vite.config.ts
import { lingoCompilerPlugin } from "@lingo.dev/compiler/vite";

export default defineConfig({
  plugins: [
    lingoCompilerPlugin({
      sourceRoot: "src",
      sourceLocale: "en",
      targetLocales: ["es", "fr", "de"],
      models: "lingo.dev",
      dev: { usePseudotranslator: true },
    }),
    react(),
  ],
});

提供者设置：

// app/layout.tsx (Next.js)
import { LingoProvider } from "@lingo.dev/compiler/react";

export default function RootLayout({ children }) {
  return (
    <LingoProvider>
      <html>
        <body>{children}</body>
      </html>
    </LingoProvider>
  );
}

语言切换器：

import { useLocale, setLocale } from "@lingo.dev/compiler/react";

export function LanguageSwitcher() {
  const locale = useLocale();
  return (
    <select value={locale} onChange={(e) => setLocale(e.target.value)}>
      <option value="en">English</option>
      <option value="es">Español</option>
    </select>
  );
}

开发环境： npm run dev（使用伪翻译器，不调用API）

生产环境： 设置usePseudotranslator: false后执行next build

将.lingo/目录提交到版本控制。

核心特性：

• 零运行时性能损耗
• 无需翻译键名或JSON文件
• 无需t()函数或<T>包装组件
• 自动检测JSX中的可翻译文本
• TypeScript支持
• 支持ICU MessageFormat复数形式
• 通过data-lingo-override属性手动覆盖
• 内置翻译编辑器组件

构建模式：

• pseudotranslator：开发模式使用占位翻译（无API成本）
• real：使用LLM生成真实翻译
• cache-only：生产模式使用CI预生成翻译（不调用API）

支持框架：

• Next.js（App Router与React Server Components）
• Vite + React（SPA和SSR）

计划支持更多框架。

阅读文档

贡献指南

欢迎贡献。请遵循以下规范：

1. 问题反馈： 报告错误或请求功能
2. 提交PR： 提交修改
   • 每个PR需附带变更记录：pnpm new（非发布修改用pnpm new:empty）
   • 确保测试通过后再提交
3. 开发环境： 本项目采用pnpm + turborepo单体仓库结构
   • 安装依赖：pnpm install
   • 运行测试：pnpm test
   • 构建：pnpm build

支持： Discord社区

星标历史

如果Lingo.dev对您有帮助，请为我们加星，助力我们达成10,000星目标！

本地化文档

现有翻译版本：

English • 中文 • 日本語 • 한국어 • Español • Français • Русский • Українська • Deutsch • Italiano • العربية • עברית • हिन्दी • Português (Brasil) • বাংলা • فارسی • Polski • Türkçe • اردو • भोजपुरी • অসমীয়া • ગુજરાતી • मराठी • ଓଡ଼ିଆ • ਪੰਜਾਬੀ • සිංහල • தமிழ் • తెలుగు

添加新语言：

1. 使用BCP-47格式将语言代码添加到i18n.json
2. 提交拉取请求

BCP-47语言代码格式： 语言[-文字][-地区]

• 语言：ISO 639-1/2/3（小写）：zh、en、bho
• 文字：ISO 15924（首字母大写）：Hans、Hant、Latn
• 地区：ISO 3166-1 alpha-2（大写）：CN、US、IN
• 示例：zh、pt-BR、zh-Hans、sr-Cyrl-RS