Dela via

Translator 3.0: Översätt

  • Artikel

Översätter text.

Begärans-URL

Skicka en POST-begäran till:

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

Se Stöd för virtuellt nätverk för Translator-tjänsten valt nätverk och privat slutpunktskonfiguration och support.

Parametrar för begäran

Begärandeparametrar som skickas på frågesträngen är:

Obligatoriska parametrar

Frågeparameter beskrivning
api-version Obligatorisk parameter.
Version av API:et som begärs av klienten. Värdet måste vara 3.0.
to Obligatorisk parameter.
Anger språket för utdatatexten. Målspråket måste vara ett av de språk som stöds i omfångettranslation. Använd till exempel to=de för att översätta till tyska.
Det går att översätta till flera språk samtidigt genom att upprepa parametern i frågesträngen. Använd till exempel to=de&to=it för att översätta till tyska och italienska.

Valfria parametrar

Frågeparameter beskrivning
från Valfri parameter.
Anger språket för indatatexten. Ta reda på vilka språk som är tillgängliga att översätta från genom att leta upp språk som stöds med hjälp av omfånget translation . Om parametern from inte anges tillämpas automatisk språkidentifiering för att fastställa källspråket.

Du måste använda parametern from i stället för autodetection när du använder funktionen för dynamisk ordlista . Obs! Funktionen för dynamisk ordlista är skiftlägeskänslig.
textType Valfri parameter.
Definierar om texten som översätts är oformaterad text eller HTML-text. Html-kod måste vara ett välformat, komplett element. Möjliga värden är: plain (standard) eller html.
category Valfri parameter.
En sträng som anger översättningens kategori (domän). Den här parametern används för att hämta översättningar från ett anpassat system som skapats med Custom Translator. Om du vill använda ditt distribuerade anpassade system lägger du till kategori-ID:t från projektinformationen för Custom Translator i kategoriparametern. Standardvärdet är: general.
profanityAction Valfri parameter.
Anger hur svordomar ska behandlas i översättningar. Möjliga värden är: NoAction (standard), Marked, eller Deleted. Information om hur du behandlar svordomar finns i Svordomshantering.
profanityMarker Valfri parameter.
Anger hur svordomar ska markeras i översättningar. Möjliga värden är: Asterisk (standard) eller Tag. Information om hur du behandlar svordomar finns i Svordomshantering.
includeAlignment Valfri parameter.
Anger om justeringsprojicering ska inkluderas från källtext till översatt text. Möjliga värden är: true eller false (standard).
includeSentenceLength Valfri parameter.
Anger om meningsgränser ska inkluderas för indatatexten och den översatta texten. Möjliga värden är: true eller false (standard).
suggestedFrom Valfri parameter.
Anger ett reservspråk om språket i indatatexten inte kan identifieras. Autodetection för språk tillämpas när parametern from utelämnas. Om identifieringen suggestedFrom misslyckas antas språket.
fromScript Valfri parameter.
Anger skriptet för indatatexten.
toScript Valfri parameter.
Anger skriptet för den översatta texten.
allowFallback Valfri parameter.
Anger att tjänsten tillåts återgå till ett allmänt system när det inte finns något anpassat system. Möjliga värden är: true (standard) eller false.

allowFallback=false anger att översättningen endast ska använda system som tränats för den category som anges av begäran. Om en översättning från språk X till språk Y kräver länkning via ett pivotspråk E måste alla system i kedjan (X → E och E → Y) vara anpassade och ha samma kategori. Om inget system hittas med den specifika kategorin returnerar begäran en statuskod på 400. allowFallback=true anger att tjänsten tillåts återgå till ett allmänt system när det inte finns något anpassat system.

Bland begäranderubrikerna finns:

Sidhuvuden beskrivning
Autentiseringshuvuden Obligatoriskt begärandehuvud.
Se tillgängliga alternativ för autentisering.
Innehållstyp Obligatoriskt begärandehuvud.
Anger nyttolastens innehållstyp.
Godkänt värde är application/json; charset=UTF-8.
Innehållslängd Valfritt.
Längden på begärandetexten.
X-ClientTraceId Valfritt.
Ett klientgenererat GUID för att unikt identifiera begäran. Du kan utelämna den här rubriken om du inkluderar spårnings-ID:t i frågesträngen med hjälp av en frågeparameter med namnet ClientTraceId.

