Bagikan melalui

Kontainer: Terjemahkan Teks

  • Artikel

Terjemahkan teks.

URL Permintaan

Kirim permintaan POST ke:

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

Contoh permintaan

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

Contoh respons

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

Parameter permintaan

Parameter permintaan yang diteruskan pada untai kueri adalah:

Parameter yang diperlukan

Parameter kueri Deskripsi Kondisi
versi-api Versi API yang diminta oleh klien. Nilai harus 3.0. Parameter yang diperlukan
dari Menentukan bahasa teks input. Parameter yang diperlukan
ke Menentukan bahasa teks output. Misalnya, gunakan to=de untuk menerjemahkan ke bahasa Jerman.
Penerjemahan ke beberapa bahasa sekaligus dapat dilakukan dengan mengulangi parameter dalam string kueri. Misalnya, gunakan to=de&to=it untuk menerjemahkan ke bahasa Jerman dan Italia.		 Parameter yang diperlukan

Parameter opsional

Parameter kueri Deskripsi
textType Parameter opsional.
Menentukan apakah teks yang diterjemahkan adalah teks biasa atau teks HTML. HTML apa pun harus menjadi elemen yang lengkap dan diformat dengan baik. Kemungkinan nilainya adalah: plain (default) atau html.
includeSentenceLength Parameter opsional.
Menentukan apakah akan menyertakan batas kalimat untuk teks input dan teks terjemahan. Nilai yang mungkin muncul adalah: true atau false (default).

Header permintaan

Header Deskripsi Kondisi
Header autentikasi Lihatopsi yang tersedia untuk autentikasi. Header permintaan yang diperlukan
Content-Type Tentukan jenis konten payload.
Nilai yang diterima adalah application/json; charset=UTF-8.		 Header permintaan yang diperlukan
Panjang-Konten Panjang isi permintaan. Opsional
X-ClientTraceId GUID yang dihasilkan klien untuk mengidentifikasi permintaan secara unik. Anda bisa menghilangkan header ini jika Anda menyertakan ID jejak dalam string kueri menggunakan parameter kueri bernama ClientTraceId. Opsional

Isi permintaan

Isi permintaan berupa array JSON. Setiap elemen larik adalah objek JSON dengan properti string bernama Text, yang mewakili string yang akan diterjemahkan.

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

Batasan berikut berlaku:

  • Larik dapat memiliki paling banyak 100 elemen.
  • Seluruh teks yang disertakan dalam permintaan tidak boleh melebihi 10.000 karakter termasuk spasi.

Isi respons

Respons yang berhasil adalah array JSON dengan satu hasil untuk setiap string dalam array input. Objek hasil mencakup properti berikut:

  • translations: Larik hasil terjemahan. Ukuran larik cocok dengan jumlah bahasa target yang ditentukan melalui parameter kueri to. Setiap elemen dalam larik meliputi:

  • to: String yang mewakili kode bahasa dari bahasa target.

  • text: String yang memberikan teks terjemahan.

  • sentLen: Objek yang menampilkan batas kalimat dalam teks input dan output.

  • srcSentLen: Larik bilangan bulat yang mewakili panjang kalimat dalam teks masukan. Panjang larik adalah jumlah kalimat, dan nilainya adalah panjang setiap kalimat.

  • transSentLen: Larik bilangan bulat yang merepresentasikan panjang kalimat dalam teks yang diterjemahkan. Panjang larik adalah jumlah kalimat, dan nilainya adalah panjang setiap kalimat.

    Batas kalimat hanya disertakan jika parameter permintaan includeSentenceLength adalah true.

    • sourceText: Objek dengan properti string tunggal bernama text, yang memberikan teks input dalam skrip default bahasa sumber. sourceText properti hanya ada ketika input dinyatakan dalam skrip yang bukan skrip biasa untuk bahasa tersebut. Misalnya, jika inputnya adalah bahasa Arab yang ditulis dalam skrip Latin, sourceText.text akan menjadi teks Arab yang sama yang diubah menjadi skrip Arab.

