Lingo.dev - 面向 LLM 驱动的本地化的开源 i18n 工具包

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

---

快速开始

工具	使用场景	快速命令
MCP	React 应用的 AI 辅助 i18n 设置	提示词: Set up i18n
CLI	翻译 JSON、YAML、markdown、CSV、PO 文件	npx lingo.dev@latest run
CI/CD	GitHub Actions 中的自动化翻译管道	uses: lingodotdev/lingo.dev@main
SDK	动态内容的运行时翻译	npm install lingo.dev
编译器	无需 i18n 包装器的构建时 React 本地化	withLingo() 插件

---

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 Agents
• Codex (OpenAI)

支持的框架:

• Next.js (App Router & Pages Router v13-16)
• TanStack Start (v1)
• React Router (v7)

用法:

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

Set up i18n with the following locales: en, es, and pt-BR. The default locale is '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 Engine）。对于自定义 LLM 提供商：

{
  "provider": {
    "id": "openai",
    "model": "gpt-4o-mini",
    "prompt": "Translate from {source} to {target}"
  }
}

支持的 LLM 提供商:

• Lingo.dev Engine (推荐)
• OpenAI
• Anthropic
• Google
• Mistral
• OpenRouter
• Ollama

阅读文档 →

---

Lingo.dev CI/CD

翻译功能总是处于“即将完成”的状态。工程师合并代码时常常忘记更新本地化文件。质量保证（Quality Assurance，简称 QA）在预发布环境发现缺失的翻译——更糟的是，用户在生产环境中发现了它们。根本原因在于：翻译是一个手动步骤，在截止日期的压力下很容易被跳过。

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

支持的平台：

• GitHub Actions
• GitLab CI/CD
• Bitbucket Pipelines

GitHub Actions 设置：

创建 .github/workflows/translate.yml 文件：

name: Translate
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 添加到仓库的 Secrets 中（设置 > Secrets and variables > Actions）
2. 对于 PR 工作流：在 设置 > Actions > General 中启用 "Allow GitHub Actions to create and approve pull requests"

工作流选项：

直接提交翻译：

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

创建包含翻译的拉取请求（Pull Request，简称 PR）：

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

可用输入参数：

输入参数	默认值	描述
api-key	(必填)	Lingo.dev API 密钥
pull-request	false	创建 PR 而非直接提交
commit-message	"feat: update translations via @LingoDotDev"	自定义提交信息
pull-request-title	"feat: update translations via @LingoDotDev"	自定义 PR 标题
working-directory	"."	运行目录
parallel	false	启用并行处理

阅读文档 →

---

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>Welcome</h1>", {
  sourceLocale: "en",
  targetLocale: "de",
});

// 检测语言
const locale = await lingoDotDev.recognizeLocale("Bonjour le monde");
// "fr"

可用的 SDK：

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

阅读文档 →

---

Lingo.dev 编译器

传统的国际化（i18n）方案侵入性强。你需要用 t() 函数包装每个字符串，发明翻译键（如 home.hero.title.v2），维护并行的 JSON 文件，并看着你的组件因本地化样板代码而膨胀。这非常繁琐，以至于团队常常将国际化工作推迟，直到它变成一次大规模重构。

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

安装：

pnpm install @lingo.dev/compiler

认证：

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

# 备选：将 API 密钥添加到 .env 文件
LINGODOTDEV_API_KEY=your_key_here

Lingo.dev

Lingo 是一个编译器，可将你的 React 应用自动翻译成多种语言。它直接在构建时处理翻译，因此你的应用在运行时无需承担任何翻译开销。

工作原理

1. 检测：Lingo 在构建时扫描你的代码，自动识别 JSX 中的所有可翻译文本
2. 翻译：使用大型语言模型（LLM）将文本翻译成目标语言
3. 编译：为每种语言生成独立的、完全本地化的构建版本

快速开始

安装：

npm install @lingo.dev/compiler

环境变量：

# 使用 Lingo.dev 托管的模型（推荐）
LINGO_API_KEY=your_key

