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

Статья
02/12/2024

Этот интерфейс позволяет переводить текст.

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

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

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

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

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

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

Обязательные параметры

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

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

до Обязательный параметр.
Определяет язык выходного текста. Целевой язык должен быть одним из поддерживаемых языков, включенных в область translation. Например, используйте параметр to=de, чтобы перевести на немецкий.
Вы можете одновременно переводить на различные языки, использовав этот параметр в строке запроса несколько раз. Например, используйте параметр to=de&to=it, чтобы перевести на немецкий и итальянский.

Параметр запроса	Description
api-version	Обязательный параметр. Версия API, запрошенная клиентом. Необходимое значение: `3.0`.
до	Обязательный параметр. Определяет язык выходного текста. Целевой язык должен быть одним из поддерживаемых языков, включенных в область `translation`. Например, используйте параметр `to=de`, чтобы перевести на немецкий. Вы можете одновременно переводить на различные языки, использовав этот параметр в строке запроса несколько раз. Например, используйте параметр `to=de&to=it`, чтобы перевести на немецкий и итальянский.

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

Параметр запроса	Description
from	Необязательный параметр. Определяет язык оригинального текста. Чтобы просмотреть, какие языки доступны для перевода, выполните поиск поддерживаемых языков, используя область `translation`. Если параметр `from` не указан, исходный язык определяется автоматически. При использовании функции динамического словаря необходимо использовать параметр `from`, а не автоматическое определение. Примечание. Функция динамического словаря учитывает регистр.
textType	Необязательный параметр. Определяет, является ли текст перевода обычным или HTML-текстом. Любой код HTML должен быть полным элементом с правильным форматом. Возможные значения: `plain` (по умолчанию) или `html`.
Категория	Необязательный параметр. Строка, где указано категорию (домен) перевода. Этот параметр позволяет получить переводы из пользовательской системы, созданной с помощью Custom Translator. Чтобы использовать развернутую настраиваемую систему, добавьте идентификатор категории из пользовательских Переводчик сведений о проекте в параметр категории. Значение по умолчанию: `general`.
profanityAction	Необязательный параметр. Указывает способ обработки нецензурной лексики в переводе. Возможные значения: `NoAction` (по умолчанию), `Marked`или `Deleted`. Способы работы с нецензурной лексикой см. в этом разделе.
profanityMarker	Необязательный параметр. Указывает, каким образом нецензурная лексика должна помечаться в переводе. Возможные значения: `Asterisk` (по умолчанию) или `Tag`. Способы работы с нецензурной лексикой см. в этом разделе.
includeAlignment	Необязательный параметр. Указывает, следует ли применять выравнивание из оригинального текста в переводе. Возможные значения: `true` или `false` (по умолчанию).
includeSentenceLength	Необязательный параметр. Указывает, следует ли включать границы предложения оригинального и переведенного текста. Возможные значения: `true` или `false` (по умолчанию).
suggestedFrom	Необязательный параметр. Указывает автоматический язык, если не удается определить язык оригинального текста. Автоопределение языка применяется при опущении параметра `from`. При сбое `suggestedFrom` обнаружения предполагается язык.
fromScript	Необязательный параметр. Указывает сценарий оригинального текста.
toScript	Необязательный параметр. Указывает скрипт переведенного текста.
allowFallback	Необязательный параметр. Указывает, что службе разрешено откатиться к общей системе, когда пользовательская система не существует. Возможные значения: `true` (по умолчанию) или `false`. `allowFallback=false` указывает, что для перевода должны использоваться только те обученные для `category` системы, которые указаны в запросе. Если перевод с языка X на язык Y требует цепочки через язык сводных данных E, то все системы в цепочке (X → E и E → Y) должны быть настраиваемыми и иметь одну и ту же категорию. Если система не найдена с определенной категорией, запрос возвращает код состояния 400. `allowFallback=true` указывает, что службе разрешено откатиться к общей системе, когда пользовательская система не существует.

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

