Translator Text API 3.0: TranslateTranslator Text API 3.0: Translate

テキストを翻訳します。Translates text.

要求 URLRequest URL

POST 要求の送信先は次のとおりです。Send a POST request to:

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

要求パラメーターRequest parameters

クエリ文字列に渡される要求パラメーターを次に示します。Request parameters passed on the query string are:

Query parameter (クエリ パラメーター)Query parameter 説明Description
api-versionapi-version "必須のパラメーター"。Required parameter.
クライアントによって要求される API のバージョン。Version of the API requested by the client. 値は 3.0 とする必要があります。Value must be 3.0.
fromfrom "省略可能なパラメーター"。Optional parameter.
入力テキストの言語を指定します。Specifies the language of the input text. translation スコープを使用してサポートされている言語を検索することにより、翻訳することができるソース言語を確認します。Find which languages are available to translate from by looking up supported languages using the translation scope. from パラメーターが指定されていない場合は、自動言語検出が適用されてソース言語が特定されます。If the from parameter is not specified, automatic language detection is applied to determine the source language.

動的ディクショナリ機能を使用する場合は、自動検出ではなく、from パラメーターを使用する必要があります。You must use the from parameter rather than autodetection when using the dynamic dictionary feature.
toto "必須のパラメーター"。Required parameter.
出力テキストの言語を指定します。Specifies the language of the output text. ターゲット言語は、translation スコープに含まれているサポートされている言語のいずれかとする必要があります。The target language must be one of the supported languages included in the translation scope. たとえば、ドイツ語に翻訳するには to=de を使用します。For example, use to=de to translate to German.
クエリ文字列内でパラメーターを繰り返すことにより、同時に複数の言語に翻訳することができます。It's possible to translate to multiple languages simultaneously by repeating the parameter in the query string. たとえば、ドイツ語とイタリア語に翻訳するには、to=de&to=it を使用します。For example, use to=de&to=it to translate to German and Italian.
textTypetextType 省略可能なパラメーターOptional parameter.
翻訳するテキストがプレーン テキストか、それとも HTML テキストかを定義します。Defines whether the text being translated is plain text or HTML text. HTML の場合は、適切な形式の完全な要素である必要があります。Any HTML needs to be a well-formed, complete element. 指定できる値は plain (既定値) または html です。Possible values are: plain (default) or html.
categorycategory 省略可能なパラメーターOptional parameter.
翻訳のカテゴリ (ドメイン) を指定する文字列。A string specifying the category (domain) of the translation. このパラメーターは、Custom Translator でビルドしたカスタマイズされたシステムから翻訳を取得するために使用します。This parameter is used to get translations from a customized system built with Custom Translator. デプロイ済みのカスタマイズされたシステムを使用するには、カスタム翻訳ツール プロジェクトの詳細からこのパラメーターにカテゴリ ID を追加します。Add the Category ID from your Custom Translator project details to this parameter to use your deployed customized system. 既定値は general です。Default value is: general.
profanityActionprofanityAction 省略可能なパラメーターOptional parameter.
翻訳での不適切な表現の処理方法を指定します。Specifies how profanities should be treated in translations. 指定できる値は NoAction (既定値)、Marked、または Deleted です。Possible values are: NoAction (default), Marked or Deleted. 不適切な表現の処理方法を理解するには、不適切な表現の処理に関するセクションを参照してください。To understand ways to treat profanity, see Profanity handling.
profanityMarkerprofanityMarker 省略可能なパラメーターOptional parameter.
翻訳での不適切な表現のマーキング方法を指定します。Specifies how profanities should be marked in translations. 指定できる値は Asterisk (既定値) または Tag です。Possible values are: Asterisk (default) or Tag. 不適切な表現の処理方法を理解するには、不適切な表現の処理に関するセクションを参照してください。To understand ways to treat profanity, see Profanity handling.
includeAlignmentincludeAlignment 省略可能なパラメーターOptional parameter.
ソース テキストから翻訳済みテキストへのアライメント プロジェクションを含めるかどうかを指定します。Specifies whether to include alignment projection from source text to translated text. 指定できる値は true または false (既定値) です。Possible values are: true or false (default).
includeSentenceLengthincludeSentenceLength 省略可能なパラメーターOptional parameter.
入力テキストと翻訳済みテキストに対して文の境界を含めるかどうかを指定します。Specifies whether to include sentence boundaries for the input text and the translated text. 指定できる値は true または false (既定値) です。Possible values are: true or false (default).
suggestedFromsuggestedFrom 省略可能なパラメーターOptional parameter.
入力テキストの言語を識別できない場合のフォールバック言語を指定します。Specifies a fallback language if the language of the input text can't be identified. from パラメーターが省略されている場合は、言語自動検出が適用されます。Language auto-detection is applied when the from parameter is omitted. 検出に失敗した場合は、suggestedFrom 言語と見なされます。If detection fails, the suggestedFrom language will be assumed.
fromScriptfromScript 省略可能なパラメーターOptional parameter.
入力テキストのスクリプトを指定します。Specifies the script of the input text.
toScripttoScript 省略可能なパラメーターOptional parameter.
翻訳済みテキストのスクリプトを指定します。Specifies the script of the translated text.
allowFallbackallowFallback "省略可能なパラメーター"。Optional parameter.
カスタム システムが存在しない場合に、サービスが一般的なシステムにフォールバックできるかどうかを指定します。Specifies that the service is allowed to fallback to a general system when a custom system does not exist. 指定できる値は true (既定値) または false です。Possible values are: true (default) or false.

