SDK v0 연동 유지 관리

LingoDotDevEngine 헬퍼를 이해하고 마이그레이션 과정에서도 입력, 출력, 배치 처리, 취소 동작을 그대로 유지하세요.

LingoDotDevEngine를 사용하는 애플리케이션은 객체 번역 외의 기능에도 의존할 수 있습니다. 요청을 청크로 나누거나 배열을 재구성하고, HTML을 파싱하기도 합니다. 마이그레이션할 때는 이러한 동작이 유지되도록 명시적으로 챙겨야 합니다. 가져오기 구문만 바꾼다고 이 기능들까지 대체되지는 않습니다.

이 레퍼런스는 lingo.dev 0.138.10을 다룹니다. 이 버전의 lingo.dev/sdk 진입점은 @lingo.dev/_sdk 0.17.3을 다시 내보냅니다. 호출 지점을 점검하는 동안에는 애플리케이션의 Lockfile에 기록된 버전을 유지하세요. 새로운 서버 워크플로에는 자바스크립트 API 가이드를 참고하세요.

기존 객체 번역 호출 #

기존 서버 측 호출 형식은 다음과 같습니다.

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

const apiKey = process.env.LINGO_API_KEY;
const engineId = process.env.LINGO_ENGINE_ID;
if (!apiKey || !engineId) throw new Error("Configure a key and localization engine ID");

const client = new LingoDotDevEngine({ apiKey, engineId });
const translated = await client.localizeObject(
  { greeting: "Welcome back" },
  { sourceLocale: "en", targetLocale: "es" },
);

이 헬퍼는 번역된 레코드를 바로 반환합니다. 인증 정보는 서버에 보관하세요. 문서 작업은 생성, 시작, 다운로드로 이어지는 별도의 수명 주기를 따릅니다. 작업 생성 응답은 이 헬퍼가 반환하는 번역된 레코드와 다릅니다.

생성자 및 배치 제어 옵션 #

옵션기존 동작
apiKey필수 문자열로, 생성자에서 유효성을 검사합니다.
apiUrlAPI 기본 URL을 재정의합니다.
engineId번역 요청과 함께 전송되는 로컬라이제이션 엔진 선택값입니다. 선택 사항입니다.
batchSize기본값 25, 최댓값 250.
idealBatchItemSize기본값 250, 최댓값 2500.
maxRetries기본값 3.
retryDelayMs기본값 500밀리초.

배치 옵션은 클라이언트가 청크를 구성하는 방식을 제어하며, 애플리케이션 전체의 동시성을 제어하지는 않습니다. 재시도 헬퍼는 네트워크 오류와 5xx 오류가 발생하면 지수적으로 늘어나는 대기 시간에 무작위 변동을 적용해 재시도합니다. 의도적인 중단이나 일반적인 4xx 응답은 이 헬퍼에서 재시도하지 않습니다. 인식이나 계정 조회 같은 다른 작업은 별도의 요청 경로를 사용하므로, 하나의 재시도 정책이 모든 메서드에 적용된다고 가정하지 마세요.

헬퍼 입력 및 반환값 #

헬퍼입출력 규약
localizeObject(object, params, progressCallback?, signal?)레코드를 입력받아 번역된 레코드를 반환합니다.
localizeText(text, params, progressCallback?, signal?)텍스트를 필드로 감싸고 번역된 문자열을 반환합니다.
batchLocalizeText(text, { sourceLocale, targetLocales, fast? }, signal?)로캘마다 텍스트 요청을 실행하고, 요청한 로캘 순서대로 문자열을 반환합니다.
localizeStringArray(strings, params)임시 키를 사용해 문자열 배열을 재구성합니다. 공개된 신호 매개변수는 없습니다.
localizeChat(messages, params, progressCallback?, signal?){ name, text } 메시지의 text를 번역하고 메시지 이름은 유지합니다.
localizeHtml(html, params, progressCallback?, signal?)jsdom로 HTML을 파싱하고, 선택한 콘텐츠를 번역한 뒤 결과를 직렬화합니다.
recognizeLocale(text, signal?)인식 결과의 로캘 값을 반환합니다.
estimate(items, signal?){ targetLocale, sourceChars } 항목을 입력받아 대략적인 합계와 로캘별 비용을 반환합니다.
whoami(signal?)일반적인 계정 요청 실패 응답에는 { email, id } 또는 null를 반환합니다. 서버 오류가 발생하면 예외를 던질 수 있습니다.

공통 번역 매개변수는 sourceLocale(감지를 위해 널 값 허용), targetLocale, 선택 사항인 fast, 로캘별 참조 데이터, 키별 힌트 배열, filePath, triggerType(cli 또는 ci)입니다. 로캘은 사용 전에 정규화됩니다. 새 요청 스키마에 매핑할 때도 각 입력의 의미를 유지하세요.

진행 상황 콜백은 완료 비율과 원본 청크 및 처리된 청크 정보를 포함해 클라이언트 청크의 완료 현황을 전달합니다. 영속성이 보장되는 백그라운드 작업 알림은 아닙니다. AbortSignal는 클라이언트 작업을 중단하지만, 서버가 이미 수락한 처리를 되돌릴 수는 없습니다.

HTML 동작을 명시적으로 유지하기 #

HTML 헬퍼는 script 및 style 외부의 텍스트 노드와 meta.content, img.alt, input.placeholder, a.title를 번역합니다. 문서 언어를 대상 언어로 설정하고 DOM을 직렬화합니다. 모든 속성을 번역하거나 원본 바이트를 그대로 보존하지는 않습니다.

실제 서버 런타임에서 이 헬퍼를 테스트하고, 동적으로 가져오는 jsdom 모듈이 정상적으로 해석되는지도 확인하세요. HTML 호출을 다른 변환 방식으로 마이그레이션하기 전에 링크, 구조적 마크업, 선택된 속성, 직렬화된 출력을 비교하세요. 구조화된 JSON 요청만으로는 이러한 HTML 처리 단계가 수행되지 않습니다.

ReplexicaEngine와 LingoEngine는 호환성을 위한 별칭으로 LingoDotDevEngine를 확장하며, 사용 중단 예정 경고를 출력합니다. 별칭 경고를 없애는 것은 이름을 바꾸는 작업일 뿐, 동작 마이그레이션까지 완료하는 것은 아닙니다.

애플리케이션을 문서 작업으로 전환하기 #

새로운 연동에는 API 작업 수명 주기를 사용하세요. 객체 콘텐츠를 인라인 JSON 문서에 넣고 작업을 시작한 뒤, 완료된 각 대상 결과를 다운로드하세요. 애플리케이션이 결과를 수락할 때까지 작업 ID를 원본 리비전과 함께 보관하세요.

현재 텍스트 감싸기, 배열 순서, HTML 파싱, 배치 처리, 진행 상황 콜백에 의존하는 애플리케이션 동작을 모두 유지하세요. 파일 번역에는 해당 문서 형식을 사용할 수 있습니다. 전송 방식을 바꾼다고 클라이언트 측 변환이나 재시도 동작까지 자동으로 재현되지는 않습니다.

애플리케이션의 저장 처리를 새 흐름으로 전환하기 전에 결과 데이터와 실패 처리 방식을 비교하세요. 워크플로 가이드에서는 부분 결과와 요청 순서와 다르게 완료되는 경우를 다룹니다.