Заголовки	Description
Заголовки проверки подлинности	Обязательный заголовок запроса. См. описание доступных способов проверки подлинности.
Тип контента	Обязательный заголовок запроса. Указывает тип содержимого для полезных данных. Допустимое значение: `application/json; charset=UTF-8`.
content-length: 0	Обязательный заголовок запроса. Длина текста запроса.
X-ClientTraceId	Необязательно. Созданный клиентом идентификатор GUID, позволяющий уникально идентифицировать запрос. Этот заголовок можно опустить, если в строке запроса указан идентификатор трассировки в параметре с именем `ClientTraceId`.

Текст запроса

Текст запроса является массивом в формате JSON. Каждый элемент этого массива представляет собой объект JSON со строковым свойством Text, который являет собой строку для перевода.

[
    {"Text":"I would really like to drive your car around the block a few times."}
]

Сведения об ограничениях символов и массивов см. в статьеОграничения запросов.

Текст ответа

Успешный ответ возвращается в формате массива JSON с одним результатом для каждой строки входного массива. Объект результата содержит следующие свойства.

detectedLanguage — объект, описывающий распознанный язык с помощью следующих свойств:
- language — строку, которая представляет код обнаруженного языка.
- score — значение с плавающей запятой, обозначающее достоверность результата. Может принимать ноль или единицу, где низкая оценка обозначает низкую достоверность.
Свойство detectedLanguage присутствует в объекте результата исключительно при запросе автоопределения языка.
translations — массив результатов перевода. Размер массива совпадает с количеством языков, указанных с помощью параметра запроса to. Каждый элемент массива содержит:
- to — строка, которая содержит код целевого языка.
- text — строка с текстом перевода.
- transliteration — объект, который возвращает переведенный текст в сценарии, указанном в параметре toScript.
  - script — строка, которая указывает целевой сценарий.
  - text — строка, которая возвращает целевой текст в целевом сценарии.
  Если не выполняется транслитерация, объект transliteration не включается.
  - alignment — объект с одним свойством строки proj, который преобразовывает оригинальный текст в переведенный. Сведения о выравнивании предоставляются, только когда параметр запроса includeAlignment имеет значение true. Сведения о выравнивании возвращаются в виде строкового значения в следующем формате: [[SourceTextStartIndex]:[SourceTextEndIndex]–[TgtTextStartIndex]:[TgtTextEndIndex]]. Двоеточие разделяет начальный и конечный индексы, дефис — языки, а пробел — слова. Одно слово может выровняться с нулевым, одним или несколькими словами на другом языке, а выровненные слова могут быть неконтентными. Если сведения о выравнивании недоступны, элемент выравнивания пуст. Примеры и ограничения см. в разделе Получение сведений о выравнивании.
- sentLen — объект, возвращающий границы предложения в оригинальном и переведенном текстах.
  - srcSentLen — массив целых чисел, представляющих значения длины предложений в оригинальном тексте. Длина массива соответствует количеству предложений, а значения — длине каждого предложения.
  - transSentLen: массив целых чисел, представляющих значения длины предложений в переведенном тексте. Длина массива соответствует количеству предложений, а значения — длине каждого предложения.
  Границы предложения включены только тогда, когда параметр запроса includeSentenceLength имеет значение true.
sourceText — объект с одним свойством строки text, который возвращает оригинальный текст в сценарии по умолчанию исходного языка. sourceText свойство присутствует только в том случае, если входные данные выражаются в сценарии, который не является обычным для этого языка. Например, если входные данные были арабскими, написанными на латинице, то sourceText.text будет тот же арабский текст, преобразованный в арабский скрипт..

Примеры ответов JSON приведены в разделе примеры.

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

Заголовки	Description
X-requestid	Значение, созданное службой для определения запроса, используемого для устранения неполадок.
X-mt-system	Указывает тип системы, который использовался для перевода каждого целевого языка, запрошенного для перевода. Это значение представляет собой список строк, разделенных запятыми. Каждая строка указывает тип: Custom — Request включает настраиваемую систему и по крайней мере одну пользовательскую систему, используемую во время перевода. Команда — все остальные запросы
X-metered-usage	Указывает потребление (количество символов, для которых взимается плата пользователя) для запроса задания перевода. Например, если слово "Hello" переведено с английского языка (en) на французский (fr), это поле возвращает значение `5`.

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

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

