다음을 통해 공유

Translator 3.0: 언어

  • 아티클

현재 Translator의 다른 작업에서 지원되는 언어 집합을 가져옵니다.

요청 URL

다음에 GET 요청을 보냅니다.

https://api.cognitive.microsofttranslator.com/languages?api-version=3.0

가상 네트워크의 경우 사용자 지정 도메인 엔드포인트를 사용합니다.

https://<your-custom-domain>.cognitiveservices.azure.com/languages?api-version=3.0

자세한 내용은 Translator 서비스 선택 네트워크 및 프라이빗 엔드포인트 구성 및 지원에 대한 Virtual Network 지원을 참조하세요.

요청 매개 변수

쿼리 문자열에 전달된 요청 매개 변수는 다음과 같습니다.

쿼리 매개 변수 설명
api-version 필수 매개 변수

클라이언트에서 요청한 API 버전입니다. 값은 3.0이어야 합니다.
scope 선택적 매개 변수입니다.

반환할 언어 그룹을 정의하는 쉼표로 구분된 이름 목록입니다. 허용 그룹 이름은 translation, transliteration 및 dictionary입니다. 범위가 지정되지 않는 경우 모든 그룹이 반환됩니다. 그러면 scope=translation,transliteration,dictionary를 전달하는 것과 동일합니다.

응답 본문을 참조하세요.

요청 헤더는 다음과 같습니다.

헤더 설명
Accept-Language 선택적 요청 헤더입니다.

사용자 인터페이스 문자열에 사용할 언어입니다. 응답의 일부 필드는 언어 이름 또는 지역 이름입니다. 이 매개 변수를 사용하여 이러한 이름이 반환되는 언어를 정의합니다. 언어는 올바른 형식 BCP 의 47 언어 태그를 제공하여 지정됩니다. 예를 들어 값을 fr 사용하여 프랑스어로 이름을 요청하거나 값을 zh-Hant 사용하여 중국어 번체로 이름을 요청합니다.
대상 언어가 지정되지 않았거나 지역화를 사용할 수 없는 경우 이름은 영어로 제공됩니다.
X-ClientTraceId 선택적 요청 헤더입니다.
요청을 고유하게 식별하는 클라이언트 생성 ID입니다.

언어 리소스를 가져오는 데 인증이 필요하지 않습니다.

응답 본문

클라이언트는 scope 쿼리 매개 변수를 사용하여 나열할 언어 그룹을 정의합니다.

  • scope=translation 는 텍스트를 한 언어에서 다른 언어로 번역하는 데 지원되는 언어를 제공합니다.

  • scope=transliteration 는 한 언어의 텍스트를 한 스크립트에서 다른 스크립트로 변환하는 기능을 제공합니다.

  • scope=dictionary는 Dictionary 작업이 데이터를 반환하는 언어 쌍을 제공합니다.

클라이언트는 쉼표로 구분된 이름 목록을 지정하여 동시에 여러 그룹을 검색할 수 있습니다. 예를 들어 모든 scope=translation,transliteration,dictionary 그룹에 대해 지원되는 언어를 반환합니다.

성공적인 응답은 요청된 각 그룹에 대해 하나의 속성을 가진 JSON 개체입니다.

{
    "translation": {
        //... set of languages supported to translate text (scope=translation)
    },
    "transliteration": {
        //... set of languages supported to convert between scripts (scope=transliteration)
    },
    "dictionary": {
        //... set of languages supported for alternative translations and examples (scope=dictionary)
    }
}

