容器：翻譯文字

  • 發行項

翻譯文字。

要求 URL

將 POST 要求傳送至：

POST http://localhost:{port}/translate?api-version=3.0&&from={from}&to={to}

範例要求

curl -x POST "https:localhost:5000/translate?api-version=3.0&from=en&to=es" -H "Content-Type: application/json" -d "[{
'Text': 'I would really like to drive your car.'}]"

範例回應

[
  {
    "translations": [
      {
        "text": "Realmente me gustaría conducir su coche.",
        "to": "es"
      }
    ]
  }
]

要求參數

在查詢字串上傳遞的要求參數如下：

必要參數

查詢參數 描述 條件
api-version 用戶端要求的 API 版本。 值必須是 3.0。 必要參數
from 指定輸入文字的語言。 必要參數
打給 指定輸出文字的語言。 例如，使用 to=de 來翻譯為德文。
藉由在查詢字串中重複 參數，即可同時轉譯成多種語言。 例如，使用 to=de&to=it 來翻譯為德文和義大利文。		 必要參數

選擇性參數

查詢參數 描述
textType 選擇性參數。
定義翻譯的文字是純文本還是 HTML 文字。 任何 HTML 都必須是格式正確的完整專案。 可能的值為：plain (預設) 或 html。
includeSentenceLength 選擇性參數。
指定是否要包含輸入文字和翻譯文字的句子界限。 可能的值為： true 或 false （預設值）。

要求標頭

標頭 描述 條件
驗證標頭 請參閱可用的驗證選項。 必要要求標頭
內容-類型 指定承載的內容類型。
接受的值為 application/json; charset=UTF-8。		 必要要求標頭
Content-Length 要求本文的長度。 選擇性
X-ClientTraceId 用於識別唯一要求的 GUID，由用戶端產生。 如果您使用名為 ClientTraceId的查詢參數，在查詢字串中包含追蹤標識碼，則可以省略此標頭。 選擇性

要求本文

要求的主體是 JSON 陣列。 每個陣列元素都是 JSON 物件，其具有名為 Text的字串屬性，代表要翻譯的字串。

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

適用下列限制：

  • 陣列最多可以有100個專案。
  • 要求中包含的整個文字不能超過10,000個字元，包括空格。

回應本文

成功的回應是 JSON 陣列，輸入數位中的每個字串都有一個結果。 結果物件包含下列屬性：

  • translations：翻譯結果的陣列。 陣列的大小符合透過 to 查詢參數指定的目標語言數目。 陣列中的每個元素都包含：

  • to：字串，表示目標語言的語言代碼。

  • text：提供翻譯文字的字串。

  • sentLen：在輸入和輸出文字中傳回句子界限的物件。

  • srcSentLen：整數陣列，表示輸入文字中句子的長度。 陣列的長度是句子數目，而值則是每個句子的長度。

  • transSentLen：整數陣列，表示翻譯文字中句子的長度。 陣列的長度是句子數目，而值則是每個句子的長度。

    只有在要求參數 includeSentenceLength 為 true時，才會包含句子界限。

    • sourceText：具有名為 text的單一字串屬性 的物件，其會提供來源語言默認腳本中的輸入文字。 sourceText 只有在輸入以不是語言一般腳本的腳本表示時，屬性才會存在。 例如，如果輸入是以拉丁腳本撰寫的阿拉伯文，則會 sourceText.text 是轉換成阿拉伯腳本的相同阿拉伯文文字。

回應標頭

標頭 描述
X-RequestId 服務所產生的值，用來識別要求，並用於疑難解答目的。
X-MT-System 指定用於翻譯每個要求翻譯之「到」語言的系統類型。 值是以逗號分隔的字串清單。 每個字串都指出類型：

▪自定義 - 要求包含自定義系統，而且翻譯期間至少使用了一個自定義系統。
▪ 小組 - 所有其他要求

回應狀態代碼