Header respons

Header Deskripsi
X-RequestId Nilai yang dihasilkan oleh layanan untuk mengidentifikasi permintaan dan digunakan untuk tujuan pemecahan masalah.
X-MT-System Menentukan jenis sistem yang digunakan untuk terjemahan pada setiap bahasa ‘ke’ bahasa yang diminta untuk diterjemahkan. Nilainya adalah daftar string yang dipisahkan koma. Setiap string menunjukkan jenis:

▪ Kustom - Permintaan menyertakan sistem kustom dan minimal satu sistem kustom digunakan selama penerjemahan.
▪ Tim - Semua permintaan lainnya

Kode status respons

Jika terjadi kesalahan, permintaan mengembalikan respons kesalahan JSON. Kode kegagalan adalah 6 digit angka yang menggabungkan kode status HTTP 3 digit diikuti dengan 3 digit angka untuk mengategorikan kesalahan lebih lanjut. Kode galat umum dapat ditemukan di halaman referensi Penerjemah v3.

Sampel kode: menerjemahkan teks

Catatan

  • Setiap sampel berjalan pada localhost yang Anda tentukan dengan docker run perintah .
  • Saat kontainer Anda berjalan, localhost arahkan ke kontainer itu sendiri.
  • Anda tidak perlu menggunakan localhost:5000. Anda dapat menggunakan port apa pun yang belum digunakan di lingkungan host Anda.

Menerjemahkan satu input

Contoh ini menunjukkan bagaimana menerjemahkan satu kalimat dari Bahasa Inggris ke Mandarin Sederhana.

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

Isi respons adalah:

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

Larik translations mencakup satu elemen, yang memberikan terjemahan dari satu bagian teks dalam input.

Mengkueri titik akhir azure AI Penerjemah (teks)

Berikut adalah contoh permintaan HTTP cURL menggunakan localhost:5000 yang Anda tentukan dengan docker run perintah :

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

Catatan

Jika Anda mencoba permintaan cURL POST sebelum kontainer siap, Anda akan menerima respons Layanan sementara tidak tersedia. Tunggu sampai kontainer siap, lalu coba lagi.

Menerjemahkan teks menggunakan API Swagger

Bahasa Inggris ↔ Jerman

  1. Navigasi ke halaman Swagger: http://localhost:5000/swagger/index.html
  2. Pilih POST /terjemahkan
  3. Pilih Coba
  4. Masukkan parameter Dari sebagai en
  5. Masukkan parameter Ke sebagai de
  6. Masukkan parameter versi api sebagai 3.0
  7. Di bagian teks, ganti string dengan JSON berikut
  [
        {
            "text": "hello, how are you"
        }
  ]

Pilih Eksekusi, terjemahan yang dihasilkan berupa output dalam Isi Respons. Anda akan melihat respon berikut.

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

Menerjemahkan teks dengan Python

Bahasa Inggris ↔ Prancis

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=(',', ': ')))

Menerjemahkan teks dengan aplikasi konsol C#/.NET

Bahasa Spanyol Inggris ↔

Buka Visual Studio, dan buat aplikasi konsol baru. Edit file *.csproj untuk menambahkan simpul <LangVersion>7.1</LangVersion> —menentukan C# 7.1. Tambahkan paket Newtoonsoft.Json NuGet versi 11.0.2.

Di Program.cs, ganti semua kode yang ada dengan skrip berikut:

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();
            }
        }
    }
}

Menerjemahkan beberapa string

Menerjemahkan beberapa string sekaligus hanyalah masalah menentukan larik string dalam isi permintaan.

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

Respons berisi terjemahan semua bagian teks dalam urutan yang sama persis seperti dalam permintaan. Isi respons adalah:

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

Menerjemahkan ke beberapa bahasa

Contoh ini menunjukkan cara menerjemahkan input yang sama ke beberapa bahasa dalam satu permintaan.

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

