JavaScript SDK

Lingo.dev JavaScript SDK는 웹 애플리케이션, Node.js 서버 및 프론트엔드 프레임워크에 실시간 AI 기반 번역 기능을 추가합니다. 이 SDK는 채팅 메시지, 사용자 댓글, 즉각적인 번역이 필요한 실시간 데이터와 같은 동적 콘텐츠를 처리합니다.

Lingo.dev CLI를 사용한 정적 파일 현지화와 달리, SDK는 콘텐츠를 필요에 따라 처리하므로 콘텐츠가 지속적으로 변경되는 채팅 애플리케이션, 이메일 클라이언트 및 소셜 미디어 도구에 이상적입니다.

설치

npm install lingo.dev

기본 설정

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

const lingoDotDev = new LingoDotDevEngine({
  apiKey: "your-api-key-here",
});

텍스트 번역

간단한 텍스트 번역:

const result = await lingoDotDev.localizeText("Hello, world!", {
  sourceLocale: "en",
  targetLocale: "es",
});
// 반환값: "¡Hola Mundo!"

여러 언어로 번역:

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

객체 번역

구조화된 데이터 번역:

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

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

이 메서드는 중첩된 객체를 처리하고 텍스트 값을 번역하는 동시에 원래 구조를 유지합니다.

채팅 번역

대화 배열 번역:

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",
});
// 동일한 구조로 번역된 대화를 반환합니다

채팅 메서드는 텍스트 내용만 번역하면서 사용자 이름과 같은 메타데이터를 보존합니다.

HTML 번역

마크업을 보존하면서 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 번역은 텍스트 내용만 번역하면서 모든 태그, 속성 및 구조를 유지합니다.

언어 감지

소스 언어 자동 감지:

const locale = await lingoDotDev.recognizeLocale("Bonjour le monde");
// Returns: 'fr'

자동 감지와 함께 사용:

const result = await lingoDotDev.localizeText("Bonjour le monde", {
  sourceLocale: null, // 자동 감지
  targetLocale: "en",
});
// Returns: "Hello world"

언어 감지는 처리 시간이 추가되므로 소스 언어를 알 수 없는 경우에만 사용하십시오.

구성 옵션

SDK 동작 구성:

const lingoDotDev = new LingoDotDevEngine({
  apiKey: "your-api-key-here",
  batchSize: 100, // API 요청당 최대 항목 수 (기본값: 50, 최대: 250)
  idealBatchItemSize: 1000, // 배치당 목표 단어 수 (기본값: 500, 최대: 2500)
});

배치 크기는 각 API 요청에서 전송되는 항목 수를 제어합니다. 값이 높을수록 API 호출은 줄어들지만 요청 크기가 증가합니다.

이상적인 배치 항목 크기는 최적의 처리 효율성을 위한 목표 단어 수를 제어합니다.

번역 매개변수

속도 대 품질 제어:

const result = await lingoDotDev.localizeText("Hello world", {
  sourceLocale: "en",
  targetLocale: "es",
  fast: true, // 품질보다 속도 우선
});

fast 매개변수는 시간에 민감한 애플리케이션을 위해 잠재적으로 품질이 저하될 수 있지만 더 빠른 번역을 가능하게 합니다.

진행 상황 추적

대규모 번역 작업 모니터링:

await lingoDotDev.localizeObject(
  largeObject,
  { sourceLocale: "en", targetLocale: "es" },
  (progress) => {
    console.log(`Translation progress: ${progress}%`);
    // UI 진행 표시줄 업데이트
  },
);

진행 상황 콜백은 대규모 번역 작업에 대한 실시간 피드백을 제공하며, 사용자 인터페이스 업데이트에 유용합니다.

오류 처리

적절한 오류 처리 구현:

try {
  const result = await lingoDotDev.localizeText("Hello", {
    sourceLocale: "en",
    targetLocale: "es",
  });
} catch (error) {
  console.error("Translation failed:", error.message);
  // Handle error appropriately
}

SDK는 네트워크 문제에 대한 자동 재시도 기능을 포함하고 있지만, 애플리케이션 수준의 오류 처리는 여전히 중요합니다.