Код состояния	Description
200	Успешно.
400	Один из параметров запроса отсутствует или имеет недопустимое значение. Исправьте параметры запроса и повторите попытку.
401	Не удалось выполнить аутентификацию запроса. Убедитесь, что указаны допустимые учетные данные.
403	Запрос не авторизован. Подробные сведения можно найти в сообщении об ошибке. Этот код состояния часто указывает, что вы использовали все бесплатные переводы, предоставляемые пробной подпиской.
408	Не удалось выполнить запрос, так как отсутствует ресурс. Подробные сведения можно найти в сообщении об ошибке. Если запрос включает пользовательскую категорию, этот код состояния часто указывает, что пользовательская система перевода пока недоступна для обслуживания запросов. Запрос необходимо повторить после периода ожидания (например, 1 минута).
429	Сервер отклонил запрос, так как клиент превысил ограничения запроса.
500	Произошла непредвиденная ошибка. Если ошибка сохраняется, передайте отчет о ней, включив следующие данные: дата и время сбоя, идентификатор запроса из заголовка ответа X-RequestId и идентификатор клиента из заголовка запроса X-ClientTraceId.
503	Сервер временно недоступен. Повторите запрос. Если ошибка сохраняется, передайте отчет о ней, включив следующие данные: дата и время сбоя, идентификатор запроса из заголовка ответа X-RequestId и идентификатор клиента из заголовка запроса X-ClientTraceId.

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

Примеры

Перевод отдельного элемента

В этом примере показано, как перевести одно предложение с английского языка на упрощенный китайский.

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=zh-Hans" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'Hello, what is your name?'}]"

Текст ответа:

[
    {
        "translations":[
            {"text":"你好, 你叫什么名字？","to":"zh-Hans"}
        ]
    }
]

Массив translations содержит один элемент, который обеспечивает перевод одного элемента текста в оригинальных данных.

Перевод одного ввода с автоопределением языка

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

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=zh-Hans" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'Hello, what is your name?'}]"

Текст ответа:

[
    {
        "detectedLanguage": {"language": "en", "score": 1.0},
        "translations":[
            {"text": "你好, 你叫什么名字？", "to": "zh-Hans"}
        ]
    }
]

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

Перевод методом транслитерации

Давайте расширим предыдущий пример, добавив метод транслитерации. В следующем запросе используется китайский текст, написанный латинским алфавитом.

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=zh-Hans&toScript=Latn" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'Hello, what is your name?'}]"

Текст ответа:

[
    {
        "detectedLanguage":{"language":"en","score":1.0},
        "translations":[
            {
                "text":"你好, 你叫什么名字？",
                "transliteration":{"script":"Latn", "text":"nǐ hǎo , nǐ jiào shén me míng zì ？"},
                "to":"zh-Hans"
            }
        ]
    }
]

Результат перевода теперь включает свойство transliteration, которое возвращает переведенный текст, написанный символами латиницы.

Перевод нескольких фрагментов текста

Одновременный перевод нескольких строк — это просто вопрос задания массива строк в тексте запроса.

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=zh-Hans" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'Hello, what is your name?'}, {'Text':'I am fine, thank you.'}]"

Ответ содержит перевод всех фрагментов текста в том же порядке, что и в запросе. Текст ответа:

[
    {
        "translations":[
            {"text":"你好, 你叫什么名字？","to":"zh-Hans"}
        ]
    },
    {
        "translations":[
            {"text":"我很好，谢谢你。","to":"zh-Hans"}
        ]
    }
]

Перевод на несколько языков

В этом примере показано, как перевести одинаковый оригинальный текст на несколько языков в одном запросе.

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=zh-Hans&to=de" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'Hello, what is your name?'}]"

Текст ответа:

[
    {
        "translations":[
            {"text":"你好, 你叫什么名字？","to":"zh-Hans"},
            {"text":"Hallo, was ist dein Name?","to":"de"}
        ]
    }
]