allowFallback=false は、要求によって指定された category 向けにトレーニングされているシステムのみを翻訳で使用することを指定します。allowFallback=false specifies that the translation should only use systems trained for the category specified by the request. 言語 X から言語 Y への翻訳で、中心言語 E を経由するチェーン処理が必要な場合、チェーン内のすべてのシステム (X->E と E->Y) はカスタムであり、同じカテゴリを持っている必要があります。If a translation for language X to language Y requires chaining through a pivot language E, then all the systems in the chain (X->E and E->Y) will need to be custom and have the same category. 特定のカテゴリを持つシステムが見つからない場合、要求は 400 状態コードを返します。If no system is found with the specific category, the request will return a 400 status code. allowFallback=true は、カスタム システムが存在しない場合は、サービスが一般的なシステムにフォールバックできることを指定します。allowFallback=true specifies that the service is allowed to fallback to a general system when a custom system does not exist.

要求ヘッダーには次のものがあります。Request headers include:

headersHeaders 説明Description
認証ヘッダーAuthentication header(s) "必須の要求ヘッダー" です。Required request header.
認証に使用できるオプションに関するページをご覧ください。See available options for authentication.
Content-TypeContent-Type "必須の要求ヘッダー" です。Required request header.
ペイロードのコンテンツ タイプを指定します。Specifies the content type of the payload.
指定できる値は application/json; charset=UTF-8 です。Accepted value is application/json; charset=UTF-8.
Content-LengthContent-Length "必須の要求ヘッダー" です。Required request header.
要求本文の長さです。The length of the request body.
X-ClientTraceIdX-ClientTraceId 省略可能Optional.
要求を一意に識別する、クライアントで生成された GUID。A client-generated GUID to uniquely identify the request. ClientTraceId という名前のクエリ パラメーターを使用してクエリ文字列内にトレース ID を含める場合、このヘッダーは省略できます。You can omit this header if you include the trace ID in the query string using a query parameter named ClientTraceId.

要求本文Request body

要求の本文は JSON 配列です。The body of the request is a JSON array. 各配列要素は、Text という名前の文字列プロパティ (翻訳するテキストを表す) を持つ JSON オブジェクトです。Each array element is a JSON object with a string property named Text, which represents the string to translate.

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

次の制限事項が適用されます。The following limitations apply:

  • 配列に含めることができる要素は、最大でも 100 個です。The array can have at most 100 elements.
  • 要求に含めるテキスト全体では、スペースも含めて 5,000 文字を超えてはなりません。The entire text included in the request cannot exceed 5,000 characters including spaces.

応答本文Response body

