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

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

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

URL-адрес запроса

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

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

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

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

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

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

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

Параметры запроса Описание
версия API Обязательный параметр

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

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

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

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

Заголовки Описание
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 и пустой текст ответа.

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

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

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

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

Код состояния Описание
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"

Связанный контент

Дополнительные сведения см. в разделе"Поддержка языков".