Begärandetext

Brödtexten i begäran är en JSON-matris. Varje matriselement är ett JSON-objekt med en strängegenskap med namnet Text, som representerar strängen som ska översättas.

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

Information om tecken- och matrisgränser finns i Begränsningar för begäran.

Själva svaret

Ett lyckat svar är en JSON-matris med ett resultat för varje sträng i indatamatrisen. Ett resultatobjekt innehåller följande egenskaper:

  • detectedLanguage: Ett objekt som beskriver det identifierade språket via följande egenskaper:

    • language: En sträng som representerar koden för det identifierade språket.

    • score: Ett flyttalsvärde som anger konfidensen i resultatet. Poängen är mellan noll och en och en låg poäng indikerar ett lågt förtroende.

    Egenskapen detectedLanguage finns bara i resultatobjektet när autodetection för språk begärs.

  • translations: En matris med översättningsresultat. Matrisens storlek matchar antalet målspråk som anges via frågeparametern to . Varje element i matrisen innehåller:

    • to: En sträng som representerar språkkoden för målspråket.

    • text: En sträng som ger den översatta texten.

    • transliteration: Ett objekt som ger den översatta texten i skriptet som anges av parametern toScript .

      • script: En sträng som anger målskriptet.

      • text: En sträng som ger den översatta texten i målskriptet.

      Objektet transliteration ingår inte om transkriberingen inte sker.

      • alignment: Ett objekt med en enskild strängegenskap med namnet proj, som mappar indatatext till översatt text. Justeringsinformationen tillhandahålls endast när parametern includeAlignment för begäran är true. Justering returneras som ett strängvärde i följande format: [[SourceTextStartIndex]:[SourceTextEndIndex]–[TgtTextStartIndex]:[TgtTextEndIndex]]. Kolonet separerar start- och slutindex, strecket separerar språken och blanksteget separerar orden. Ett ord kan vara i linje med noll, ett eller flera ord på det andra språket, och de justerade orden kan vara icke-sammanhängande. När ingen justeringsinformation är tillgänglig är justeringselementet tomt. Se Hämta justeringsinformation för ett exempel och begränsningar.

    • sentLen: Ett objekt som returnerar meningsgränser i indata- och utdatatexterna.

      • srcSentLen: En heltalsmatris som representerar längden på meningarna i indatatexten. Matrisens längd är antalet meningar och värdena är längden på varje mening.

      • transSentLen: En heltalsmatris som representerar längden på meningarna i den översatta texten. Matrisens längd är antalet meningar och värdena är längden på varje mening.

      Meningsgränser inkluderas endast när parametern includeSentenceLength för begäran är true.

  • sourceText: Ett objekt med en enskild strängegenskap med namnet text, som ger indatatexten i standardskriptet för källspråket. sourceText egenskapen finns bara när indata uttrycks i ett skript som inte är det vanliga skriptet för språket. Om indata till exempel var arabiska skrivna i latinskt skript skulle det sourceText.text vara samma arabiska text som konverterats till arabiskt skript.

Exempel på JSON-svar finns i exempelavsnittet.

Svarsrubriker

Sidhuvuden beskrivning
X-requestid Värde som genereras av tjänsten för att identifiera den begäran som används för felsökning.
X-mt-system Anger den systemtyp som användes för översättning för varje "till"-språk som begärdes för översättning. Värdet är en kommaavgränsad lista med strängar. Varje sträng anger en typ:

Anpassad – Begäran innehåller ett anpassat system och minst ett anpassat system användes under översättningen.
Team – Alla andra begäranden
X-mätningsanvändning Anger förbrukning (antalet tecken som användaren debiteras för) för översättningsjobbets begäran. Om ordet "Hello" till exempel översätts från engelska (en) till franska (fr) returnerar det här fältet värdet 5.

Svarsstatuskoder

Följande är de möjliga HTTP-statuskoder som en begäran returnerar.