正常な応答は、入力配列内の文字列ごとに 1 つの結果が含まれる JSON 配列となります。A successful response is a JSON array with one result for each string in the input array. 結果オブジェクトには次のプロパティが含まれています。A result object includes the following properties:

  • detectedLanguage:次のプロパティによって、検出された言語を説明するオブジェクトです。detectedLanguage: An object describing the detected language through the following properties:

    • language:検出された言語のコードを表す文字列です。language: A string representing the code of the detected language.

    • score:結果内の信頼度を示す浮動小数点値です。score: A float value indicating the confidence in the result. スコアは 0 から 1 の範囲であり、低いスコアは低い信頼度を示します。The score is between zero and one and a low score indicates a low confidence.

    detectedLanguage プロパティは、言語自動検出が要求された場合に限り、結果オブジェクト内に存在します。The detectedLanguage property is only present in the result object when language auto-detection is requested.

  • translations:翻訳結果の配列です。translations: An array of translation results. 配列のサイズは、to クエリ パラメーターを通して指定されたターゲット言語の数に一致します。The size of the array matches the number of target languages specified through the to query parameter. 配列内の各要素は次のとおりです。Each element in the array includes:

    • to:ターゲット言語の言語コードを表す文字列です。to: A string representing the language code of the target language.

    • text:翻訳済みテキストを提供する文字列です。text: A string giving the translated text.

    • transliteration:toScript パラメーターによって指定されたスクリプトで、翻訳済みテキストを提供するオブジェクトです。transliteration: An object giving the translated text in the script specified by the toScript parameter.

      • script:ターゲット スクリプトを指定する文字列です。script: A string specifying the target script.

      • text:ターゲット スクリプトで翻訳済みテキストを提供する文字列です。text: A string giving the translated text in the target script.

    翻訳が実行されない場合、transliteration オブジェクトは含められません。The transliteration object is not included if transliteration does not take place.

    • alignment:proj という名前の 1 つの文字列プロパティを持つオブジェクトです。これにより、入力テキストが翻訳済みテキストにマッピングされます。alignment: An object with a single string property named proj, which maps input text to translated text. アライメント情報は、要求パラメーター includeAlignmenttrue である場合に提供されるだけとなります。The alignment information is only provided when the request parameter includeAlignment is true. アライメントは、次の形式の文字列値として返されます: [[SourceTextStartIndex]:[SourceTextEndIndex]–[TgtTextStartIndex]:[TgtTextEndIndex]]Alignment is returned as a string value of the following format: [[SourceTextStartIndex]:[SourceTextEndIndex]–[TgtTextStartIndex]:[TgtTextEndIndex]]. コロンによって開始および終了インデックスが区切られ、ダッシュによって言語が区切られ、スペースによって単語が区切られます。The colon separates start and end index, the dash separates the languages, and space separates the words. 1 個の単語が他の言語の 0 個、1 個、または複数個の単語にアライメントされる場合があります。さらに、アライメントされる単語が連続していない場合もあります。One word may align with zero, one, or multiple words in the other language, and the aligned words may be non-contiguous. アライメント情報が使用できない場合、アライメント要素は空になります。When no alignment information is available, the alignment element will be empty. 例と制限事項については、「アライメント情報を取得する」を参照してください。See Obtain alignment information for an example and restrictions.

    • sentLen:入力テキストと出力テキスト内で文の境界を返すオブジェクトです。sentLen: An object returning sentence boundaries in the input and output texts.

      • srcSentLen:入力テキスト内の文の長さを表す整数配列です。srcSentLen: An integer array representing the lengths of the sentences in the input text. 配列の長さは文の数であり、値は各文の長さです。The length of the array is the number of sentences, and the values are the length of each sentence.

      • transSentLen:翻訳済みテキスト内の文の長さを表す整数配列です。transSentLen: An integer array representing the lengths of the sentences in the translated text. 配列の長さは文の数であり、値は各文の長さです。The length of the array is the number of sentences, and the values are the length of each sentence.

    文の境界は、要求パラメーター includeSentenceLengthtrue の場合にのみ含められます。Sentence boundaries are only included when the request parameter includeSentenceLength is true.

  • sourceText:text という名前の 1 つの文字列プロパティを持つオブジェクトです。これにより、ソース言語の既定のスクリプトで入力テキストが提供されます。sourceText: An object with a single string property named text, which gives the input text in the default script of the source language. sourceText プロパティは、言語の通常のスクリプトではないスクリプトで入力が表されている場合にのみ存在します。sourceText property is present only when the input is expressed in a script that's not the usual script for the language. たとえば、入力がラテン文字で記述されたアラビア語であるならば、sourceText.text は同じアラビア語のテキストをアラビア文字に変換したものとなります。For example, if the input were Arabic written in Latin script, then sourceText.text would be the same Arabic text converted into Arab script.

JSON 応答の例については、「」セクションを参照してください。Example of JSON responses are provided in the examples section.

応答ヘッダーResponse headers

