翻译 API

Lingo.dev 的本地化 API 通过已配置的本地化引擎翻译键值数据。一次 HTTP 调用即可完成：传入字符串，返回译文，并自动应用术语表规则、品牌语调和模型选择。

何时使用 API#

如果翻译发生在运行时或后端服务中，而不是在构建阶段，就应该使用本地化 API。

使用场景	示例
动态内容	翻译存储在数据库中的课程描述、课时标题或测验题目
用户生成内容	按需翻译评价、评论或论坛帖子
API 响应	根据用户的语言区域，从后端返回本地化内容
通知	在发送前翻译邮件主题、推送通知或应用内消息

构建时 vs 运行时

如果你的内容存放在静态文件（JSON、Markdown、.strings）中，CLI 或 CI/CD 集成会更适合。API 则是为后端内容本地化而设计的。

前置条件#

创建本地化引擎

每一次 API 调用都会经过一个本地化引擎——它决定使用哪个 LLM 模型、术语表、品牌语调和指令。你可以在 Lingo.dev 控制台中创建。

生成 API 密钥

API 请求通过 X-API-Key 标头进行身份验证。请在 API Keys 页面生成密钥。密钥仅会在创建时显示一次——请务必妥善保管。

本地化内容#

向 localize 端点发送 POST 请求，并附上源语言区域、目标语言区域以及键值数据。完整的请求/响应结构请参阅 API reference。

下面的示例会将一段 JavaScript 课程内容翻译成西班牙语：

javascript

const content = {
  intro: "JavaScript is a programming language that powers the interactive elements of most websites. When you click a button, submit a form, or see content update without the page reloading, JavaScript is making that happen.",
};

const response = await fetch("https://api.lingo.dev/process/localize", {
  method: "POST",
  headers: {
    "X-API-Key": "your_api_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    engineId: "eng_abc123",
    sourceLocale: "en",
    targetLocale: "es",
    data: content,
  }),
});

const { data } = await response.json();
// {
//   intro: "JavaScript es un lenguaje de programacion que impulsa los elementos interactivos de la mayoria de los sitios web. Cuando haces clic en un boton, envias un formulario o ves contenido actualizarse sin que la pagina se recargue, JavaScript lo esta haciendo posible."
// }

键会原样保留：你发送 intro，返回的仍是 intro。引擎只翻译值。

如何组织键#

data 对象是扁平的——每个键都对应一个字符串。组织键时，应让它们携带清晰的语义上下文：

javascript

const content = {
  "variables.intro": "Variables are containers for storing data values. In JavaScript, you declare them with let, const, or var.",
  "variables.example": "Use const for values that never change, and let for values that do.",
  "variables.exercise": "Declare a variable called age and assign it your age as a number.",
};

按语义分组的键有助于本地化引擎生成更连贯的译文。引擎会把单次请求中的所有键视为相关上下文——variables.intro 和 variables.example 一起发送时，通常会比分开发送得到更一致的翻译。

技术术语

像 "const" 或 "let" 这样的术语属于编程语境，不应被翻译。你可以使用术语表将这些术语标记为不可翻译，或将其映射为特定语言区域中的对应表达。如果你在使用 Claude Code 或 Cursor 这类 AI 编码助手，Localization MCP 可以帮助你在开发工作流中配置术语表规则。

在保存时完成本地化#

常见做法是在内容创建或更新时完成翻译，而不是在读取时再翻译。这样一来，当用户请求内容时，译文就已经存储在数据库中了。

javascript

app.post("/api/lessons", async (req, res) => {
  const lesson = await db.lessons.create(req.body);

  const content = {
    intro: lesson.intro,
    example: lesson.example,
    exercise: lesson.exercise,
  };

  const targetLocales = ["es", "fr", "de", "ja"];

  const translations = await Promise.all(
    targetLocales.map(async (targetLocale) => {
      const response = await fetch("https://api.lingo.dev/process/localize", {
        method: "POST",
        headers: {
          "X-API-Key": process.env.LINGODOTDEV_API_KEY,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          sourceLocale: "en",
          targetLocale,
          data: content,
        }),
      });

      const { data } = await response.json();
      return { locale: targetLocale, data };
    })
  );

  await db.lessonTranslations.insertMany(
    translations.map((t) => ({
      lessonId: lesson.id,
      locale: t.locale,
      ...t.data,
    }))
  );

  res.json(lesson);
});

这样，读取本地化内容就只是一次简单的数据库查询——读取时无需再调用 API：

javascript

