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

VizPodpora virtuální sítě pro vybranou službu Translator a konfiguraci a podporu privátního koncového bodu.

Parametry požadavku

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

Povinné 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. Slouží to=de například k překladu do němčiny.
Parametr v řetězci dotazu je možné přeložit na více jazyků současně. Slouží to=de&to=it například k překladu do němčiny a italštiny.

Volitelné parametry

Parametr dotazu Popis
od 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íku from je nutné místo automatického rozpoznávání použít parametr. Poznámka: Funkce dynamického slovníku rozlišují malá a velká písmena.
textType Volitelný parametr.
Definuje, zda je přeložený text prostým textem nebo textem HTML. Libovolný 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í custom Translatoru. Pokud chcete použít nasazený přizpůsobený systém, přidejte ID kategorie z podrobností projektu Custom Translator do parametru kategorie. Výchozí hodnota je: general.
vulgární akce Volitelný parametr.
Určuje, jak se mají v překladech zpracovávat vulgární výrazy. Možné hodnoty jsou: NoAction (výchozí), Markednebo Deleted. Informace o způsobech zacházení s vulgárním výrazem najdete v tématu Zpracování vulgárních výrazů.
vulgární výrazMarker Volitelný parametr.
Určuje, jak se mají v překladech označovat vulgární výrazy. Možné hodnoty jsou: Asterisk (výchozí) nebo Tag. Informace o způsobech zacházení s vulgárním výrazem najdete v tématu Zpracování 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, jestli 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. Autodetection jazyka se použije při vynechání parametru from . Pokud se detekce nezdaří, předpokládá se, ž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 z jazyka X do jazyka Y vyžaduje řetězení v kontingenčním jazyce E, musí být všechny systémy v řetězci (X → E a E → Y) 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 Popis
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 k překladu.

