JavaScript SDK - Lingo.dev SDK

简介

Lingo.dev JavaScript SDK 为网页应用、Node.js 服务器和前端框架添加了实时 AI 驱动的翻译功能。该 SDK 处理动态内容，例如聊天消息、用户评论和需要即时翻译的实时数据。

与使用 Lingo.dev CLI 的静态文件本地化不同，SDK 按需处理内容，非常适合聊天应用、电子邮件客户端和内容不断变化的社交媒体工具。

安装

npm install lingo.dev

基本设置

SDK 需要从 Lingo.dev 获取 API 密钥。

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

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

文本翻译

将简单的文本字符串翻译为目标语言。

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

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

const result = await lingoDotDev.localizeText("Hello, world!", {
  sourceLocale: "en",
  targetLocale: "es",
});
console.log(result);
// 输出: "¡Hola Mundo!"

对象翻译

在保留结构的同时翻译嵌套对象。SDK 会递归处理所有字符串值。

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

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

const content = {
  greeting: "Hello",
  farewell: "Goodbye",
  message: "Welcome to our platform",
};

const translated = await lingoDotDev.localizeObject(content, {
  sourceLocale: "en",
  targetLocale: "es",
});
console.log(translated);
// 输出: { greeting: "Hola", farewell: "Adiós", message: "Bienvenido a nuestra plataforma" }

批量翻译为多种语言

在一次调用中将内容翻译为多种目标语言。返回一个数组，每个目标语言对应一个结果。

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

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

const results = await lingoDotDev.batchLocalizeText("Hello, world!", {
  sourceLocale: "en",
  targetLocales: ["es", "fr", "de"],
});
console.log(results);
// 输出: ['¡Hola Mundo!', 'Bonjour le monde!', 'Hallo Welt!']

聊天翻译

在保留发言者姓名的同时翻译聊天消息。每条消息必须包含 "name" 和 "text" 字段。

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

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

const conversation = [
  { name: "Alice", text: "Hello!" },
  { name: "Bob", text: "How are you?" },
  { name: "Alice", text: "I'm doing well, thanks!" },
];

const translated = await lingoDotDev.localizeChat(conversation, {
  sourceLocale: "en",
  targetLocale: "es",
});

for (const message of translated) {
  console.log(`${message.name}: ${message.text}`);
}
// 输出:
// Alice: ¡Hola!
// Bob: ¿Cómo estás?
// Alice: ¡Me va bien, gracias!

HTML 翻译

在保留标记的同时翻译 HTML。保持所有标签、属性和结构，仅翻译文本内容。

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

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

const html = "<div>Hello <strong>world</strong></div>";

const translated = await lingoDotDev.localizeHtml(html, {
  sourceLocale: "en",
  targetLocale: "es",
});
console.log(translated);
// 输出: "<div>Hola <strong>mundo</strong></div>"

进度跟踪

通过回调函数监控翻译进度。在进行大规模翻译操作时，这对于更新用户界面非常有用。

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

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

const largeObject = {
  page1: "Welcome to our application",
  page2: "This is the second page",
  page3: "Here is more content",
  page4: "Final page of content",
};

await lingoDotDev.localizeObject(
  largeObject,
  { sourceLocale: "en", targetLocale: "es" },
  (progress) => {
    console.log(`Translation progress: ${progress}%`);
  },
);
// 输出:
// Translation progress: 25%
// Translation progress: 50%
// Translation progress: 75%
// Translation progress: 100%

翻译参数

针对时间敏感型应用的速度与质量控制。

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

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

const result = await lingoDotDev.localizeText("Hello world", {
  sourceLocale: "en",
  targetLocale: "es",
  fast: true, // 优先速度而非质量
});
console.log(result);
// 输出: "Hola mundo"

配置

控制批处理行为。SDK 根据项目数量和字数限制拆分大型负载。

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

const lingoDotDev = new LingoDotDevEngine({
  apiKey: process.env.LINGODOTDEV_API_KEY,
  batchSize: 100, // 每次 API 请求的最大项目数（默认: 50，最大: 250）
  idealBatchItemSize: 1000, // 每批目标字数（默认: 500，最大: 2500）
});

const result = await lingoDotDev.localizeText("Configuration test", {
  sourceLocale: "en",
  targetLocale: "es",
});
console.log(result);
// 输出: "Prueba de configuración"

语言检测

检测文本字符串的语言。仅在源语言未知时使用，因为检测会增加处理时间。

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

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

const locale = await lingoDotDev.recognizeLocale("Bonjour le monde");
console.log(locale);
// 输出: 'fr'

使用自动检测：

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

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

const result = await lingoDotDev.localizeText("Bonjour le monde", {
  sourceLocale: null, // 自动检测
  targetLocale: "en",
});
console.log(result);
// 输出: "Hello world"

错误处理

SDK 包含针对网络问题的自动重试功能。对于其他失败情况，请实现应用级错误处理。

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

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

try {
  const result = await lingoDotDev.localizeText("Hello", {
    sourceLocale: "en",
    targetLocale: "es",
  });
  console.log(result);
} catch (error) {
  console.error("翻译失败:", error.message);
  // 适当处理错误
}