如果發生錯誤，要求會傳回 JSON 錯誤回應。 錯誤碼是6位數的數字，結合3位數 HTTP狀態代碼，後面接著3位數的數位，以進一步分類錯誤。 v3 翻譯工具參考頁面上可找到常見的錯誤碼。

程式代碼範例：翻譯文字

注意

  • 每個範例都會在您使用 命令指定的 docker run 上localhost執行。
  • 當您的容器正在執行時， localhost 會指向容器本身。
  • 您不需要使用 localhost:5000。 您可以使用任何尚未在主機環境中使用的埠。

轉譯單一輸入

此範例示範如何將單一句子從英文翻譯成簡體中文。

curl -X POST "http://localhost:{port}/translate?api-version=3.0&from=en&to=zh-Hans" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'Hello, what is your name?'}]"

回應本文為：

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

數位包含 translations 一個元素，提供輸入中單一文字片段的翻譯。

查詢 Azure AI 翻譯工具 端點 （文字）

以下是使用命令所指定 docker run localhost：5000的 cURL HTTP 要求範例：

  curl -X POST "http://localhost:5000/translate?api-version=3.0&from=en&to=zh-HANS"
    -H "Content-Type: application/json" -d "[{'Text':'Hello, what is your name?'}]"

注意

如果您在容器就緒之前嘗試 cURL POST 要求，您將會收到服務暫時無法使用的回應。 請等候容器就緒，然後再試一次。

使用 Swagger API 翻譯文字

英文 ↔ 德文

  1. 瀏覽至 Swagger 頁面： http://localhost:5000/swagger/index.html
  2. 選取 POST /翻譯
  3. 選取 [試試看]
  4. 輸入 From 參數做為 en
  5. 輸入 To 參數做為 de
  6. 輸入 api-version 參數做為 3.0
  7. 在 [文字] 下，將 string 取代為下列 JSON
  [
        {
            "text": "hello, how are you"
        }
  ]

選取 [執行]，所產生的翻譯會輸出在 [回應主體] 中。 您應該會看到下列回應：

"translations": [
      {
          "text": "hallo, wie geht es dir",
          "to": "de"
      }
    ]

使用 Python 翻譯文字

英文↔法文

import requests, json

url = 'http://localhost:5000/translate?api-version=3.0&from=en&to=fr'
headers = { 'Content-Type': 'application/json' }
body = [{ 'text': 'Hello, how are you' }]

request = requests.post(url, headers=headers, json=body)
response = request.json()

print(json.dumps(
    response,
    sort_keys=True,
     indent=4,
     ensure_ascii=False,
     separators=(',', ': ')))

使用 C#/.NET 主控台應用程式翻譯文字

英文↔西班牙文

啟動 Visual Studio，並建立新的主控台應用程式。 編輯 *.csproj 檔案以新增 <LangVersion>7.1</LangVersion> 節點 — 指定 C# 7.1。 新增 Newtoonsoft.Json NuGet 套件 11.0.2 版。

在 Program.cs 中，將所有現有的程式碼取代為下列指令碼：

using Newtonsoft.Json;
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

namespace TranslateContainer
{
    class Program
    {
        const string ApiHostEndpoint = "http://localhost:5000";
        const string TranslateApi = "/translate?api-version=3.0&from=en&to=es";

        static async Task Main(string[] args)
        {
            var textToTranslate = "Sunny day in Seattle";
            var result = await TranslateTextAsync(textToTranslate);

            Console.WriteLine(result);
            Console.ReadLine();
        }

        static async Task<string> TranslateTextAsync(string textToTranslate)
        {
            var body = new object[] { new { Text = textToTranslate } };
            var requestBody = JsonConvert.SerializeObject(body);

            var client = new HttpClient();
            using (var request =
                new HttpRequestMessage
                {
                    Method = HttpMethod.Post,
                    RequestUri = new Uri($"{ApiHostEndpoint}{TranslateApi}"),
                    Content = new StringContent(requestBody, Encoding.UTF8, "application/json")
                })
            {
                // Send the request and await a response.
                var response = await client.SendAsync(request);

                return await response.Content.ReadAsStringAsync();
            }
        }
    }
}