Работа с нецензурной лексикой

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

Если необходимо избежать появления ненормативной лексики при переводе (независимо от наличия ненормативной лексики в источнике), можно использовать параметр фильтрации ненормативной лексики. Этот параметр позволяет выбрать, следует ли просматривать удаленную ненормативную лексику, помеченную соответствующими тегами (предоставляя возможность добавления собственной после обработки) или без действий. Допустимые значения ProfanityAction : Deleted, Markedи NoAction (по умолчанию).

ProfanityAction	Действие
`NoAction`	NoAction - алгоритм действий по умолчанию. Ненормативная лексика переходит из источника в целевой объект. Пример источника (японский):彼はジャッカスです。 Пример перевода (английский): он джек---.
`Deleted`	Оскорбительные слова удаляются из выходных данных без замены. Пример источника (японский):彼はジャッカスです。 Пример перевода (английский): он a**
`Marked`	Маркер заменяет помеченное слово в выходных данных. Маркер зависит от параметра `ProfanityMarker`. Для `ProfanityMarker=Asterisk`, ненормативные слова заменяются `*`на: Пример источника (японский):彼はジャッカスです。 Пример перевода (английский)*: он \\\. Для `ProfanityMarker=Tag`этого ненормативные слова окружены ненормативной лексикой XML-тегов <и </profanity>>: Пример источника (японский):彼はジャッカスです。 Пример перевода (английский): он ненормативный <>джек---</ненормативность>.

Например:

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=de&profanityAction=Marked" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'This is an <expletive> good idea.'}]"

Данный запрос возвращает:

[
    {
        "translations":[
            {"text":"Das ist eine *** gute Idee.","to":"de"}
        ]
    }
]

Сравнение:

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=de&profanityAction=Marked&profanityMarker=Tag" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'This is an <expletive> good idea.'}]"

Последний запрос возвращает:

[
    {
        "translations":[
            {"text":"Das ist eine <profanity>verdammt</profanity> gute Idee.","to":"de"}
        ]
    }
]

Перевод содержимого, включающее разметку

Обычно переводят содержимое, которое включает разметку, например содержимое HTML-страницы или содержимое XML-документа. Включите параметр запроса textType=html при переводе содержимого с тегами. Кроме того, иногда бывает полезно исключить из перевода конкретное содержимое. С помощью атрибута class=notranslate можно указать содержимое, которое должно остаться не переведенным. В следующем примере содержимое внутри первого div элемента не преобразуется, а содержимое второго div элемента преобразуется.

<div class="notranslate">This will not be translated.</div>
<div>This will be translated. </div>

Пример запроса приведен ниже.

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=zh-Hans&textType=html" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'<div class=\"notranslate\">This will not be translated.</div><div>This will be translated.</div>'}]"

Ответ:

[
    {
        "translations":[
            {"text":"<div class=\"notranslate\">This will not be translated.</div><div>这将被翻译。</div>","to":"zh-Hans"}
        ]
    }
]

Получить сведения о выравнивании

Сведения о сопоставлении возвращаются в виде строкового значения в следующем формате для каждого слова источника. Сведения о каждом слове разделяются пробелом, в том числе в языках (системах письменности) без разделения пробелами, таких как китайский:

[[SourceTextStartIndex]:[SourceTextEndIndex]–[TgtTextStartIndex]:[TgtTextEndIndex]] *

Пример строки со сведениями о сопоставлении: 0:0-7:10 1:2-11:20 3:4-0:3 3:4-4:6 5:5-21:21.

Иными словами, двоеточие разделяет начальный и конечный индексы, дефис — языки, а пробел — слова. Одно слово может выровняться с нулевым, одним или несколькими словами на другом языке, а выровненные слова могут быть неконтентными. Если сведения о выравнивании недоступны, элемент Alignment пуст. В этом случае метод не возвращает ошибку.

Чтобы получить сведения о выравнивании, укажите параметр includeAlignment=true в строке запроса.

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=fr&includeAlignment=true" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'The answer lies in machine translation.'}]"

