容器：翻譯文字

發行項
09/01/2024

翻譯文字。

要求 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`。	必要參數
寄件者	指定輸入文字的語言。	必要參數
打給	指定輸出文字的語言。例如，使用 `to=de` 來翻譯為德文。藉由在查詢字串中重複參數，即可同時轉譯成多種語言。例如，使用 `to=de&to=it` 來翻譯為德文和義大利文。	必要參數

您可以查詢服務以取得 translation 範圍支援的語言。
另請參閱語言支援音譯。

選擇性參數

查詢參數	描述
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個專案。
要求中包含的完整文字不能超過 50,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 翻譯文字

英文 ↔ 德文

瀏覽至 Swagger 頁面： http://localhost:5000/swagger/index.html
選取 POST /翻譯
選取 [試試看]
輸入 From 參數做為 en
輸入 To 參數做為 de
輸入 api-version 參數做為 3.0
在 [文字] 下，將 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 會完全利用內容和統計機率。如果您已建立定型數據，以在內容中顯示您的工作或片語，您會取得更好的結果。深入瞭解自定義翻譯工具。

需求限制

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

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

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

使用 docker compose：具有支援容器的翻譯工具

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

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

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

作業	要求查詢	Document type	支援容器
• 文字翻譯 • 文件翻譯	`from` 已指定。	Office 文件	無
• 文字翻譯 • 文件翻譯	`from` 未指定。需要自動語言偵測，才能判斷來源語言。	Office 文件	✔️ 文字分析：語言容器
• 文字翻譯 • 文件翻譯	`from` 已指定。	掃描的 PDF 文件	✔️ 視覺：讀取容器
• 文字翻譯 • 文件翻譯	`from` 為指定，需要自動語言偵測，才能判斷來源語言。	掃描的 PDF 文件	✔️ 文字分析：語言容器 ✔️ 視覺：讀取容器

容器映像和標記

您可以在 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`版本標記的完整清單。

建立您的應用程式

使用您慣用的編輯器或 IDE，為名為 container-environment 的應用程式建立或所選名稱新目錄。
建立名為 compose.yaml 的新 YAML 檔案。 .yml 或 .yaml 延伸檔案都可用於 compose 檔案。
將下列 YAML 程式碼範例複製並貼到 compose.yaml 檔案中。請使用 Azure 入口網站翻譯工具執行個體中的金鑰和端點取代 {TRANSLATOR_KEY} 和 {TRANSLATOR_ENDPOINT_URI}。請確定您使用 document translation endpoint。
最上層名稱 (azure-ai-translator、azure-ai-language、azure-ai-read) 是您指定的參數。

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}

開啟終端機瀏覽至 container-environment 資料夾，並使用下列 docker-compose 命令啟動容器：
```
docker compose up
```
若要停止容器，請使用下列命令：
```
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 可讓您執行命令 lto 中斷連結，或在執行中的容器中設定環境變數。
如需詳細資訊，請參閱 docker CLI 參考。

後續步驟

深入瞭解文字翻譯

共用方式為

容器：翻譯文字

要求 URL

要求參數

必要參數

選擇性參數

要求標頭

要求本文

回應本文

回應標頭

回應狀態代碼

程式代碼範例：翻譯文字

轉譯單一輸入

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

使用 Swagger API 翻譯文字

英文 ↔ 德文

使用 Python 翻譯文字

英文↔法文

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

英文↔西班牙文

翻譯多個字串

翻譯成多種語言

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

使用動態字典轉譯

需求限制

使用 docker compose：具有支援容器的翻譯工具

容器映像和標記

建立您的應用程式

後續步驟

意見反應

其他資源

共用方式為

容器：翻譯文字

要求 URL

要求參數

必要參數

選擇性參數

要求標頭

要求本文

回應本文

回應標頭

回應狀態代碼

程式代碼範例：翻譯文字

轉譯單一輸入

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

使用 Swagger API 翻譯文字

英文 ↔ 德文

使用 Python 翻譯文字

英文↔法文

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

英文↔西班牙文

翻譯多個字串

翻譯成多種語言

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

使用動態字典轉譯

需求限制

使用 docker compose：具有支援容器的翻譯工具

容器映像和標記

建立您的應用程式

後續步驟

意見反應

其他資源

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