翻譯多個字串

一次翻譯多個字串只是在要求本文中指定字串數位的問題。

curl -X POST "http://localhost:5000/translate?api-version=3.0&from=en&to=zh-Hans" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'Hello, what is your name?'}, {'Text':'I am fine, thank you.'}]"

回應包含所有文字片段的翻譯，順序與要求完全相同。 回應本文為：

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

翻譯成多種語言

此範例示範如何在一個要求中將相同的輸入轉譯成數種語言。

curl -X POST "http://localhost:5000/translate?api-version=3.0&from=en&to=zh-Hans&to=de" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'Hello, what is your name?'}]"

回應本文為：

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

使用標記翻譯內容並指定翻譯的內容

通常轉譯包含標記的內容，例如 HTML 頁面的內容或 XML 檔的內容。 使用標籤翻譯內容時包含查詢參數 textType=html 。 此外，從翻譯中排除特定內容有時很有用。 您可以使用 屬性 class=notranslate 來指定應該維持在其原始語言中的內容。 在下列範例中，不會翻譯第一個項目 div 內的內容，而第二 div 個元素中的內容則會轉譯。

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

以下是要說明的範例要求。

curl -X POST "http://localhost:5000/translate?api-version=3.0&from=en&to=zh-Hans&textType=html" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'<div class=\"notranslate\">This will not be translated.</div><div>This will be translated.</div>'}]"

回應是:

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

使用動態字典轉譯

如果已經知道想要套用至單字或片語的翻譯，則可以在要求內以標記來提供。 動態字典僅適用於適當的名詞，例如個人名稱和產品名稱。

要提供的標記會使用下列語法。

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

例如，請考慮英文句子「文字文字是字典專案」。若要在翻譯中保留文字 文字， 請傳送要求：

curl -X POST "http://localhost:5000/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.'}]"

結果如下：

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

此功能的運作 textType=text 方式與 或相同 textType=html。 此功能應該謹慎使用。 自定義翻譯的適當且更好的方式是使用自定義 翻譯工具。 Custom Translator 會完全利用內容和統計機率。 如果您已建立定型數據，以在內容中顯示您的工作或片語，您會取得更好的結果。 深入瞭解自定義 翻譯工具。

需求限制

每個翻譯要求限制為 10,000 個字元，且所有您要翻譯的目標語言。 例如，傳送 3,000 個字元的翻譯要求以轉譯成三種不同的語言，會導致要求大小為 3000x3 = 9,000 個字元，以符合要求限制。 您需支付每個字元的費用，而不是要求數目。 我們建議傳送較短的要求。

下表列出 翻譯工具 轉譯作業的陣列元素和字元限制。

作業 陣列元素的大小上限 陣列元素的數目上限 要求大小上限（字元）
translate 10,000 100 10,000

使用 docker compose：搭配支援容器 翻譯工具

Docker compose 是一種工具，可讓您使用通常名為 compose.yaml的單一 YAML 檔案來設定多容器應用程式。 docker compose up使用 命令來啟動容器應用程式，以及docker compose down停止和移除容器的命令。

如果您已安裝 Docker Desktop CLI，它包含 Docker compose 及其必要條件。 如果您沒有 Docker Desktop，請參閱 安裝 Docker Compose 概觀。

下表列出文字和文件翻譯作業所需的支援容器。 翻譯工具 容器會透過 Azure 帳戶上的 Azure AI 翻譯工具 資源，將帳單資訊傳送至 Azure。

作業 要求查詢 Document type 支援容器
•文本翻譯
• 檔案翻譯		 from 指定。 Office 檔 無
•文本翻譯
• 檔案翻譯		 from 未指定。 需要自動語言偵測，才能判斷來源語言。 Office 檔 文字分析：語言容器 ✔️
•文本翻譯
• 檔案翻譯		 from 指定。 掃描的 PDF 檔 Vision：read 容器 ✔️
•文本翻譯
• 檔案翻譯		 from 未指定需要自動語言偵測來判斷來源語言。 掃描的 PDF 檔 文字分析：語言容器 ✔️