Statuskod beskrivning
200 Klart!
400 En av frågeparametrarna saknas eller är ogiltig. Korrigera parametrar för begäran innan du försöker igen.
401 Det gick inte att autentisera begäran. Kontrollera att autentiseringsuppgifterna är angivna och giltiga.
403 Begäran är inte auktoriserad. Kontrollera informationsfelmeddelandet. Den här statuskoden anger ofta att du använde alla kostnadsfria översättningar som tillhandahålls med en utvärderingsprenumeration.
408 Det gick inte att uppfylla begäran eftersom en resurs saknas. Kontrollera informationsfelmeddelandet. När begäran innehåller en anpassad kategori anger den här statuskoden ofta att det anpassade översättningssystemet ännu inte är tillgängligt för att hantera begäranden. Begäran bör göras om efter en väntetid (till exempel 1 minut).
429 Servern avvisade begäran eftersom klienten överskred begärandegränserna.
500 Ett oväntat fel har uppstått. Om felet kvarstår rapporterar du det med: datum och tid för felet, begärandeidentifierare från svarshuvudet X-RequestId och klientidentifierare från begärandehuvudet X-ClientTraceId.
503 Servern är inte tillgänglig för tillfället. Försök igen med begäran. Om felet kvarstår rapporterar du det med: datum och tid för felet, begärandeidentifierare från svarshuvudet X-RequestId och klientidentifierare från begärandehuvudet X-ClientTraceId.

Om ett fel inträffar returnerar begäran ett JSON-felsvar. Felkoden är ett 6-siffrigt tal som kombinerar den tresiffriga HTTP-statuskoden följt av ett tresiffrigt tal för att ytterligare kategorisera felet. Vanliga felkoder finns på referenssidan för Translator v3.

Exempel

Översätta en enda indata

Det här exemplet visar hur du översätter en enda mening från engelska till förenklad kinesiska.

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

Svarstexten är:

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

Matrisen translations innehåller ett element som ger översättning av den enda textdelen i indata.

Översätta en enda indata med språk autodetection

Det här exemplet visar hur du översätter en enda mening från engelska till förenklad kinesiska. Begäran anger inte indataspråket. Autodetection av källspråket används i stället.

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

Svarstexten är:

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

Svaret liknar svaret från föregående exempel. Eftersom automatisk språkdetection begärdes innehåller svaret även information om det språk som identifierats för indatatexten. Autodetection för språk fungerar bättre med längre indatatext.

Översätt med transkribering

Nu ska vi utöka föregående exempel genom att lägga till transliteration. I följande begäran begärs en kinesisk översättning skriven i latinskt skript.

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

Svarstexten är:

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

Översättningsresultatet innehåller nu en transliteration egenskap som ger den översatta texten med latinska tecken.

Översätta flera textstycken

Att översätta flera strängar samtidigt handlar helt enkelt om att ange en matris med strängar i begärandetexten.

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

Svaret innehåller översättningen av alla textstycken i exakt samma ordning som i begäran. Svarstexten är:

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

Översätt till flera språk

Det här exemplet visar hur du översätter samma indata till flera språk i en begäran.

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

Svarstexten är:

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

Hantera svordomar

Normalt behåller Translator-tjänsten svordomar som finns i källan i översättningen. Graden av svordomar och det sammanhang som gör ord profana skiljer sig åt mellan kulturer, och därför kan graden av svordomar i målspråket förstärkas eller minskas.

Om du vill undvika att få svordomar i översättningen, oavsett förekomsten av svordomar i källtexten, kan du använda alternativet för svordomsfiltrering. Med alternativet kan du välja om du vill se svordomar borttagna, markerade med lämpliga taggar (vilket ger dig möjlighet att lägga till din egen efterbearbetning) eller om ingen åtgärd har vidtagits. De godkända värdena ProfanityAction för är Deleted, Markedoch NoAction (standard).

Godkänt profanityAction-värde ProfanityMarker-värde Åtgärd Exempel: Källspråk – spanska Exempel: Målspråk – engelska
NoAction Standard. Samma som att inte ställa in det här alternativet. Olämpligt språk skickas från källan till målet. Que coche de<insert-profane-word> <Vilken insert-profane-word> bil
Marked Asterisk Asterisker ersätter olämpliga ord (standard). Que coche de<insert-profane-word> What a *** car
Marked Tagg Profana ord omges av svordomar> för XML-taggar<...</svordomar>. Que coche de<insert-profane-word> <Vilken svordom><insert-profane-word></svordomsbil>
Borttagen Olämpliga ord tas bort från utdata och ersätts inte. Que coche de<insert-profane-word> What a car

