通过

你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

容器：翻译文本

  • 项目

翻译文本。

请求 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。		 必需参数

可选参数

查询参数 说明
textType 可选参数。
定义要翻译的文本是纯文本还是 HTML 文本。 HTML 必须是格式正确的完整元素。 可能的值为 plain（默认）html。
includeSentenceLength 可选参数。
指定是否包括输入文本和翻译文本的句子边界。 可能的值为 true 或 false（默认）。

请求标头

头文件 说明 条件
身份验证标头 请参阅可用的身份验证选项。 所需的请求标头
Content-Type 指定有效负载的内容类型。
接受的值为：application/json; charset=UTF-8。		 所需的请求标头
Content-Length 请求正文的长度。 可选
X-ClientTraceId 客户端生成的 GUID，用于唯一标识请求。 如果在查询字符串中使用名为 ClientTraceId 的查询参数包括了跟踪 ID，则可以省略此标头。 可选

请求正文

请求的正文是一个 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 翻译器参考页上找到。

代码示例：翻译文本

注意

  • 每个示例都运行在 localhost 使用 docker run 命令指定的实例上。
  • 在容器运行时， 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>

例如，假设英语句子为“The word wordomatic is a dictionary entry”。若要在翻译中保留单词 wordomatic，请发送如下请求：

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，此功能都以相同的方式工作。 应尽量少使用此功能。 对翻译进行自定义时，一个合适且要好得多的方法是使用自定义翻译工具。 自定义翻译工具能够充分利用上下文和统计概率。 如果创建了在上下文中显示工作或短语的训练数据，则获得更好的结果。 详细了解自定义翻译工具。

请求限制

每个翻译请求在你要翻译到的所有目标语言中都限制为 50,000 个字符。 例如，如果发送 3,000 个字符的翻译请求以翻译成三种不同的语言，则请求大小为 3000x3 = 9,000 个字符，这满足请求限制。 按字符收费，而不是按请求数收费。 建议发送较短的请求。

下表列出了翻译器的“翻译”操作的数组元素和字符限制。

Operation 数组元素的最大大小 最大数组元素数 最大请求大小（字符数）
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 帐户上的 Azure AI 翻译资源将计费信息发送到 Azure。

操作 请求查询 Document type 支持容器
• 文本翻译
• 文档翻译		 已指定 from。 Office 文档 无
• 文本翻译
• 文档翻译		 未指定 from。 需要自动语言检测来确定源语言。 Office 文档 ✔️ 文本分析：语言容器
• 文本翻译
• 文档翻译		 已指定 from。 扫描的 PDF 文档 ✔️ 版本：读取容器
• 文本翻译
• 文档翻译		 未指定 from，需要自动语言检测来确定源语言。 扫描的 PDF 文档 ✔️ 文本分析：语言容器

✔️ 版本：读取容器
容器映像和标记

Azure AI 服务容器映像位于 Microsoft 工件注册表目录中。 下表列出了文本和文档翻译的完全限定图像位置：

容器 映像位置 备注
翻译：文本翻译 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_KEY} 和 {TRANSLATOR_ENDPOINT_URI} 替换为 Azure 门户翻译实例中的键和终结点值。 请确保使用 .document translation endpoint

  4. 顶层名称（azure-ai-translator、azure-ai-language、azure-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 参考。

后续步骤

详细了解文本翻译