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!']

마크업을 보존하면서 HTML 번역:

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

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

HTML 번역은 텍스트 내용만 번역하면서 모든 태그, 속성 및 구조를 유지합니다.

채팅 번역

화자 이름을 유지하면서 채팅 메시지를 번역합니다. 각 메시지는 "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}`);
}
// Output:
// 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);
// Output: "<div>Hola <strong>mundo</strong></div>"

진행 상황 추적

콜백을 통해 번역 진행 상황을 모니터링합니다. 대규모 번역 작업 중 UI 업데이트에 유용합니다.

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}%`);
  },
);
// Output:
// 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, // Prioritize speed over quality
});
console.log(result);
// Output: "Hola mundo"

구성

배치 처리 동작을 제어합니다. SDK는 항목 수와 단어 수 제약에 따라 대용량 페이로드를 분할합니다.

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

const lingoDotDev = new LingoDotDevEngine({
  apiKey: process.env.LINGODOTDEV_API_KEY,
  batchSize: 100, // Max items per API request (default: 50, max: 250)
  idealBatchItemSize: 1000, // Target word count per batch (default: 500, max: 2500)
});

const result = await lingoDotDev.localizeText("Configuration test", {
  sourceLocale: "en",
  targetLocale: "es",
});
console.log(result);
// Output: "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);
// Output: '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, // Auto-detect
  targetLocale: "en",
});
console.log(result);
// Output: "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("Translation failed:", error.message);
  // Handle error appropriately
}