app.get("/api/lessons/:id", async (req, res) => {
  const locale = req.query.locale || "en";

  if (locale === "en") {
    const lesson = await db.lessons.findById(req.params.id);
    return res.json(lesson);
  }

  const translation = await db.lessonTranslations.findOne({
    lessonId: req.params.id,
    locale,
  });

  res.json(translation);
});

下一步#

API 参考

localize 和 recognize 端点的完整请求/响应结构

何时使用 API#

如果翻译发生在运行时或后端服务中，而不是在构建阶段，就应该使用本地化 API。

使用场景	示例
动态内容	翻译存储在数据库中的课程描述、课时标题或测验题目
用户生成内容	按需翻译评价、评论或论坛帖子
API 响应	根据用户的语言区域，从后端返回本地化内容
通知	在发送前翻译邮件主题、推送通知或应用内消息

构建时 vs 运行时

如果你的内容存放在静态文件（JSON、Markdown、.strings）中，CLI 或 CI/CD 集成会更适合。API 则是为后端内容本地化而设计的。

前置条件#

创建本地化引擎

每一次 API 调用都会经过一个本地化引擎——它决定使用哪个 LLM 模型、术语表、品牌语调和指令。你可以在 Lingo.dev 控制台中创建。

生成 API 密钥

API 请求通过 X-API-Key 标头进行身份验证。请在 API Keys 页面生成密钥。密钥仅会在创建时显示一次——请务必妥善保管。

本地化内容#

向 localize 端点发送 POST 请求，并附上源语言区域、目标语言区域以及键值数据。完整的请求/响应结构请参阅 API reference。

下面的示例会将一段 JavaScript 课程内容翻译成西班牙语：

javascript

const content = {
  intro: "JavaScript is a programming language that powers the interactive elements of most websites. When you click a button, submit a form, or see content update without the page reloading, JavaScript is making that happen.",
};

const response = await fetch("https://api.lingo.dev/process/localize", {
  method: "POST",
  headers: {
    "X-API-Key": "your_api_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    engineId: "eng_abc123",
    sourceLocale: "en",
    targetLocale: "es",
    data: content,
  }),
});

const { data } = await response.json();
// {
//   intro: "JavaScript es un lenguaje de programacion que impulsa los elementos interactivos de la mayoria de los sitios web. Cuando haces clic en un boton, envias un formulario o ves contenido actualizarse sin que la pagina se recargue, JavaScript lo esta haciendo posible."
// }

键会原样保留：你发送 intro，返回的仍是 intro。引擎只翻译值。

如何组织键#

data 对象是扁平的——每个键都对应一个字符串。组织键时，应让它们携带清晰的语义上下文：

javascript

const content = {
  "variables.intro": "Variables are containers for storing data values. In JavaScript, you declare them with let, const, or var.",
  "variables.example": "Use const for values that never change, and let for values that do.",
  "variables.exercise": "Declare a variable called age and assign it your age as a number.",
};

技术术语

在保存时完成本地化#

常见做法是在内容创建或更新时完成翻译，而不是在读取时再翻译。这样一来，当用户请求内容时，译文就已经存储在数据库中了。

javascript

app.post("/api/lessons", async (req, res) => {
  const lesson = await db.lessons.create(req.body);

  const content = {
    intro: lesson.intro,
    example: lesson.example,
    exercise: lesson.exercise,
  };

  const targetLocales = ["es", "fr", "de", "ja"];

  const translations = await Promise.all(
    targetLocales.map(async (targetLocale) => {
      const response = await fetch("https://api.lingo.dev/process/localize", {
        method: "POST",
        headers: {
          "X-API-Key": process.env.LINGODOTDEV_API_KEY,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          sourceLocale: "en",
          targetLocale,
          data: content,
        }),
      });

      const { data } = await response.json();
      return { locale: targetLocale, data };
    })
  );

  await db.lessonTranslations.insertMany(
    translations.map((t) => ({
      lessonId: lesson.id,
      locale: t.locale,
      ...t.data,
    }))
  );

  res.json(lesson);
});

这样，读取本地化内容就只是一次简单的数据库查询——读取时无需再调用 API：

javascript

app.get("/api/lessons/:id", async (req, res) => {
  const locale = req.query.locale || "en";

  if (locale === "en") {
    const lesson = await db.lessons.findById(req.params.id);
    return res.json(lesson);
  }

  const translation = await db.lessonTranslations.findOne({
    lessonId: req.params.id,
    locale,
  });

  res.json(translation);
});

下一步#

API 参考

localize 和 recognize 端点的完整请求/响应结构