Ответ:

[
    {
        "translations":[
            {
                "text":"La réponse se trouve dans la traduction automatique.",
                "to":"fr",
                "alignment":{"proj":"0:2-0:1 4:9-3:9 11:14-11:19 16:17-21:24 19:25-40:50 27:37-29:38 38:38-51:51"}
            }
        ]
    }
]

Сведения о выравнивании начинаются со строки 0:2-0:1. Это значит, что первые три символа в исходном тексте (The) сопоставляются с двумя первыми символами в переведенном тексте (La).

Ограничения

Получение сведений о выравнивании является экспериментальной функцией, которую мы включили для создания прототипов исследований и взаимодействия с потенциальными сопоставлениями фраз. Вот некоторые из заметных ограничений, при которых выравнивания не поддерживаются:

Выравнивание недоступно для текста в формате HTML, т. е. textType=html.
Выравнивание возвращается только для подмножества языковых пар:
- Английский на любой другой язык, кроме китайского традиционного, кантонского (традиционного) или сербского (кириллица)
- от японского до корейского или из корейского на японский
- от японского до китайского упрощенного и китайского упрощенного на японский
- от китайского упрощенного до китайского традиционного и китайского традиционного на китайский упрощенный
Если предложение является консервированным переводом, не выравнивание. Пример консервированного перевода : This is a test, I love youи другие предложения высокой частоты
Выравнивание недоступно, если вы применяете любой из подходов для предотвращения перевода, как описано здесь.

Установка границ предложения

Чтобы получать сведения о длине предложения в исходном тексте и переводе, укажите параметр includeSentenceLength=true в строке запроса.

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=fr&includeSentenceLength=true" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'The answer lies in machine translation. The best machine translation technology cannot always provide translations tailored to a site or users like a human. Simply copy and paste a code snippet anywhere.'}]"

Ответ:

[
    {
        "translations":[
            {
                "text":"La réponse se trouve dans la traduction automatique. La meilleure technologie de traduction automatique ne peut pas toujours fournir des traductions adaptées à un site ou des utilisateurs comme un être humain. Il suffit de copier et coller un extrait de code n'importe où.",
                "to":"fr",
                "sentLen":{"srcSentLen":[40,117,46],"transSentLen":[53,157,62]}
            }
        ]
    }
]

Перевод с помощью динамического словаря

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

В разметке используется следующий синтаксис:

<mstrans:dictionary translation="translation of phrase">phrase</mstrans:dictionary>

Например, рассмотрим следующее русское предложение: "Слово "словоматик" — это словарная запись". Чтобы сохранить при переводе слово словоматик, необходимо отправить запрос:

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=de" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'The word <mstrans:dictionary translation=\"wordomatic\">wordomatic</mstrans:dictionary> is a dictionary entry.'}]"

Результат:

[
    {
        "translations":[
            {"text":"Das Wort \"wordomatic\" ist ein Wörterbucheintrag.","to":"de"}
        ]
    }
]

Эта возможность динамического словаря работает с textType=text и textType=htmlодинаково. Компонент должен использоваться только в случае необходимости. Соответствующий и гораздо лучший способ настройки перевода — это использование концентратора Custom Translator. Custom Translator обеспечивает полное использование контекста и статистические значения вероятности. Если вы можете создать обучающие данные, отображающие работу или фразу в контексте, вы получите лучшие результаты. Узнайте больше о Custom Translator.

Следующие шаги

Поработайте с кратким руководством по Переводчику

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

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

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

Обязательные параметры

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

Текст запроса

Текст ответа

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

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

Примеры

Перевод отдельного элемента

Перевод одного ввода с автоопределением языка

Перевод методом транслитерации

Перевод нескольких фрагментов текста

Перевод на несколько языков

Работа с нецензурной лексикой

Перевод содержимого, включающее разметку

Получить сведения о выравнивании

Ограничения

Установка границ предложения

Перевод с помощью динамического словаря

Следующие шаги

Дополнительные ресурсы