Translator 3.0: Překlad

Přeloží text.

Adresa URL požadavku

Odešlete požadavek POST do:

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

Parametry požadavku

Parametry požadavku předané v řetězci dotazu jsou:

Požadované parametry

Parametr dotazu Popis
verze-api Povinný parametr.
Verze rozhraní API požadovaného klientem Hodnota musí být 3.0.
na Povinný parametr.
Určuje jazyk výstupního textu. Cílový jazyk musí být jedním z podporovaných jazyků zahrnutých translation v oboru. Můžete například použít to=de k překladu do němčiny.
Parametr v řetězci dotazu můžete současně přeložit na více jazyků. Můžete například použít to=de&to=it k překladu do němčiny a italštiny.

Volitelné parametry

Parametr dotazu Popis
Parametr dotazu Popis
Z Volitelný parametr.
Určuje jazyk vstupního textu. Vyhledejte jazyky, ze kterých se dají přeložit, vyhledáním podporovaných jazyků pomocí translation oboru. from Pokud parametr není zadaný, použije se automatické rozpoznávání jazyka k určení zdrojového jazyka.

Při použití funkce dynamického slovníkufrom je nutné místo automatického deekce použít parametr. Poznámka: Funkce dynamického slovníku rozlišuje malá a velká písmena.
TextType Volitelný parametr.
Definuje, zda je přeložený text prostým textem nebo textem HTML. Jakýkoli kód HTML musí být správně formátovaný a úplný prvek. Možné hodnoty jsou: plain (výchozí) nebo html.
category Volitelný parametr.
Řetězec určující kategorii (doménu) překladu. Tento parametr slouží k získání překladů z přizpůsobeného systému vytvořeného pomocí služby Custom Translator. Do tohoto parametru přidejte ID kategorie z podrobností projektu Custom Translator, abyste mohli použít nasazený přizpůsobený systém. Výchozí hodnota je: general.
vulgární akce Volitelný parametr.
Určuje, jak se mají v překladech zacházet s vulgárními výrazy. Možné hodnoty jsou: NoAction (výchozí) Marked nebo Deleted. Pokud chcete porozumět způsobům léčby vulgárních výrazů, podívejte se na popis vulgárních výrazů.
vulgární výrazMarker Volitelný parametr.
Určuje způsob označení vulgárních výrazů v překladech. Možné hodnoty jsou: Asterisk (výchozí) nebo Tag. Pokud chcete porozumět způsobům léčby vulgárních výrazů, podívejte se na popis vulgárních výrazů.
includeAlignment Volitelný parametr.
Určuje, jestli se má zahrnout projekce zarovnání ze zdrojového textu na přeložený text. Možné hodnoty jsou: true nebo false (výchozí).
includeSentenceLength Volitelný parametr.
Určuje, zda se mají zahrnout hranice vět pro vstupní text a přeložený text. Možné hodnoty jsou: true nebo false (výchozí).
suggestedFrom Volitelný parametr.
Určuje záložní jazyk, pokud jazyk vstupního textu nelze identifikovat. Automatické rozpoznávání jazyka se použije při vynechání parametru from . Pokud detekce selže, bude se předpokládat, že suggestedFrom jazyk.
fromScript Volitelný parametr.
Určuje skript vstupního textu.
toScript Volitelný parametr.
Určuje skript přeloženého textu.
allowFallback Volitelný parametr.
Určuje, že služba se může vrátit do obecného systému, pokud vlastní systém neexistuje. Možné hodnoty jsou: true (výchozí) nebo false.

allowFallback=false určuje, že překlad by měl používat pouze systémy natrénované pro category zadaný požadavek. Pokud překlad jazyka X do jazyka Y vyžaduje řetězení prostřednictvím kontingenčního jazyka E, všechny systémy v řetězu (X → E a E → Y) budou muset být vlastní a mají stejnou kategorii. Pokud se v konkrétní kategorii nenajde žádný systém, požadavek vrátí stavový kód 400. allowFallback=true určuje, že služba se může vrátit do obecného systému, pokud vlastní systém neexistuje.

Hlavičky požadavku zahrnují:

Hlavičky Description
Hlavičky ověřování Požadovaná hlavička požadavku.
Podívejte se na dostupné možnosti ověřování.
Typ obsahu Požadovaná hlavička požadavku.
Určuje typ obsahu datové části.
Akceptovaná hodnota je application/json; charset=UTF-8.
Délka obsahu Požadovaná hlavička požadavku.
Délka textu požadavku.
X-ClientTraceId Volitelné.
Identifikátor GUID vygenerovaný klientem pro jedinečnou identifikaci požadavku. Tuto hlavičku můžete vynechat, pokud do řetězce dotazu zahrnete ID trasování pomocí parametru dotazu s názvem ClientTraceId.

Text požadavku

