환영합니다

콘텐츠는 한 언어로 되어 있지만, 사용자는 다양한 언어로 읽습니다. 이 API는 그 간극을 코드로 메우기 위해 존재합니다. 텍스트를 보내면 번역된 결과를 돌려받고, 모든 번역은 한 번만 설정하면 되는 로컬라이제이션 엔진을 거칩니다. 이 엔진은 모든 호출에 용어집, 브랜드 보이스, 지침, 로캘별 모델 선택을 적용하므로, 결과물은 범용 모델이 임의로 추정한 방식이 아니라 팀이 의도한 방식 그대로 읽히게 됩니다.

이제 남는 결정은 하나입니다. 한 번에 얼마나 번역할 것인지입니다. 하나의 로캘을 한 번의 요청으로 번역해 응답에서 바로 결과를 받을 수도 있고, 여러 로캘을 플랫폼에 넘겨 앱의 응답성은 유지한 채 각 로캘을 독립적인 백그라운드 작업으로 처리할 수도 있습니다. 이 페이지에서는 기본 URL, 그 한 가지 결정, 그리고 다음에 어디를 보면 되는지까지 안내합니다.

이 API의 전제 조건

이 문서는 프로그래밍 방식으로 번역할 때 참고하는 레퍼런스입니다. 대시보드가 아니라 자체 코드나 파이프라인에서 로컬라이즈하기로 이미 결정했고, API 키도 가지고 있다는 전제하에 작성되었습니다. 플랫폼이 처음이신가요? 가장 먼저 이해해야 할 개념은 로컬라이제이션 엔진이며, 여기의 모든 기능은 이를 중심으로 동작합니다.

이 페이지에서 다루는 내용

기본 URL
번역하는 두 가지 방식
비동기: 여러 로캘을 작업으로 처리
동기: 요청 하나, 응답 하나
다음 단계

기본 URL#

이 레퍼런스의 모든 REST 엔드포인트는 하나의 호스트 아래에 있습니다:

text

https://api.lingo.dev

모든 요청에는 X-API-Key 헤더도 포함됩니다. 이 키는 조직 단위로 범위가 지정되며, 생성 시 한 번만 표시됩니다. 전송 방식에 대한 전체 규칙은 Authentication에서, 요청이 거부됐을 때 어떤 응답이 반환되는지는 Errors and status codes에서 확인할 수 있습니다.

번역하는 두 가지 방식#

두 모드 모두 같은 엔진, 같은 용어집, 같은 브랜드 보이스를 기반으로 동작합니다. 달라지는 것은 기다림을 누가 감당하느냐뿐입니다.

동기식 호출은 하나의 로캘 쌍을 번역하고, 번역된 데이터를 응답으로 바로 반환합니다. 가장 단순한 방식입니다. 요청 하나, 응답 하나, 그리고 별도로 운영할 엔드포인트도 필요 없습니다. 하나의 로캘만 필요하고 한 번의 왕복 시간을 기다릴 수 있다면 적합한 선택입니다.

하지만 콘텐츠가 단 하나의 로캘에만 배포되는 경우는 드뭅니다. 교육 모듈 하나가 14개 언어로 제공되기도 하고, CMS 항목 하나가 판매 중인 모든 시장으로 확장되기도 합니다. 로캘마다 동기 호출을 하나씩 보내면 14번의 왕복과, 그중 하나가 실패했을 때의 재시도 로직까지 직접 감당해야 합니다. 반대로 모두를 한 번의 동기 호출로 처리하려 하면 가장 느린 작업이 끝날 때까지 전체가 묶이게 됩니다. 따라서 API는 비동기 모드도 제공합니다. 대상 로캘과 함께 콘텐츠를 한 번 POST하면 즉시 202를 받고, 플랫폼이 각 로캘을 독립적인 백그라운드 작업으로 번역합니다. 그동안 앱은 계속 응답성을 유지하고, 재시도와 실패 격리는 플랫폼이 맡습니다.

작업 규모가 너무 크거나, 시간이 너무 오래 걸리거나, 대상 로캘이 너무 많아 기다릴 수 없다면 async를 선택하세요. 하나의 로캘 쌍 결과만 응답 하나로 받으면 충분하다면 sync가 맞습니다. 아래에서는 다뤄야 할 내용이 더 많은 async 관련 페이지를 먼저 소개하지만, 그렇다고 그것만이 "진짜" API인 것은 아닙니다. 둘 다 같은 엔진의 서로 다른 형태일 뿐입니다.