Isi respons adalah:

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

Menerjemahkan konten dengan markup dan menentukan konten yang diterjemahkan

Adalah umum untuk menerjemahkan konten yang menyertakan markup seperti konten dari halaman HTML atau konten dari dokumen XML. Sertakan parameter kueri textType=html saat menerjemahkan konten dengan tag. Selain itu, terkadang konten tertentu harus dikecualikan dari terjemahan. Anda dapat menggunakan atribut class=notranslate untuk menentukan konten yang harus tetap dalam bahasa aslinya. Dalam contoh berikut, konten di dalam elemen pertama div tidak diterjemahkan, sementara konten dalam elemen kedua div diterjemahkan.

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

Berikut adalah permintaan sampel yang akan diilustrasikan.

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

Responnya adalah:

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

Menerjemahkan dengan kamus dinamis

Jika Anda sudah mengetahui terjemahan yang ingin Anda terapkan pada kata atau frasa, Anda dapat menyediakannya sebagai markup dalam permintaan. Kamus dinamis hanya aman untuk kata benda seperti nama pribadi dan nama produk.

Markup yang dimasukkan menggunakan sintaks berikut.

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

Misalnya, pertimbangkan kalimat bahasa Inggris "The word wordomatic is a dictionary entry." To preserve the word wordomatic dalam terjemahan, kirimkan permintaan:

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

Hasilnya adalah:

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

Fitur ini bekerja dengan cara yang sama dengan textType=text atau dengan textType=html. Sebaiknya jangan terlalu sering menggunakan fitur ini. Cara yang tepat dan jauh lebih baik untuk menyesuaikan terjemahan adalah menggunakan Penerjemah Kustom. Penerjemah Kustom memanfaatkan sepenuhnya probabilitas konteks dan statistik. Jika Anda membuat data pelatihan yang memperlihatkan pekerjaan atau frasa dalam konteks, Anda mendapatkan hasil yang lebih baik. Pelajari Penerjemah Kustom lebih lanjut.

Batas permintaan

Setiap permintaan terjemahan dibatasi hingga 10.000 karakter, di semua bahasa target yang Anda terjemahkan. Misalnya, mengirim permintaan terjemahan 3.000 karakter untuk diterjemahkan ke tiga bahasa yang berbeda menghasilkan ukuran permintaan 3000x3 = 9.000 karakter, yang memenuhi batas permintaan. Anda dikenakan biaya per karakter, bukan berdasarkan jumlah permintaan. Sebaiknya kirim permintaan yang lebih pendek.

Tabel berikut ini mencantumkan elemen larik dan batas karakter untuk setiap operasi terjemahan Penerjemah.

Operasi Ukuran maksimum elemen larik Jumlah maksimum elemen larik Ukuran permintaan maksimum (karakter)
translate 10,000 100 10,000

Gunakan docker compose: Penerjemah dengan kontainer pendukung

Docker compose adalah alat yang memungkinkan Anda mengonfigurasi aplikasi multi-kontainer menggunakan satu file YAML yang biasanya bernama compose.yaml. docker compose up Gunakan perintah untuk memulai aplikasi kontainer Anda dan docker compose down perintah untuk menghentikan dan menghapus kontainer Anda.

Jika Anda menginstal Docker Desktop CLI, itu termasuk Docker compose dan prasyaratnya. Jika Anda tidak memiliki Docker Desktop, lihat gambaran umum Menginstal Docker Compose.

Tabel berikut mencantumkan kontainer pendukung yang diperlukan untuk operasi terjemahan teks dan dokumen Anda. Kontainer Penerjemah mengirim informasi penagihan ke Azure melalui sumber daya Azure AI Penerjemah di akun Azure Anda.