Text požadavku je pole JSON. Každý prvek pole je objekt JSON s řetězcovou vlastností s názvem Text, která představuje řetězec, který se má přeložit.

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

Informace o omezeních znaků a polí najdete v tématuOmezení požadavků.

Text odpovědi

Úspěšná odpověď je pole JSON s jedním výsledkem pro každý řetězec ve vstupním poli. Objekt výsledku obsahuje následující vlastnosti:

  • detectedLanguage: Objekt popisující rozpoznaný jazyk prostřednictvím následujících vlastností:

    • language: Řetězec představující kód zjištěného jazyka.

    • score: Plovoucí hodnota označující spolehlivost výsledku. Skóre je mezi nulou a jedním a nízkým skóre označuje nízkou spolehlivost.

      Vlastnost detectedLanguage je přítomna pouze ve výsledném objektu v případě, že je požadováno automatické rozpoznávání jazyka.

  • translations: Pole výsledků překladu. Velikost pole odpovídá počtu cílových jazyků zadaných parametrem to dotazu. Každý prvek v poli zahrnuje:

    • to: Řetězec představující kód jazyka cílového jazyka.

    • text: Řetězec s přeloženým textem.

  • transliteration: Objekt s přeloženým textem ve skriptu určeném parametrem toScript .

    • script: Řetězec určující cílový skript.

    • text: Řetězec s přeloženým textem v cílovém skriptu.

      Objekt transliteration není zahrnut, pokud se neprovádí transliterace.

      • alignment: Objekt s jednou řetězcovou vlastností pojmenovanou proj, která mapuje vstupní text na přeložený text. Informace o zarovnání jsou poskytovány pouze v případě, že parametr includeAlignment požadavku je true. Zarovnání se vrátí jako řetězcová hodnota následujícího formátu: [[SourceTextStartIndex]:[SourceTextEndIndex]–[TgtTextStartIndex]:[TgtTextEndIndex]]. Dvojtečka odděluje počáteční a koncový index, přerušovaná čárka odděluje jazyky a mezeru odděluje slova. Jedno slovo může být přidružené žádnému, jednomu nebo více slovům v jiném jazyce a přidružená slova můžou být nesouvislá. Pokud nejsou k dispozici žádné informace o zarovnání, prvek zarovnání bude prázdný. Viz Získání informací o zarovnání pro příklad a omezení.
  • sentLen: Objekt vracející hranice vět ve vstupních a výstupních textech.

    • srcSentLen: Celočíselná matice představující délky vět ve vstupním textu. Délka pole je počet vět a hodnoty jsou délka každé věty.

    • transSentLen: Celočíselná matice představující délky vět v přeloženého textu. Délka pole je počet vět a hodnoty jsou délka každé věty.

      Hranice vět jsou zahrnuty pouze v případě, že parametr požadavku includeSentenceLength je true.

  • sourceText: Objekt s jednou řetězcovou vlastností pojmenovanou text, která dává vstupní text ve výchozím skriptu zdrojového jazyka. sourceText vlastnost je přítomna pouze v případě, že vstup je vyjádřen ve skriptu, který není obvyklým skriptem jazyka. Pokud by byl například vstup napsaný v latince sourceText.text , byl by stejný arabský text převedený na arabský skript.

Příklady odpovědí JSON jsou uvedeny v části Příklady .

Hlavičky odpovědi

Hlavičky Description
X-requestid Hodnota generovaná službou k identifikaci požadavku. Používá se k řešení potíží.
X-mt-system Určuje typ systému, který byl použit k překladu pro každý jazyk "do" požadovaného pro překlad. Hodnota je seznam řetězců oddělený čárkami. Každý řetězec označuje typ:

* Vlastní – Požadavek zahrnuje vlastní systém a při překladu byl použit aspoň jeden vlastní systém.
* Tým – Všechny ostatní žádosti
Využití s měřením X Určuje spotřebu (počet znaků, za které bude uživatel účtován) pro žádost o úlohu překladu. Pokud je například slovo "Hello" přeloženo z angličtiny (en) do francouzštiny (fr), vrátí toto pole hodnotu 5.

Stavové kódy odpovědí

Následuje možné stavové kódy HTTP, které požadavek vrátí.