headersHeaders 説明Description
X-RequestIdX-RequestId 要求を識別するためにサービスによって生成される値。Value generated by the service to identify the request. トラブルシューティングの目的で使用されます。It is used for troubleshooting purposes.
X-MT-SystemX-MT-System 翻訳するように要求された 'to' 言語への翻訳を実行するために使用されたシステムの種類を示します。Specifies the system type that was used for translation for each ‘to’ language requested for translation. 値は、文字列のコンマ区切りの一覧です。The value is a comma-separated list of strings. 各文字列は種類を示します。Each string indicates a type:
  • Custom - 要求にはカスタム システムが含まれ、翻訳中に少なくとも 1 つのカスタム システムが使用されています。Custom - Request includes a custom system and at least one custom system was used during translation.
  • Team - それ以外のすべての要求。Team - All other requests

応答状態コードResponse status codes

要求によって返される可能性のある HTTP 状態コードを次に示します。The following are the possible HTTP status codes that a request returns.

状態コードStatus Code 説明Description
200200 成功。Success.
400400 クエリ パラメーターの 1 つが欠落しているか無効です。One of the query parameters is missing or not valid. 再試行する前に要求パラメーターを修正してください。Correct request parameters before retrying.
401401 要求を認証できませんでした。The request could not be authenticated. 資格情報が指定され、有効であることを確認してください。Check that credentials are specified and valid.
403403 要求が承認されていません。The request is not authorized. 詳細なエラー メッセージを確認してください。Check the details error message. これは、多くの場合、試用版サブスクリプションで提供されるすべての無料翻訳が使い果たされたことを示します。This often indicates that all free translations provided with a trial subscription have been used up.
408408 リソースが見つからないため、要求を処理できませんでした。The request could not be fulfilled because a resource is missing. 詳細なエラー メッセージを確認してください。Check the details error message. カスタムの category を使用している場合は、大抵は要求を処理するためにカスタム翻訳システムをまだ利用できないことを示しています。When using a custom category, this often indicates that the custom translation system is not yet available to serve requests. 要求は、待機期間 (例: 1 分) 後に再試行する必要があります。The request should be retried after a waiting period (e.g. 1 minute).
429429 クライアントが要求の制限を超えたため、サーバーは要求を拒否しました。The server rejected the request because the client has exceeded request limits.
500500 予期しないエラーが発生しました。An unexpected error occurred. エラーが解決しない場合は、エラー発生の日時、応答ヘッダー X-RequestId からの要求識別子、要求ヘッダー X-ClientTraceId からのクライアント識別子を添えてその旨をご報告ください。If the error persists, report it with: date and time of the failure, request identifier from response header X-RequestId, and client identifier from request header X-ClientTraceId.
503503 サーバーが一時的に使用できません。Server temporarily unavailable. 要求をやり直してください。Retry the request. エラーが解決しない場合は、エラー発生の日時、応答ヘッダー X-RequestId からの要求識別子、要求ヘッダー X-ClientTraceId からのクライアント識別子を添えてその旨をご報告ください。If the error persists, report it with: date and time of the failure, request identifier from response header X-RequestId, and client identifier from request header X-ClientTraceId.

エラーが発生した場合は、要求の結果として JSON エラー応答も返されます。If an error occurs, the request will also return a JSON error response. このエラーコードは 3 桁の HTTP ステータス コードの後に、エラーをさらに分類するための 3 桁の数字を続けた 6 桁の数字です。The error code is a 6-digit number combining the 3-digit HTTP status code followed by a 3-digit number to further categorize the error. 一般的なエラー コードは、v3 Translator Text API のリファレンス ページで確認できます。Common error codes can be found on the v3 Translator Text API reference page.

Examples

単一の入力を翻訳するTranslate a single input

この例では、1 つの文を英語から簡体中国語に翻訳する方法を示します。This example shows how to translate a single sentence from English to Simplified Chinese.

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

応答本文を次に示します。The response body is:

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

translations 配列には 1 つの要素が含まれており、これによって入力内の単一のテキストの翻訳が提供されます。The translations array includes one element, which provides the translation of the single piece of text in the input.

言語自動検出を使用して単一の入力を翻訳するTranslate a single input with language auto-detection

この例では、1 つの文を英語から簡体中国語に翻訳する方法を示します。This example shows how to translate a single sentence from English to Simplified Chinese. 要求では入力言語が指定されていません。The request does not specify the input language. 代わりに、ソース言語の自動検出が使用されます。Auto-detection of the source language is used instead.

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

応答本文を次に示します。The response body is:

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

応答は、前の例での応答に似ています。The response is similar to the response from the previous example. 言語自動検出が要求されたので、入力テキストで検出された言語に関する情報も含まれています。Since language auto-detection was requested, the response also includes information about the language detected for the input text.

音訳を使用して翻訳するTranslate with transliteration

