Recognize

텍스트는 있는데, 그 텍스트가 어떤 언어인지 확실한 정보가 없는 경우가 있습니다. 사용자가 직접 입력한 댓글일 수도 있고, 업로드된 파일의 문자열이거나, 들어온 지원 티켓 본문일 수도 있죠. 이 텍스트를 라우팅하거나 번역하거나, 심지어 제대로 렌더링하기 전에 먼저 알아야 할 것이 있습니다. 바로 로캘입니다. 어떤 언어인지, 어느 지역인지, 어떤 스크립트인지, 어느 방향으로 읽는지까지요. Recognize는 이 공백을 한 번의 호출로 메워줍니다. 텍스트를 보내면, 그 텍스트가 허용하는 범위 안에서 최대한 구체적인 구조화된 로캘 식별 정보를 돌려받을 수 있습니다.

이 페이지에서는 이 엔드포인트 전체를 다룹니다. 요청과 응답, 반환되는 모든 필드, 언어 바인딩, 그리고 텍스트만으로 지역이나 스크립트를 특정할 수 없을 때 응답이 어떻게 동작하는지까지 설명합니다. 이 호출은 동기식입니다. 텍스트를 POST하면 분석이 끝날 때까지 요청이 블로킹되고, 응답은 같은 왕복 요청 안에서 반환됩니다. 인증은 공통 X-API-Key 헤더로 처리되며, 키 동작 방식은 Authentication에서 확인할 수 있습니다. 오류는 모두 standard error model을 따릅니다.

요청#

POST /process/recognize

필수인 값은 text뿐입니다. labelLocale는 응답에 포함되는 사람이 읽기 쉬운 label의 언어를 결정합니다. 예를 들어 이를 de로 설정하면, 프랑스어 입력의 레이블이 영어가 아니라 독일어로 반환됩니다. 감지 결과 자체가 바뀌는 것은 아니고, 결과를 어떤 이름으로 보여줄지만 달라집니다.

{
  "text": "Bonjour le monde",
  "labelLocale": "en"
}

응답#

{
  "locale": "fr",
  "language": "fr",
  "region": null,
  "script": null,
  "label": "French",
  "direction": "ltr"
}

이 응답 형태에서 특히 눈여겨볼 점은 두 가지입니다. 단순히 정보를 보여주는 데서 그치지 않고, 결과를 실제로 활용 가능하게 만드는 요소들이죠.

첫째, 여기 나오는 모든 코드는 Lingo.dev가 임의로 만든 값이 아니라 공개 표준입니다. locale는 BCP-47, language는 ISO 639 하위 태그, region는 ISO 3166, script는 ISO 15924입니다. 그래서 이미 로캘 파싱에 사용 중인 어떤 도구로도 이 출력을 바로 소비할 수 있습니다. i18n 라이브러리든, Intl 호출이든, CLDR 조회든 마찬가지입니다. 별도의 독점 코드 체계에 맞출 필요 없이, 스택 전반에서 이미 쓰고 있는 동일한 식별자를 그대로 받게 됩니다.

둘째, region와 script가 nullable인 데에는 분명한 이유가 있습니다. 이 값들은 텍스트가 실제로 그것을 보여줄 때에만 채워집니다. 바로 다음 두 섹션에서 다룰 내용이기도 하고, 이 엔드포인트가 추측하지 않도록 만드는 핵심 특성이기도 합니다.

지역과 스크립트는 텍스트가 이를 보여줄 때에만 반환됩니다#

언어 감지기에서 가장 걱정되는 점은 과하게 단정하는 것입니다. 텍스트가 전혀 입증하지 않은 지역이나 문자 체계를 확정된 것처럼 붙여 버리고, 그 추정값을 바탕으로 로직을 짜게 될 수 있으니까요. Recognize는 정반대로 동작합니다. 근거가 충분할 때에만 하위 태그를 반환하고, 그렇지 않으면 null을 반환합니다.

텍스트 안에 지역을 드러내는 단서가 있을 때, 예를 들어 브라질 포르투갈어 어휘가 포함되어 있다면, 응답에는 전체 태그(pt-BR)가 들어갑니다. 반대로 지역 변형을 구분할 수 없다면 언어 하위 태그(pt)만 반환됩니다.

{
  "locale": "pt-BR",
  "language": "pt",
  "region": "BR",
  "script": null,
  "label": "Portuguese (Brazil)",
  "direction": "ltr"
}

{
  "locale": "pt",
  "language": "pt",
  "region": null,
  "script": null,
  "label": "Portuguese",
  "direction": "ltr"
}

같은 언어라도 정직한 답은 두 가지일 수 있습니다. 첫 번째 텍스트에는 지역을 특정할 만큼 충분한 단서가 있었지만, 두 번째 텍스트에는 없었습니다. 그래서 region은 null이 되고, locale는 pt로 축약됩니다. script도 반대 방향에서 같은 규칙을 따릅니다. 해당 언어의 기본 문자 체계라면, 예를 들어 프랑스어의 라틴 문자처럼, null이 되고, 스크립트가 실제 구분 포인트일 때만 명시됩니다.

그래서 실제로 기준이 되어야 하는 필드는 locale입니다. 이 필드는 언제나 텍스트가 뒷받침하는 가장 구체적인 태그를 담습니다. 근거가 있으면 pt-BR, 없으면 pt가 들어갑니다. 즉 locale만 읽어도 적절한 세분화 수준을 자동으로 얻을 수 있습니다. 각 부분을 다시 조합할 필요도 없고, 그럴듯해 보이지만 사실은 추측이었던 지역 값을 다시 의심할 필요도 없습니다.

direction는 번역 전에 렌더링할 수 있게 해줍니다#

언어 감지는 그 자체가 최종 목표인 경우가 드뭅니다. 보통은 텍스트로 무언가를 하기 위해 감지하고, 그 첫 단계는 대개 텍스트를 보여주는 일입니다. 응답에 direction가 포함되는 이유도 바로 여기에 있습니다. 텍스트가 왼쪽에서 오른쪽으로 읽히는지, 오른쪽에서 왼쪽으로 읽히는지를 알려주기 때문에 번역 전에 dir="rtl"를 설정하고, 레이아웃을 고르고, 폰트를 선택할 수 있습니다. 아랍어 텍스트는 "rtl"로, 위의 프랑스어 예시는 "ltr"로 반환됩니다. 언어별 텍스트 방향 테이블을 직접 유지할 필요는 없습니다. 언어를 식별하는 엔드포인트가 렌더링에 가장 먼저 필요한 정보까지 함께 넘겨주니까요.

예시#

텍스트와 선택 사항인 labelLocale를 함께 보내는 단일 POST 요청입니다. 응답은 위에서 설명한 구조화된 로캘 객체입니다.

const response = await fetch(
  "https://api.lingo.dev/process/recognize",
  {
    method: "POST",
    headers: {
      "X-API-Key": "your_api_key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      text: "Bonjour le monde",
      labelLocale: "en",
    }),
  }
);

const result = await response.json();
// { locale: "fr", language: "fr", label: "French", direction: "ltr", ... }

다음 단계#

언어를 감지하는 가장 흔한 이유는 그 결과를 바탕으로 무언가를 하기 위해서고, 대부분은 번역으로 이어집니다. Recognize가 소스 로캘을 알려주면, 그다음은 로컬라이제이션 엔드포인트가 이어받습니다.