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

Azure Translator в средстве Foundry 3.0. Перевод

Перевод текста.

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

Отправьте запрос в POST :

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

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

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

Параметры запроса, передаваемые в строке запроса:

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

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

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

Параметр запроса Description
от / из / с (context-dependent) Необязательный параметр.
Задает язык входного текста. Найдите, какие языки доступны для перевода, просматривая поддерживаемые языки с помощью translation области. from Если параметр не указан, для определения исходного языка применяется автоматическое обнаружение языка.

При использовании функции from необходимо использовать параметр, а не автоопределение. Примечание. Функция динамического словаря учитывает регистр.
textType Необязательный параметр.
Определяет, является ли перевод текста обычным или HTML-текстом. Любой HTML-код должен быть хорошо сформированным, полным элементом. Возможные значения: plain (по умолчанию) или html.
категория Необязательный параметр.
Строка, указывающая категорию (домен) перевода. Этот параметр используется для получения переводов из настраиваемой системы, созданной с помощью Пользовательского переводчика. Чтобы использовать развернутую настраиваемую систему, добавьте идентификатор категории из сведений о проекте Пользовательского переводчика в параметр категории. Значение по умолчанию: general.
ненормативное выражение Необязательный параметр.
Указывает, как следует рассматривать ненормативную лексику в переводах. Возможные значения: NoAction (по умолчанию), Markedили Deleted. Сведения о способах лечения ненормативной лексики см. в разделе "Обработка ненормативной лексики".
ненормативное выражениеMarker Необязательный параметр.
Указывает, как ненормативная лексика должна быть помечена в переводах. Возможные значения: Asterisk (по умолчанию) или Tag. Сведения о способах лечения ненормативной лексики см. в разделе "Обработка ненормативной лексики".
includeAlignment Необязательный параметр.
Указывает, следует ли включать проекцию выравнивания из исходного текста в переведенный текст. Возможные значения: true или false (по умолчанию).
includeSentenceLength Необязательный параметр.
Указывает, следует ли включать границы предложения для входного текста и переведенного текста. Возможные значения: true или false (по умолчанию).
предлагаемыйFrom Необязательный параметр.
Указывает резервный язык, если язык входного текста не удается определить. Автоматическое определение языка применяется при from опущении параметра. При сбое suggestedFrom обнаружения предполагается язык.
fromScript Необязательный параметр.
Задает скрипт входного текста.
toScript Необязательный параметр.
Задает скрипт переведенного текста.
allowFallback Необязательный параметр.
Указывает, что служба может вернуться к общей системе, если пользовательская система не существует. Возможные значения: true (по умолчанию) или false.

allowFallback=false указывает, что перевод должен использовать только системы, обученные для указанного category запросом. Если перевод с языка X на язык Y требует цепочки через язык сводных данных E, то все системы в цепочке (X → E и E → Y) должны быть настраиваемыми и иметь одну и ту же категорию. Если система не найдена с определенной категорией, запрос возвращает код состояния 400. allowFallback=true указывает, что служба может вернуться к общей системе, если пользовательская система не существует.

К заголовкам запроса относятся:

Headers Description
Заголовки проверки подлинности Обязательный заголовок запроса.
См. доступные параметры проверки подлинности.
Тип контента Обязательный заголовок запроса.
Указывает тип контента полезных данных.
Принятое значение application/json; charset=UTF-8равно.
Длина содержимого Необязательно.
Длина текста запроса.
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 приведены в разделе примеров .

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

Headers Description
X-requestid Значение, созданное службой для определения запроса, используемого для устранения неполадок.
X-mt-system Указывает системный тип, используемый для перевода для каждого языка "to", запрошенного для перевода. Значение — это разделенный запятыми список строк. Каждая строка указывает тип:

Custom — Request включает настраиваемую систему и по крайней мере одну пользовательскую систему, используемую во время перевода.
Команда — все остальные запросы
Использование x-metered Указывает потребление (количество символов, для которых взимается плата пользователя) для запроса задания перевода. Например, если слово "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-значный номер, объединяющий код состояния HTTP с 3 цифрами, за которым следует 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 Значение ProfanityMarker Действие Пример: источник — испанский Пример: целевой — английский
NoAction Default. То же самое, что и параметр. Ненормативная лексика передается из источника в целевой объект. Que coche de <Insert-profane-word> Что такое <автомобиль insert-profane-word>
Меченый Звездочка Звездочки заменяют ненормативные слова (по умолчанию). Que coche de <Insert-profane-word> Какой автомобиль ***
Меченый Тег Ненормативные слова окружены ненормативной лексикой< XML-тегов>...</ненормативность>. Que coche de <Insert-profane-word> Что такое ненормативный объект insert-profane-word<>/ненормативный< автомобиль ><>
Удалено Ненормативные слова удаляются из выходных данных без замены. Que coche de <Insert-profane-word> Что автомобиль

В приведенных выше примерах <insert-profane-word> — это заполнитель для ненормативных слов.

Рассмотрим пример.

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-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>

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

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=texttextType=html. Эту функцию следует использовать с разреженным образом. Подходящий и гораздо лучший способ настройки перевода — с помощью пользовательского переводчика. Пользовательский переводчик полностью использует контекст и статистические вероятности. Если вы можете создать обучающие данные, отображающие работу или фразу в контексте, вы получите лучшие результаты. Дополнительные сведения о пользовательском переводчике.

Дальнейшие шаги

Краткое руководство по переводчику

  • Last updated on