Stavový kód Description
200 Úspěch.
400 Jeden z parametrů dotazu chybí nebo je neplatný. Před opakováním opravte parametry požadavku.
401 Požadavek nelze ověřit. Zkontrolujte, jestli jsou zadané a platné přihlašovací údaje.
403 Požadavek není autorizovaný. Zkontrolujte chybovou zprávu podrobností. Tento stavový kód často značí, že byly využity všechny bezplatné překlady poskytované zkušebním předplatným.
408 Požadavek nelze splnit, protože chybí prostředek. Zkontrolujte chybovou zprávu podrobností. Pokud požadavek obsahuje vlastní kategorii, tento stavový kód často značí, že vlastní systém překladu ještě není k dispozici pro poskytování požadavků. Požadavek by se měl opakovat po čekací době (například 1 minutu).
429 Server žádost odmítl, protože klient překročil limity požadavků.
500 Došlo k neočekávané chybě. Pokud chyba přetrvává, nahlašte ji s datem a časem selhání, identifikátorem požadavku z hlavičky X-RequestId odpovědi a identifikátorem klienta z hlavičky požadavku X-ClientTraceId.
503 Server je dočasně nedostupný. Zkuste požadavek zopakovat. Pokud chyba přetrvává, nahlašte ji s datem a časem selhání, identifikátorem požadavku z hlavičky X-RequestId odpovědi a identifikátorem klienta z hlavičky požadavku X-ClientTraceId.

Pokud dojde k chybě, požadavek vrátí také chybovou odpověď JSON. Kód chyby je 6místné číslo, které kombinuje 3místný stavový kód HTTP následovaný 3místným číslem pro další kategorizaci chyby. Běžné kódy chyb najdete na referenční stránce služby Translator v3.

Příklady

Překlad jednoho vstupu

Tento příklad ukazuje, jak přeložit jednu větu z angličtiny do zjednodušené čínštiny.

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 odpovědi je:

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

Pole translations obsahuje jeden prvek, který poskytuje překlad jediné části textu ve vstupu.

Překlad jednoho vstupu pomocí automatického rozpoznávání jazyka

Tento příklad ukazuje, jak přeložit jednu větu z angličtiny do zjednodušené čínštiny. Požadavek nezadává jazyk zadávání. Místo toho se používá automatické rozpoznávání zdrojového jazyka.

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?'}]"

Text odpovědi je:

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

Odpověď je podobná odpovědi z předchozího příkladu. Vzhledem k tomu, že bylo požadováno automatické rozpoznávání jazyka, obsahuje odpověď také informace o jazyce zjištěném pro vstupní text. Automatické rozpoznávání jazyka funguje lépe s delším vstupním textem.

Překlad s transliterací

Pojďme předchozí příklad rozšířit přidáním transliterace. Následující žádost žádá o překlad v čínštině napsaný v latince.

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?'}]"

Text odpovědi je:

[
    {
        "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"
            }
        ]
    }
]

Výsledek překladu teď obsahuje transliteration vlastnost, která dává přeložený text pomocí latinek.

Překlad několika částí textu

Převod více řetězců najednou je jednoduše otázkou určení pole řetězců v textu požadavku.

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.'}]"

Odpověď obsahuje překlad všech částí textu ve stejném pořadí jako v požadavku. Text odpovědi je:

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

Překlad do více jazyků

Tento příklad ukazuje, jak v jednom požadavku přeložit stejný vstup do několika jazyků.

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?'}]"

Text odpovědi je:

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

Zpracování vulgárních výrazů

Za normálních okolností si služba Translator zachová vulgární výraz, který se nachází ve zdroji překladu. Stupeň vulgárního výrazu a kontextu, který činí slova vulgárními rozdíly mezi kulturami, a v důsledku toho může být stupeň vulgárního jazyka v cílovém jazyce amplifikován nebo snížen.

Pokud chcete zabránit vulgárnímu vulgárnímu překladu bez ohledu na přítomnost vulgárního textu, můžete použít možnost filtrování vulgárních výrazů. Tato možnost vám umožní zvolit, jestli chcete zobrazit odstranění vulgárních výrazů, ať už chcete označit vulgární výrazy odpovídajícími značkami (dáváte možnost přidat vlastní zpracování) nebo nechcete provádět žádnou akci. Akceptované hodnoty ProfanityAction jsou Deleteda MarkedNoAction (výchozí).

Vulgární akce Akce
NoAction NoAction je výchozí chování. Vulgární verze se předá ze zdroje do cíle.

Příklad zdroje (japonština):: 彼はジャッカスです。
Příklad překladu (angličtina):: Je to jack---.
Deleted Vyměněná slova budou z výstupu odebrána bez nahrazení.

Příklad zdroje (japonština):: 彼はジャッカスです。
Příklad překladu (angličtina):*
Marked Vyměněná slova jsou ve výstupu nahrazena značkou. Značka závisí na parametru ProfanityMarker .

Vyměněná ProfanityMarker=Asteriskslova jsou nahrazena ***:
Příklad zdroje (japonština):: 彼はジャッカスです。
Příklad překladu (angličtina): Je to \\\*.

Pro ProfanityMarker=Tag, profane slova jsou obklopeny XML značky <vulgární> a </vulgární:>
Příklad zdroje (japonština):: 彼はジャッカスです。
Příklad překladu (angličtina):: Je to vulgární <>jack---</vulgární.>