Operasi Permintaan kueri Jenis dokumen Kontainer pendukung
• Terjemahan teks
• Terjemahan Dokumen		 from Ditentukan. Dokumen Office Tidak
• Terjemahan teks
• Terjemahan Dokumen		 from tidak ditentukan. Memerlukan deteksi bahasa otomatis untuk menentukan bahasa sumber. Dokumen Office ✔️ Analitik teks:kontainer bahasa
• Terjemahan teks
• Terjemahan Dokumen		 from Ditentukan. Dokumen PDF yang dipindai ✔️ Visi:baca kontainer
• Terjemahan teks
• Terjemahan Dokumen		 from tidak ditentukan yang memerlukan deteksi bahasa otomatis untuk menentukan bahasa sumber. Dokumen PDF yang dipindai ✔️ Analitik teks:kontainer bahasa

✔️ Visi:baca kontainer
Gambar dan tag kontainer

Gambar kontainer layanan Azure AI dapat ditemukan di katalog Registri Artefak Microsoft. Tabel berikut mencantumkan lokasi gambar yang sepenuhnya memenuhi syarat untuk terjemahan teks dan dokumen:

Kontainer Lokasi citra Catatan
Penerjemah: Terjemahan teks mcr.microsoft.com/azure-cognitive-services/translator/text-translation:latest Anda dapat melihat daftar lengkap tag versi Terjemahan Teks layanan Azure AI di MCR.
Penerjemah: Terjemahan dokumen TODO TODO
Analitik teks: bahasa mcr.microsoft.com/azure-cognitive-services/textanalytics/language:latest Anda dapat melihat daftar lengkap layanan Azure AI Tag versi Bahasa Analitik Teks di MCR.
Visi: baca mcr.microsoft.com/azure-cognitive-services/vision/read:latest Anda dapat melihat daftar lengkap tag versi Computer Vision Read OCR layanan Azure AI di MCR.

Membuat aplikasi

  1. Dengan menggunakan editor atau IDE pilihan Anda, buat direktori baru untuk aplikasi Anda bernama container-environment atau nama pilihan Anda.

  2. Buat file YAML baru bernama compose.yaml. Ekstensi .yml atau .yaml dapat digunakan untuk file.compose

  3. Salin dan tempel sampel kode YAML berikut ke dalam file Anda compose.yaml . Ganti {TRANSLATOR_KEY} dan {TRANSLATOR_ENDPOINT_URI} dengan nilai kunci dan titik akhir dari instans portal Azure Penerjemah Anda. Pastikan Anda menggunakan document translation endpoint.

  4. Nama tingkat atas (azure-ai-translator, azure-ai-language, ) azure-ai-readadalah parameter yang Anda tentukan.

  5. container_name adalah parameter opsional yang menetapkan nama untuk kontainer saat berjalan, daripada membiarkan docker compose menghasilkan nama.

    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. Buka terminal navigasi ke container-environment folder, dan mulai kontainer dengan perintah berikut docker-compose :

    docker compose up

  7. Untuk menghentikan kontainer, gunakan perintah berikut:

    docker compose down

    Tip

    docker compose Perintah:

    • docker compose pause menjeda kontainer yang sedang berjalan.
    • docker compose unpause {your-container-name} membatalkan jeda kontainer yang dijeda.
    • docker compose restart memulai ulang semua kontainer yang dihentikan dan berjalan dengan semua perubahan sebelumnya utuh. Jika Anda membuat perubahan pada konfigurasi, compose.yaml perubahan ini tidak diperbarui dengan docker compose restart perintah . Anda harus menggunakan docker compose up perintah untuk mencerminkan pembaruan dan perubahan dalam compose.yaml file.
    • docker compose ps -a mencantumkan semua kontainer, termasuk yang dihentikan.
    • docker compose exec memungkinkan Anda menjalankan perintah untuk melepaskan atau mengatur variabel lingkungan dalam kontainer yang sedang berjalan.

    Untuk informasi selengkapnya, lihatreferensi CLI docker.

Langkah berikutnya

Pelajari selengkapnya tentang terjemahan teks