I exemplen ovan <är insert-profane-word> en platshållare för olämpliga ord.

Till exempel:

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

Den här begäran returnerar:

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

Jämför med:

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

Den senaste begäran returnerar:

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

Översätta innehåll som innehåller markering

Det är vanligt att översätta innehåll som innehåller markering, till exempel innehåll från en HTML-sida eller innehåll från ett XML-dokument. Inkludera frågeparameter textType=html när du översätter innehåll med taggar. Dessutom är det ibland användbart att undanta specifikt innehåll från översättning. Du kan använda attributet class=notranslate för att ange innehåll som ska finnas kvar på ursprungsspråket. I följande exempel översätts inte innehållet i det första div elementet, medan innehållet i det andra div elementet översätts.

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

Här är en exempelbegäran som ska illustreras.

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

Svaret är:

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

Hämta justeringsinformation

Justering returneras som ett strängvärde i följande format för varje ord i källan. Informationen för varje ord avgränsas med ett blanksteg, inklusive för icke-blankstegsavgränsade språk (skript) som kinesiska:

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

Exempel på justeringssträng: ”0:0-7:10 1:2-11:20 3:4-0:3 3:4-4:6 5:5-21:21”.

Med andra ord separerar kolonet start- och slutindex, strecket separerar språken och blanksteg separerar orden. Ett ord kan vara i linje med noll, ett eller flera ord på det andra språket, och de justerade orden kan vara icke-sammanhängande. När ingen justeringsinformation är tillgänglig är justeringselementet tomt. Metoden returnerar inget fel i det fallet.

Om du vill ta emot justeringsinformation anger du includeAlignment=true i frågesträngen.

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

Svaret är:

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

Justeringsinformationen börjar med 0:2-0:1, vilket innebär att de första tre tecknen i källtexten (The) mappas till de två första tecknen i den översatta texten (La).

Begränsningar

Att få justeringsinformation är en experimentell funktion som vi har aktiverat för prototyper av forskning och upplevelser med potentiella frasmappningar. Här följer några av de viktigaste begränsningarna där justering inte stöds:

  • Justering är inte tillgängligt för text i HTML-format, d.v.s. textType=html
  • Justering returneras endast för en delmängd av språkparen:
    • Engelska till/från andra språk förutom traditionell kinesiska, kantonesiska (traditionell) eller serbiska (kyrillisk)
    • från japanska till koreanska eller från koreanska till japanska
    • från japanska till kinesiska förenklad och kinesiska förenklad till japanska
    • från kinesiska förenklad till kinesiska traditionell och kinesisk traditionell till kinesiska förenklad
  • Du justerar inte om meningen är en konserverad översättning. Exempel på en konserverad översättning är This is a test, I love youoch andra högfrekventa meningar
  • Justering är inte tillgängligt när du använder någon av metoderna för att förhindra översättning enligt beskrivningen här

Hämta meningsgränser

Om du vill få information om meningslängden i källtexten och översatt text anger du includeSentenceLength=true i frågesträngen.

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

Svaret är:

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

Översätt med dynamisk ordlista

Om du redan känner till den översättning som du vill använda för ett ord eller en fras kan du ange den som markering i begäran. Den dynamiska ordlistan är bara säker för lämpliga substantiv, till exempel personliga namn och produktnamn. Obs! Funktionen för dynamisk ordlista är skiftlägeskänslig.

Markering som ska anges använder följande syntax.

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

Tänk till exempel på den engelska meningen "Ordet ordomatisk är en ordlistepost". Skicka begäran för att bevara ordet ordomatiskt i översättningen:

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

Resultatet är:

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

Den här funktionen för dynamisk ordlista fungerar på samma sätt med textType=text eller med textType=html. Funktionen bör användas sparsamt. Det lämpliga och mycket bättre sättet att anpassa översättningen är att använda Custom Translator. Custom Translator använder kontext och statistiska sannolikheter fullt ut. Om du kan skapa träningsdata som visar ditt arbete eller din fras i kontext får du bättre resultat. Läs mer om Custom Translator.

Nästa steg

Prova Translator-snabbstarten