# 或使用直接的 LLM 提供商（Groq、OpenAI、Anthropic、Google）
GROQ_API_KEY=your_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(),
  ],
});

Provider 设置：

// 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（使用 React 服务器组件的 App Router）
• Vite + React（SPA 和 SSR）

计划支持更多框架。

阅读文档 →

---

贡献

欢迎贡献。请遵循以下指南：

1. 问题： 报告错误或请求功能
2. 拉取请求： 提交更改
   • 每个 PR 都需要一个变更集：pnpm new（或对于非发布更改使用 pnpm new:empty）
   • 提交前确保测试通过
3. 开发： 这是一个 pnpm + turborepo 单体仓库
   • 安装依赖：pnpm install
   • 运行测试：pnpm test
   • 构建：pnpm build

支持： Discord 社区

Star 历史

如果你觉得 Lingo.dev 有用，请给我们一个 star，帮助我们达到 10,000 个 star！

本地化文档

可用翻译：

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（小写）：en、zh、bho
• 脚本：ISO 15924（首字母大写）：Hans、Hant、Latn
• 区域：ISO 3166-1 alpha-2（大写）：US、CN、IN
• 示例：en、pt-BR、zh-Hans、sr-Cyrl-RS

Lingo.dev 快速上手指南

Lingo.dev 是一个开源的 AI 驱动国际化（i18n）工具包，提供 MCP、CLI、CI/CD、SDK 和编译器等多种工具，帮助开发者高效实现多语言本地化。

环境准备

系统要求

• Node.js: 版本 18 或更高
• 包管理器: npm、yarn、pnpm 或 bun
• Git: 用于版本控制
• IDE: 支持 Claude Code、Cursor、GitHub Copilot Agents 或 Codex（如需使用 MCP 功能）

前置依赖

• 一个可用的 LLM 服务 API 密钥（可选，可使用 Lingo.dev 默认引擎）
• 对于 CI/CD 使用：需要 GitHub、GitLab 或 Bitbucket 账户

安装步骤

方式一：CLI 工具（推荐）

# 全局安装 CLI
npm install -g lingo.dev@latest

# 或使用 npx 直接运行
npx lingo.dev@latest init

方式二：SDK（用于运行时翻译）

# 在项目中安装 SDK
npm install lingo.dev

方式三：编译器（用于 React 应用）

# 安装编译器
pnpm install @lingo.dev/compiler

方式四：CI/CD（GitHub Actions）

在 .github/workflows/translate.yml 中添加：

- name: Lingo.dev
  uses: lingodotdev/lingo.dev@main

基本使用

1. CLI 快速开始

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

# 2. 编辑生成的 i18n.json 文件
# 配置源语言和目标语言

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

配置示例 (i18n.json)：

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "zh-CN",
    "targets": ["en", "ja", "ko"]
  },
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"]
    }
  }
}

2. MCP 使用（AI 辅助）

在支持的 IDE 中配置 MCP 服务器后，直接向 AI 助手输入：

为我的 React 应用设置国际化，支持以下语言：zh-CN, en, ja。默认语言是 'zh-CN'。

AI 助手将自动：

• 配置基于语言的路由
• 设置语言切换组件
• 实现自动语言检测
• 生成必要的配置文件

3. SDK 基本示例

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

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

// 翻译文本
const translated = await lingoDotDev.localizeText("你好，世界！", {
  sourceLocale: "zh-CN",
  targetLocale: "en",
});
// 输出: "Hello, world!"

4. 编译器集成（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: "zh-CN",
    targetLocales: ["en", "ja"],
  });
}

5. CI/CD 自动化

创建 GitHub Actions 工作流文件 .github/workflows/translate.yml：

name: Translate
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 }}

下一步

• 访问 官方文档 获取详细指南
• 查看各工具的专属文档部分：
  • MCP 文档
  • CLI 文档
  • CI/CD 文档
  • SDK 文档
  • 编译器文档

提示：首次使用建议从 CLI 开始，熟悉基本流程后再集成到开发工作流中。