각 속성의 값은 다음과 같습니다.

  • translation 속성

    속성 값 translation 은 (키, 값) 쌍의 사전입니다. 각 키는 47개 언어 태그입니다 BCP . 키는 텍스트를 번역할 수 있는 대상 또는 원본 언어를 식별합니다. 키와 연결된 값은 언어를 설명하는 속성이 있는 JSON 개체입니다.

    • name: 헤더를 통해 Accept-Language 요청된 로캘의 언어 이름을 표시합니다.

    • nativeName: 이 언어의 로캘 네이티브 언어 이름을 표시합니다.

    • dir: 오른쪽에서 왼쪽 언어 또는 ltr 왼쪽에서 오른쪽 언어에 대한 방향성입니다rtl.

    예제는 다음과 같습니다.

    {
  "translation": {
    ...
    "fr": {
      "name": "French",
      "nativeName": "Français",
      "dir": "ltr"
    },
    ...
  }
}

  • transliteration 속성

    속성 값 transliteration 은 (키, 값) 쌍의 사전입니다. 각 키는 47개 언어 태그입니다 BCP . 키는 텍스트를 한 스크립트에서 다른 스크립트로 변환할 수 있는 언어를 식별합니다. 키와 연결된 값은 언어 및 지원되는 해당 언어를 설명하는 속성이 있는 JSON 개체입니다.

    • name: 헤더를 통해 Accept-Language 요청된 로캘의 언어 이름을 표시합니다.

    • nativeName: 이 언어의 로캘 네이티브 언어 이름을 표시합니다.

    • scripts: 변환할 스크립트 목록입니다. scripts 목록의 각 요소에는 다음 속성이 있습니다.

      • code: 스크립트를 식별하는 코드입니다.

      • name: 헤더를 통해 Accept-Language 요청된 로캘에 스크립트의 이름을 표시합니다.

      • nativeName: 언어의 로캘 네이티브 언어 이름을 표시합니다.

      • dir: 오른쪽에서 왼쪽 언어 또는 ltr 왼쪽에서 오른쪽 언어에 대한 방향성입니다rtl.

      • toScripts: 텍스트를 변환하는 데 사용할 수 있는 스크립트 목록입니다. 목록의 toScripts 각 요소에는 앞에서 설명한 대로 속성code, namenativeName및 dir 속성이 있습니다.

    예제는 다음과 같습니다.

    {
  "transliteration": {
    ...
    "ja": {
      "name": "Japanese",
      "nativeName": "日本語",
      "scripts": [
        {
          "code": "Jpan",
          "name": "Japanese",
          "nativeName": "日本語",
          "dir": "ltr",
          "toScripts": [
            {
              "code": "Latn",
              "name": "Latin",
              "nativeName": "ラテン語",
              "dir": "ltr"
            }
          ]
        },
        {
          "code": "Latn",
          "name": "Latin",
          "nativeName": "ラテン語",
          "dir": "ltr",
          "toScripts": [
            {
              "code": "Jpan",
              "name": "Japanese",
              "nativeName": "日本語",
              "dir": "ltr"
            }
          ]
        }
      ]
    },
    ...
  }
}

  • dictionary 속성

    속성 값 dictionary 은 (키, 값) 쌍의 사전입니다. 각 키는 47개 언어 태그입니다 BCP . 키는 대체 번역 및 백 번역을 사용할 수 있는 언어를 식별합니다. 값은 사용할 수 있는 번역을 포함하는 소스 언어 및 대상 언어를 설명하는 JSON 개체입니다.

    • name: 헤더를 통해 Accept-Language 요청된 로캘에 원본 언어의 이름을 표시합니다.

    • nativeName: 이 언어의 로캘 네이티브 언어 이름을 표시합니다.

    • dir: 오른쪽에서 왼쪽 언어 또는 ltr 왼쪽에서 오른쪽 언어에 대한 방향성입니다rtl.

    • translations: 원본 언어로 표현된 쿼리에 대한 변경 번역 및 예제가 있는 언어 목록입니다. translations 목록의 각 요소에는 다음 속성이 있습니다.

      • name: 헤더를 통해 Accept-Language 요청된 로캘에 대상 언어의 이름을 표시합니다.

      • nativeName: 대상 언어의 로캘 네이티브에 대상 언어의 이름을 표시합니다.

      • dir: 오른쪽에서 왼쪽 언어 또는 ltr 왼쪽에서 오른쪽 언어에 대한 방향성입니다rtl.

      • code: 대상 언어를 식별하는 언어 코드입니다.

    예제는 다음과 같습니다.

    "es": {
  "name": "Spanish",
  "nativeName": "Español",
  "dir": "ltr",
  "translations": [
    {
      "name": "English",
      "nativeName": "English",
      "dir": "ltr",
      "code": "en"
    }
  ]
},

응답 개체의 구조는 API 버전이 변경되지 않고 변경되지 않습니다. 동일한 버전의 API의 경우 Microsoft 번역기 서비스에서 지원하는 언어 목록을 지속적으로 확장하므로 사용 가능한 언어 목록이 시간이 지남에 따라 변경됩니다.

지원되는 언어 목록은 자주 변경되지 않습니다. 네트워크 대역폭을 저장하고 응답성을 향상하려면 클라이언트 애플리케이션에서 언어 리소스 및 해당 엔터티 태그(ETag)를 캐싱하는 것을 고려해야 합니다. 그런 다음, 클라이언트 애플리케이션은 주기적으로(예: 24시간마다) 지원되는 언어의 최신 집합을 인출하는 서비스를 쿼리합니다. 헤더 필드에 현재 ETag 값을 If-None-Match 전달하면 서비스가 응답을 최적화할 수 있습니다. 리소스가 수정되지 않으면 서비스는 상태 코드 304와 빈 응답 본문을 반환합니다.

응답 헤더

헤더 설명
ETag 지원되는 언어의 요청된 그룹에 대한 엔터티 태그의 현재 값입니다. 후속 요청을 보다 효율적으로 만들기 위해 클라이언트는 헤더 필드에 값을 If-None-Match 보낼 ETag 수 있습니다.
X-RequestId 요청을 식별하기 위해 서비스에서 생성한 값입니다. 이 값은 문제 해결을 위해 사용됩니다.

응답 상태 코드

요청을 반환하는 가능한 HTTP 상태 코드는 다음과 같습니다.

상태 코드 Description
200 성공.
304 리소스가 수정되지 않고 요청 헤더에 지정된 버전과 일치합니다 If-None-Match.
400 쿼리 매개 변수 중 하나가 없거나 잘못되었습니다. 다시 시도하기 전에 요청 매개 변수를 수정합니다.
429 클라이언트가 요청 제한을 초과했기 때문에 서버가 요청을 거부했습니다.
500 예기치 않은 오류가 발생했습니다. 오류가 지속되면 오류 날짜 및 시간, 응답 헤더의 요청 식별자 및 요청 X-ClientTraceId헤더X-RequestId의 클라이언트 식별자를 사용하여 보고합니다.
503 서버를 일시적으로 사용할 수 없습니다. 요청을 재시도합니다. 오류가 지속되면 오류 날짜 및 시간, 응답 헤더의 요청 식별자 및 요청 X-ClientTraceId헤더X-RequestId의 클라이언트 식별자를 사용하여 보고합니다.

오류가 발생하는 경우 요청은 JSON 오류 응답도 반환합니다. 오류 코드는 오류를 더 범주화하도록 뒤에 3자리 숫자가 오는 3자리 HTTP 상태 코드로 결합된 6자리 숫자입니다. 일반적인 오류 코드는 v3 Translator 참조 페이지에서 확인할 수 있습니다.

예제

다음 예제에서는 텍스트 번역에 지원되는 언어를 검색하는 방법을 보여 줍니다.

curl "https://api.cognitive.microsofttranslator.com/languages?api-version=3.0&scope=translation"