Příklad:

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.'}]"

Tento požadavek vrátí:

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

Porovnat s:

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.'}]"

Poslední požadavek vrátí:

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

Přeložte obsah pomocí revizí a rozhodněte se, co je přeložené.

Běžně se překládá obsah, který obsahuje značky, jako je například obsah ze stránky HTML nebo obsahu z dokumentu XML. Při překladu obsahu se značkami zahrňte parametr textType=html dotazu. Kromě toho je někdy užitečné vyloučit konkrétní obsah z překladu. Atribut můžete použít class=notranslate k určení obsahu, který by měl zůstat v původním jazyce. V následujícím příkladu se obsah uvnitř prvního div prvku nepřeloží, zatímco obsah ve druhém div prvku se přeloží.

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

Tady je ukázkový požadavek na ilustraci.

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>'}]"

Odpověď je:

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

Získání informací o zarovnání

Přidružení se vrátí jako řetězcová hodnota následujícího formátu pro každé slovo zdroje. Informace pro každé slovo jsou oddělené mezerou, včetně jazyků (skriptů), které nepoužívají k oddělování mezeru, jako je čínština:

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

Příklad řetězce přidružení: "0:0-7:10 1:2-11:20 3:4-0:3 3:4-4:6 5:5-21:21".

Jinými slovy, dvojtečka odděluje počáteční a koncový index, pomlčka odděluje jazyky a mezera odděluje slova. Jedno slovo může být přidružené žádnému, jednomu nebo více slovům v jiném jazyce a přidružená slova můžou být nesouvislá. Pokud nejsou k dispozici žádné informace o přidružení, element Alignment bude prázdný. Metoda v takovém případě nevrací žádnou chybu.

Chcete-li přijímat informace o zarovnání, zadejte includeAlignment=true řetězec dotazu.

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.'}]"

Odpověď je:

[
    {
        "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"}
            }
        ]
    }
]

Informace o zarovnání začínají znakem 0:2-0:1, což znamená, že první tři znaky ve zdrojovém textu (The) se mapují na první dva znaky přeloženého textu (La).

Omezení

Získání informací o zarovnání je experimentální funkce, kterou jsme povolili pro vytváření prototypů výzkumu a zkušeností s potenciálními mapováními frází. V budoucnu se můžeme rozhodnout tuto funkci přestat podporovat. Tady jsou některá z případných omezení, která se nepodporují:

  • Zarovnání není k dispozici pro text ve formátu HTML, což je textType=html.
  • Zarovnání se vrátí jenom pro podmnožinu dvojic jazyků:
    • Angličtina do/z libovolného jiného jazyka s výjimkou čínštiny tradiční, kantoštiny (tradiční) nebo srbštiny (cyrilice).
    • z japonštiny do korejštiny nebo z korejštiny na japonštinu.
    • od japonštiny po zjednodušenou čínštinu a zjednodušenou čínštinu do japonštiny.
    • od čínštiny od zjednodušené čínštiny do tradiční čínštiny a tradiční čínštiny do zjednodušené čínštiny.
  • Pokud je věta naskenovaným překladem, nedostanete zarovnání. Příkladem naskenovaného překladu je "Toto je test", "Miluji vás" a další věty s vysokou frekvencí.
  • Zarovnání není k dispozici, pokud použijete některý z přístupů, abyste zabránili překladu, jak je popsáno tady.

Získání hranic vět

Pokud chcete získat informace o délce vět ve zdrojovém textu a přeložený text, zadejte includeSentenceLength=true řetězec dotazu.

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.'}]"

Odpověď je:

[
    {
        "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]}
            }
        ]
    }
]

Překlad s dynamickým slovníkem

Pokud už znáte překlad, který chcete použít pro slovo nebo frázi, můžete ho zadat jako revizi v rámci požadavku. Dynamický slovník je bezpečný pouze pro správné podstatná jména, jako jsou osobní jména a názvy produktů. Poznámka: Funkce dynamického slovníku rozlišuje malá a velká písmena.

Kód, který se má zadat, používá následující syntaxi.

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

Představte si například anglickou větu "Slovo wordomatic je položka slovníku". Pokud chcete zachovat slovo wordomatic v překladu, odešlete žádost:

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.'}]"

Výsledek je:

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

Tato funkce dynamického slovníku funguje stejným způsobem s textType=text nebo s textType=html. Tato funkce by měla být použita střídmě. Vhodným a mnohem lepším způsobem přizpůsobení překladu je použití služby Custom Translator. Custom Translator plně využívá kontextové a statistické pravděpodobnosti. Pokud můžete vytvořit trénovací data, která zobrazují vaši práci nebo frázi v kontextu, získáte mnohem lepší výsledky. Přečtěte si další informace o službě Custom Translator.

Další kroky