[
    {"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. Výsledný objekt 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: Hodnota float označující spolehlivost ve 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, pokud je požadováno autodetection jazyka.

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

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

    • text: Řetězec, který dává přeložený text.

    • transliteration: Objekt, který dává přeložený text ve skriptu určeném parametrem toScript .

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

      • text: Řetězec, který dává přeložený text v cílovém skriptu.

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

      • alignment: Objekt s jednou řetězcovou vlastností s názvem proj, která mapuje vstupní text na přeložený text. Informace o zarovnání jsou poskytovány pouze v případech, kdy je trueparametr includeAlignment požadavku . Zarovnání je vráceno jako řetězcová hodnota následujícího formátu: [[SourceTextStartIndex]:[SourceTextEndIndex]–[TgtTextStartIndex]:[TgtTextEndIndex]]. 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 zarovnané s nulou, jedním nebo více slovy v jiném jazyce a zarovnaná slova mohou být nesouvislé. Pokud nejsou k dispozici žádné informace o zarovnání, prvek zarovnání je prázdný. Příklad a omezení najdete v tématu Získání informací o zarovnání.
    • sentLen: Objekt vracející hranice vět ve vstupním a výstupním textu.

      • 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élkou 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élkou každé věty.

      Hranice vět jsou zahrnuty pouze v případech, kdy je trueparametr includeSentenceLength požadavku .

  • sourceText: Objekt s jednou řetězcovou vlastností s názvem 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 pro jazyk. Pokud byl například vstup napsaný v latince, byl sourceText.text 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 Popis
X-requestid Hodnota vygenerovaná službou k identifikaci požadavku používaného pro účely řešení potíží.
X-mt-system Určuje typ systému, který byl použit pro překlad pro každý jazyk "to" požadovaný pro překlad. Hodnota je čárkami oddělený seznam řetězců. 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í měřeného X Určuje spotřebu (počet znaků, za které se uživateli účtuje) žá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íže jsou uvedené možné stavové kódy HTTP, které požadavek vrátí.

Stavový kód Popis
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 s podrobnostmi. Tento stavový kód často označuje, že jste použili všechny bezplatné překlady poskytnuté se zkušebním předplatným.
408 Požadavek nelze splnit, protože chybí prostředek. Zkontrolujte chybovou zprávu s podrobnostmi. Pokud požadavek obsahuje vlastní kategorii, tento stavový kód často značí, že vlastní systém překladu ještě není k dispozici pro obsluhu požadavků. Požadavek by se měl opakovat po čekací době (například 1 minutu).
429 Server odmítl požadavek, 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í chybovou odpověď JSON. Kód chyby je 6místné číslo, které kombinuje 3místný stavový kód HTTP následovaný 3místným číslem, aby se chyba dále kategorizovala. 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?'}]"

Tělo odpovědi je:

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

Pole translations obsahuje jeden prvek, který poskytuje překlad jednoho 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á 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?'}]"

Tělo 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, odpověď obsahuje 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 transkliterací

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

Tělo 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 více částí textu

Překlad více řetězců najednou je jednoduše otázkou zadání 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. Tělo odpovědi je:

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

Překlad do více jazyků

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

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

Tělo 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í služba Translator uchovává vulgární výrazy, které se nacházejí ve zdroji v 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 zesílen nebo snížen.

Pokud se chcete vyhnout vulgárnímu vulgárnímu výrazu v překladu bez ohledu na přítomnost vulgárních výrazů ve zdrojovém textu, můžete použít možnost filtrování vulgárních výrazů. Tato možnost vám umožní zvolit, jestli chcete zobrazovat odstranění vulgárních výrazů označených odpovídajícími značkami (abyste mohli přidat vlastní po zpracování), nebo bez provedení akce. Přijaté hodnoty ProfanityAction jsou Deleted, Markeda NoAction (výchozí).

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

Příklad zdroje (japonština):彼はジャッカスです。
Příklad překladu (angličtina):: Je to jack---.
Deleted Vulgární slova se bez náhrady odeberou z výstupu.

Příklad zdroje (japonština):彼はジャッカスです。
Příklad překladu (angličtina):*
Marked Značka nahradí označené slovo ve výstupu. Značka závisí na parametru ProfanityMarker .

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

Vulgární ProfanityMarker=Tagslova jsou obklopena vulgárními> výrazy <XML a </vulgárními výrazy>:
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řeklad obsahu, který obsahuje revize

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 není obsah uvnitř prvního div prvku přeložen, zatímco obsah v druhém div prvku je přeložen.

<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 zarovnané s nulou, jedním nebo více slovy v jiném jazyce a zarovnaná slova mohou být nesouvislé. Pokud nejsou k dispozici žádné informace o zarovnání, element Alignment je prázdný. Metoda v takovém případě nevrací žádnou chybu.

Pokud chcete získat informace o zarovnání, zadejte includeAlignment=true v řetězci 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í textem 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í. Tady jsou některá z hledných omezení, u kterých nejsou podporována zarovnání:

  • Zarovnání není k dispozici pro text ve formátu HTML, tedy textType=html
  • Zarovnání se vrátí pouze pro podmnožinu párů jazyka:
    • Angličtina do/z jakéhokoli jiného jazyka kromě čínštiny tradiční, kantonštiny (tradiční) nebo srbštiny (cyrilice)
    • z japonštiny do korejštiny nebo korejštiny do japonštiny
    • z japonštiny na zjednodušenou čínštinu a zjednodušenou čínštinu do japonštiny
    • zjednodušená čínština do čínštiny (tradiční čínština) a čínština (tradiční) do čínštiny (zjednodušená čínština)
  • Zarovnání nezarovnáte, pokud je věta naskenovaným překladem. Příklad naskenovaného překladu je This is a test, I love youa 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

Chcete-li získat informace o délce věty ve zdrojovém textu a přeložený text, zadejte includeSentenceLength=true v řetězci 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 pomocí dynamického slovníku

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šují 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 požadavek:

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ýsledkem je:

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

Tato funkce dynamického slovníku funguje stejně s textType=text nebo s textType=html. Tato funkce by se měla používat 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 lepší výsledky. Přečtěte si další informace o službě Custom Translator.

Další kroky