Переводчик 3.0: Languages

Статья
09/01/2024

Получает набор языков, поддерживаемых в настоящее время другими операциями Переводчика.

Запросить URL-адрес

Отправьте запрос GET на следующий адрес.

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

Для виртуальных сетей используйте конечную точку личного домена:

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

Дополнительные сведения см. в разделе виртуальная сеть Поддержка выбранной службы Переводчика и конфигурации частной конечной точки и поддержки.

Параметры запроса

В таблице ниже приведены параметры, которые передаются в строке запроса.

Параметры запроса Description

api-version Обязательный параметр

Версия API, запрошенная клиентом. Необходимое значение: 3.0.

область Необязательный параметр.

Список имен, разделенных запятыми, определяющий возвращаемую группу языков. Допустимые имена групп: translation, transliterationи dictionary. Если область не задана, то возвращаются все группы, которые эквивалентны передаче scope=translation,transliteration,dictionary.

Параметры запроса	Description
api-version	Обязательный параметр Версия API, запрошенная клиентом. Необходимое значение: `3.0`.
область	Необязательный параметр. Список имен, разделенных запятыми, определяющий возвращаемую группу языков. Допустимые имена групп: `translation`, `transliteration`и `dictionary`. Если область не задана, то возвращаются все группы, которые эквивалентны передаче `scope=translation,transliteration,dictionary`.

См. текст ответа.

Заголовки запроса.

Заголовки Description

Accept-Language Дополнительный заголовок запроса.

Язык, используемый для строк пользовательского интерфейса. Некоторые поля в ответе — это имена языков или регионов. Используйте этот параметр, чтобы определить язык, на котором возвращаются эти имена. Язык указан путем предоставления хорошо сформированного BCP 47 языкового тега. Например, значение fr позволяет получить имена на французском языке, а значение zh-Hant — на традиционном китайском.
Имена предоставляются на английском языке, если целевой язык не указан или когда локализация недоступна.

X-ClientTraceId Дополнительный заголовок запроса.
Созданный клиентом идентификатор GUID, позволяющий уникально идентифицировать запрос.

Заголовки	Description
Accept-Language	Дополнительный заголовок запроса. Язык, используемый для строк пользовательского интерфейса. Некоторые поля в ответе — это имена языков или регионов. Используйте этот параметр, чтобы определить язык, на котором возвращаются эти имена. Язык указан путем предоставления хорошо сформированного `BCP` 47 языкового тега. Например, значение `fr` позволяет получить имена на французском языке, а значение `zh-Hant` — на традиционном китайском. Имена предоставляются на английском языке, если целевой язык не указан или когда локализация недоступна.
X-ClientTraceId	Дополнительный заголовок запроса. Созданный клиентом идентификатор GUID, позволяющий уникально идентифицировать запрос.

Для получения языковых ресурсов аутентификация не требуется.

Текст ответа

Клиент использует 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. Направление письма на этом языке, где rtl — это "справа налево" или ltr — "слева направо".
Пример.
```
{
  "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. Направление письма на этом языке, где rtl — это "справа налево" или ltr — "слева направо".
  - toScripts. Список сценариев, доступных для преобразования текста. Каждый элемент списка toScripts имеет свойства code, name, nativeName и 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. Направление письма на этом языке, где rtl — это "справа налево" или ltr — "слева направо".
- translations. Список языков с альтернативными переводами и примерами запросов, выраженными на языке источника. Каждый элемент списка translations содержит следующие свойства.
  - name. Отображаемое имя целевого языка в языковом стандарте, запрашиваемое через заголовок Accept-Language.
  - nativeName. Отображаемое собственное имя целевого языка в языковом стандарте.
  - dir. Направление письма на этом языке, где rtl — это "справа налево" или ltr — "слева направо".
  - code. Код языка, определяющий целевой язык.
Пример.
```
"es": {
  "name": "Spanish",
  "nativeName": "Español",
  "dir": "ltr",
  "translations": [
    {
      "name": "English",
      "nativeName": "English",
      "dir": "ltr",
      "code": "en"
    }
  ]
},
```

Структура объекта ответа не изменяется без изменения версии API. Для той же версии API список доступных языков может меняться со временем, потому что Microsoft Translator постоянно расширяет список языков, поддерживаемых его службами.

Список поддерживаемых языков часто не изменяется. Чтобы сохранить пропускную способность сети и повысить скорость реагирования для клиентского приложения, следует рассмотреть возможность кэширования языковых ресурсов и соответствующего тега объекта (ETag). Затем клиентское приложение может периодически (например, один раз каждые 24 часа) делать запрос в службу для получения последнего набора поддерживаемых языков. Передача текущего ETag значения в поле заголовка If-None-Match позволяет службе оптимизировать ответ. Если ресурс не изменен, служба возвращает код состояния 304 и пустой текст ответа.

Заголовки ответа

Заголовки	Description
ETag	Текущее значение тега сущности для запрошенных групп поддерживаемых языков. Для более эффективных запросов, клиент может отправить значение `ETag` в поле заголовка `If-None-Match`.
X-RequestId	Сформированное службой значение для идентификации запроса. Используется для устранения неполадок.

Коды состояния ответа

Ниже приведены возможные коды состояния HTTP, которые возвращает запрос.

Код состояния	Description
200	Успех.
304	Ресурс не изменяется и соответствует версии, указанной заголовками `If-None-Match`запросов.
400	Один из параметров запроса отсутствует или имеет недопустимое значение. Исправьте параметры запроса и повторите попытку.
429	Сервер отклонил запрос, так как клиент превысил ограничения запроса.
500	Произошла непредвиденная ошибка. Если ошибка сохраняется, передайте отчет о ней, включив следующие данные: дата и время сбоя, идентификатор запроса из заголовка ответа `X-RequestId` и идентификатор клиента из заголовка запроса `X-ClientTraceId`.
503	Сервер временно недоступен. Повторите запрос. Если ошибка сохраняется, передайте отчет о ней, включив следующие данные: дата и время сбоя, идентификатор запроса из заголовка ответа `X-RequestId` и идентификатор клиента из заголовка запроса `X-ClientTraceId`.

Если возникнет ошибка, запрос также вернет ответ JSON с ошибкой. Код ошибки представляет собой число из 6 знаков, первые 3 из которых являются кодом состояния HTTP, а оставшиеся 3 цифры определяют категорию ошибки. Коды распространенных ошибок можно найти на справочной странице переводчика версии 3.

Примеры

В следующем примере показано, как получить список языков, поддерживаемых для перевода текста.

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

Поделиться через