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

  • Статья

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

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

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

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

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

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

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

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

Версия 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 представляет собой словарь (ключ, значение) пары. Каждый ключ является языковым тегом BCP-47. Ключ идентифицирует язык, с которого или на который текст может быть переведен. Значение, связанное с ключом, является JSON-объектом со свойствами, которые описывают язык.

    • name. Отображаемое имя языка в языковом стандарте, запрашиваемое через заголовок Accept-Language.

    • nativeName. Отображаемое собственное имя языка в языковом стандарте.

    • dir. Направление письма на этом языке, где rtl — это "справа налево" или ltr — "слева направо".

    Пример.

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

  • Свойствоtransliteration

    Значение свойства transliteration представляет собой словарь (ключ, значение) пары. Каждый ключ является языковым тегом BCP-47. Ключ идентифицирует язык, для которого текст может быть преобразован из одного сценария в другой. Значение, связанное с ключом, является 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 представляет собой словарь (ключ, значение) пары. Каждый ключ является языковым тегом BCP-47. Ключ идентифицирует язык, для которого доступны альтернативные и обратные переводы. Значение — это 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"