音訳を追加して、前の例を拡張してみましょう。Let's extend the previous example by adding transliteration. 次の要求では、ラテン文字で記述する、中国語の翻訳が求められています。The following request asks for a Chinese translation written in Latin script.

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

応答本文を次に示します。The response body is:

[
    {
        "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 プロパティが含まれるようになります。これにより、ラテン文字を使用して翻訳されたテキストが提供されます。The translation result now includes a transliteration property, which gives the translated text using Latin characters.

複数のテキストを変換するTranslate multiple pieces of text

一度に複数の文字列を翻訳するには、要求本文に文字列の配列を指定するだけです。Translating multiple strings at once is simply a matter of specifying an array of strings in the request body.

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

応答本文を次に示します。The response body is:

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

複数の言語に変換するTranslate to multiple languages

この例では、1 つの要求で同じ入力を複数の言語に翻訳する方法を示します。This example shows how to translate the same input to several languages in one request.

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

応答本文を次に示します。The response body is:

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

不適切な表現を処理するHandle profanity

通常、Translator サービスでは、ソースに存在する不適切な表現は翻訳でも保たれます。Normally the Translator service will retain profanity that is present in the source in the translation. 不適切な表現の程度や、言葉に不敬な意味を込めるコンテキストは文化によって異なります。結果として、ターゲット言語での不適切な表現の程度は強められることもあれば、弱められることもあります。The degree of profanity and the context that makes words profane differ between cultures, and as a result the degree of profanity in the target language may be amplified or reduced.

ソース テキスト内での不適切な表現の有無に関係なく、翻訳で不適切な表現が生じるのを防ぐには、不適切な表現のフィルター処理オプションを使用できます。If you want to avoid getting profanity in the translation, regardless of the presence of profanity in the source text, you can use the profanity filtering option. このオプションを使用すると、不適切な表現を削除するかどうか、適切なタグで不適切な表現をマークするかどうか (独自の後処理を追加するためのオプションが用意されています)、または何も操作を行わないかどうかを選択することができます。The option allows you to choose whether you want to see profanity deleted, whether you want to mark profanities with appropriate tags (giving you the option to add your own post-processing), or you want no action taken. ProfanityAction に指定できる値は、DeletedMarked、および NoAction (既定値) です。The accepted values of ProfanityAction are Deleted, Marked and NoAction (default).

ProfanityActionProfanityAction ActionAction
NoAction これは既定の動作です。This is the default behavior. 不適切な表現はソースからターゲットに渡されます。Profanity will pass from source to target.

ソースの例 (日本語): 彼はジャッカスです。 Example Source (Japanese): 彼はジャッカスです。
翻訳の例 (英語): He is a jackass. Example Translation (English): He is a jackass.
Deleted 不適切な単語は、置換されずに出力から削除されます。Profane words will be removed from the output without replacement.

ソースの例 (日本語): 彼はジャッカスです。 Example Source (Japanese): 彼はジャッカスです。
翻訳の例 (英語): He is a. Example Translation (English): He is a.
Marked 不適切な単語は、出力ではマーカーに置き換えられます。Profane words are replaced by a marker in the output. マーカーは ProfanityMarker パラメーターによって異なります。The marker depends on the ProfanityMarker parameter.

ProfanityMarker=Asterisk の場合、不適切な単語は \*\*\* に置き換えられます。For ProfanityMarker=Asterisk, profane words are replaced with \*\*\*:
ソースの例 (日本語): 彼はジャッカスです。 Example Source (Japanese): 彼はジャッカスです。
翻訳の例 (英語): He is a \*\*\*. Example Translation (English): He is a \*\*\*.

ProfanityMarker=Tag の場合、不適切な単語は XML タグ <profanity> および </profanity> によって囲まれます。For ProfanityMarker=Tag, profane words are surrounded by XML tags <profanity> and </profanity>:
ソースの例 (日本語): 彼はジャッカスです。 Example Source (Japanese): 彼はジャッカスです。
翻訳の例 (英語): He is a <profanity>jackass</profanity>. Example Translation (English): He is a <profanity>jackass</profanity>.

例:For example:

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 a freaking good idea.'}]"

次が返されます。This returns:

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

次の場合と比較します。Compare with:

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 a freaking good idea.'}]"

その最後の要求では次が返されます。That last request returns:

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

マークアップを含むコンテンツの翻訳および翻訳対象の決定Translate content with markup and decide what's translated

HTML ページからのコンテンツや XML ドキュメントからのコンテンツなど、マークアップを含むコンテンツを翻訳するのが一般的です。It's common to translate content which includes markup such as content from an HTML page or content from an XML document. タグ付きのコンテンツを翻訳する場合は、クエリ パラメーター textType=html を含めます。Include query parameter textType=html when translating content with tags. さらに、特定のコンテンツを翻訳から除外すると便利な場合があります。In addition, it's sometimes useful to exclude specific content from translation. 属性 class=notranslate を使用すると、元の言語のまま残す必要があるコンテンツを指定できます。You can use the attribute class=notranslate to specify content that should remain in its original language. 次の例では、1 番目の div 要素内のコンテンツは翻訳されませんが、2 番目の div 要素内のコンテンツは変換されます。In the following example, the content inside the first div element will not be translated, while the content in the second div element will be translated.

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

要求の例を次に示します。Here is a sample request to illustrate.

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

応答は次のとおりです。The response is:

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

アラインメント情報を取得するObtain alignment information

アライメント情報を受信するには、クエリ文字列上で includeAlignment=true を指定します。To receive alignment information, specify includeAlignment=true on the query string.

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

応答は次のとおりです。The response is:

[
    {
        "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 で始まっています。これは、ソース テキスト内の最初の 3 文字 (The) が翻訳済みテキスト内の最初の 2 文字 (La) にマッピングされていることを意味します。The alignment information starts with 0:2-0:1, which means that the first three characters in the source text (The) map to the first two characters in the translated text (La).

制限事項Limitations

次の制限事項に注意してください。Note the following restrictions:

  • HTML 形式のテキスト、つまり textType=html の場合、配置は使用できません。Alignment is not available for text in HTML format i.e., textType=html
  • アライメントは言語ペアのサブセットに対してのみ返されます。Alignment is only returned for a subset of the language pairs:
    • 英語から他の任意の言語へfrom English to any other language;
    • 他の任意の言語から英語へ。ただし、繁体字中国語、繁体字中国語、およびラトビア語から英語については除くfrom any other language to English except for Chinese Simplified, Chinese Traditional, and Latvian to English;
    • 日本語から韓国語へ、または韓国語から日本語へfrom Japanese to Korean or from Korean to Japanese.
  • 文があらかじめ用意された翻訳である場合、アラインメントは返されません。You will not receive alignment if the sentence is a canned translation. あらかじめ用意された翻訳には、"This is a test" や "I love you" など高い頻度で出現する文があります。Example of a canned translation is "This is a test", "I love you" and other high frequency sentences.

文の境界を取得するObtain sentence boundaries

ソース テキストと翻訳済みテキストの文の長さに関する情報を受信するには、クエリ文字列上で includeSentenceLength=true を指定します。To receive information about sentence length in the source text and translated text, specify includeSentenceLength=true on the query string.

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

応答は次のとおりです。The response is:

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

動的ディクショナリを使用して翻訳するTranslate with dynamic dictionary

単語や語句に適用する翻訳があらかじめわかっている場合は、それを要求内でマークアップとして指定することができます。If you already know the translation you want to apply to a word or a phrase, you can supply it as markup within the request. 動的ディクショナリは、固有名詞や製品名のような複合名詞に対してのみ安全に使用できます。The dynamic dictionary is only safe for compound nouns like proper names and product names.

指定するマークアップでは、次の構文を使用します。The markup to supply uses the following syntax.

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

たとえば、"The word wordomatic is a dictionary entry." という英文を考えてみます。For example, consider the English sentence "The word wordomatic is a dictionary entry." 単語 wordomatic を翻訳内でそのまま使用するには、次の要求を送信します。To preserve the word wordomatic in the translation, send the request:

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\">word or phrase</mstrans:dictionary> is a dictionary entry.'}]"

結果は次のとおりです。The result is:

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

この機能は、textType=text または textType=html の場合も同じように動作します。This feature works the same way with textType=text or with textType=html. この機能は慎重に使用する必要があります。The feature should be used sparingly. 翻訳をカスタマイズするには、Custom Translator を使用するのが適切で望ましい方法です。The appropriate and far better way of customizing translation is by using Custom Translator. Custom Translator では、コンテキストおよび統計的確率を最大限に活用します。Custom Translator makes full use of context and statistical probabilities. コンテキスト内の単語または語句を表示するトレーニング データを作成する余裕がある場合、非常に良い結果が得られます。If you have or can afford to create training data that shows your work or phrase in context, you get much better results. Custom Translator の詳細については、こちらを参照してくださいLearn more about Custom Translator.