Vision：read 容器 ✔️
容器映像和標籤

您可以在 Microsoft 成品登錄 目錄中找到 Azure AI 服務容器映像。 下表列出文字和文件翻譯的完整影像位置：

容器 映像位置 備註
翻譯工具：文字翻譯 mcr.microsoft.com/azure-cognitive-services/translator/text-translation:latest 您可以在 MCR 上檢視 Azure AI 服務文字翻譯版本標籤的完整清單。
翻譯工具：文件翻譯 Todo Todo
文字分析：語言 mcr.microsoft.com/azure-cognitive-services/textanalytics/language:latest 您可以在 MCR 上檢視 Azure AI 服務的完整清單 文字分析 語言版本標籤。
視覺：讀取 mcr.microsoft.com/azure-cognitive-services/vision/read:latest 您可以在 MCR 上檢視 Azure AI 服務的完整清單 電腦視覺 讀取OCR版本標籤。

建立您的應用程式

  1. 使用您慣用的編輯器或 IDE，為您的應用程式建立名為 container-environment 的新目錄或您選擇的名稱。

  2. 建立名為 compose.yaml的新 YAML 檔案。 .yml或 .yaml 擴展名都可用於 compose 檔案。

  3. 將下列 YAML 程式代碼範例複製並貼到您的 compose.yaml 檔案中。 將和 {TRANSLATOR_ENDPOINT_URI} 取代{TRANSLATOR_KEY}為您 Azure 入口網站 翻譯工具 實例中的金鑰和端點值。 請確定您使用 document translation endpoint。

  4. 最上層名稱 （azure-ai-translator、 azure-ai-languageazure-ai-read、 ） 是您指定的參數。

  5. container_name是選擇性參數，可在容器執行時設定名稱，而不是讓docker compose產生名稱。

    services:
  azure-ai-translator:
    container_name: azure-ai-translator
    image: mcr.microsoft.com/product/azure-cognitive-services/translator/text-translation:latest
    environment:
        - EULA=accept
        - billing={TRANSLATOR_ENDPOINT_URI}
        - apiKey={TRANSLATOR_KEY}
        - AzureAiLanguageHost=http://azure-ai-language:5000
        - AzureAiReadHost=http://azure-ai-read:5000
    ports:
          - "5000:5000"
    azure-ai-language:
      container_name: azure-ai-language
      image:  mcr.microsoft.com/azure-cognitive-services/textanalytics/language:latest
      environment:
          - EULA=accept
          - billing={TRANSLATOR_ENDPOINT_URI}
          - apiKey={TRANSLATOR_KEY}
    azure-ai-read:
      container_name: azure-ai-read
      image:  mcr.microsoft.com/azure-cognitive-services/vision/read:latest
      environment:
          - EULA=accept
          - billing={TRANSLATOR_ENDPOINT_URI}
          - apiKey={TRANSLATOR_KEY}

  6. 開啟終端機瀏覽至 container-environment 資料夾，並使用下列 docker-compose 命令啟動容器：

    docker compose up

  7. 若要停止容器，請使用下列命令：

    docker compose down

    提示

    docker compose 命令：

    • docker compose pause 暫停執行中的容器。
    • docker compose unpause {your-container-name} 取消暫停的容器。
    • docker compose restart 會重新啟動所有已停止且執行中的容器，且所有先前的變更都保持不變。 如果您對組 compose.yaml 態進行變更，則不會使用 docker compose restart 命令來更新這些變更。 您必須使用 docker compose up 命令來反映檔案中的 compose.yaml 更新和變更。
    • docker compose ps -a 列出所有容器，包括已停止的容器。
    • docker compose exec 可讓您執行命令，以 中斷連結 或 設定執行中容器中的環境變數 。

    如需詳細資訊， 請參閱docker CLI 參考。

後續步驟

深入瞭解文字翻譯