Share via

Pustaka klien Terjemahan Dokumen Batch

  • Artikel

Terjemahan Dokumen adalah fitur berbasis cloud dari layanan azure AI Penerjemah yang secara asinkron menerjemahkan seluruh dokumen dalam bahasa yang didukung dan berbagai format file. Dalam mulai cepat ini, pelajari cara menggunakan Terjemahan Dokumen dengan bahasa pemrograman pilihan Anda untuk menerjemahkan dokumen sumber ke dalam bahasa target sambil mempertahankan struktur dan pemformatan teks.

Penting

  • Terjemahan Dokumen saat ini hanya didukung dalam sumber daya Penerjemah (layanan tunggal), dan tidak disertakan dalam sumber daya layanan Azure AI (multi-layanan).

  • Terjemahan Dokumen didukung dalam tingkat berbayar. Language Studio hanya mendukung tingkat instans S1 atau D3. Kami menyarankan agar Anda memilih Standar S1 untuk mencoba Terjemahan Dokumen. LihatHarga layanan Azure AI—Penerjemah.

Prasyarat

Untuk memulai, Anda memerlukan:

  • Akun Azure aktif. Jika Anda tidak memilikinya, Anda dapat membuat akun gratis.

  • Sumber daya Penerjemah layanan tunggal (bukan sumber daya layanan Azure AI multi-layanan). Jika Anda berencana menggunakan fitur Terjemahan Dokumen dengan otorisasi identitas terkelola, pilih wilayah geografis seperti US Timur. Pilih standar S1 atau D3 atau tingkat harga.

  • Akun Azure Blob Storage. Anda akan membuat kontainer di akun Azure Blob Storage untuk file sumber dan target Anda:

    • Kontainer sumber. Kontainer ini adalah tempat Anda mengunggah file yang akan diterjemahkan (wajib).
    • Kontainer target. Kontainer ini adalah tempat file terjemahan Anda disimpan (diperlukan).

Otorisasi kontainer penyimpanan

Anda dapat memilih salah satu opsi berikut untuk mengotorisasi akses ke sumber daya Penerjemah Anda.

✔️ Identitas Terkelola. Identitas terkelola adalah perwakilan layanan yang membuat identitas Microsoft Entra dan izin khusus untuk sumber daya terkelola Azure. Identitas terkelola memungkinkan Anda menjalankan aplikasi Penerjemah tanpa harus menyematkan kredensial dalam kode Anda. Identitas terkelola adalah cara yang lebih aman untuk memberikan akses ke data penyimpanan dan mengganti persyaratan bagi Anda untuk menyertakan token tanda tangan akses bersama (SAS) dengan URL sumber dan target Anda.

Untuk mempelajari selengkapnya, lihatIdentitas terkelola untuk Terjemahan Dokumen.

Screenshot of managed identity flow (RBAC).

✔️ Tanda Tangan Akses Bersama (SAS). Tanda tangan akses bersama adalah URL yang memberikan akses terbatas untuk jangka waktu tertentu ke layanan Penerjemah Anda. Untuk menggunakan metode ini, Anda perlu membuat token Tanda Tangan Akses Bersama (SAS) untuk kontainer sumber dan target Anda. sourceUrl dan targetUrl harus menyertakan token Tanda Tangan Akses Bersama (SAS), ditambahkan sebagai string kueri. Token dapat ditetapkan ke kontainer Anda atau blob tertentu.

  • Kontainer sumber atau blob Anda harus menunjuk akses baca dan daftar.
  • Kontainer atau blob target Anda harus menunjuk akses tulis dan daftar.

Untuk mempelajari selengkapnya, lihatMembuat token SAS.

Screenshot of a resource URI with a SAS token.

Bangun aplikasi Anda

Ada beberapa alat yang tersedia untuk membuat, membangun, dan menjalankan aplikasi C#/.NET Penerjemah. Di sini, kami memandu Anda menggunakan antarmuka baris perintah (CLI) atau Visual Studio. Pilih salah satu tab berikut untuk memulai:

Menyiapkan proyek Anda

Di jendela konsol (seperti cmd, PowerShell, atau Bash), gunakan perintah dotnet new untuk membuat aplikasi konsol baru dengan nama batch-document-translation. Perintah ini membuat proyek C# "Halo Dunia" sederhana dengan file sumber tunggal: Program.cs.

dotnet new console -n batch-document-translation

Ubah direktori Anda ke folder aplikasi yang baru dibuat. Bangun aplikasi Anda dengan perintah berikut:

dotnet build

Output build tidak boleh berisi peringatan atau kesalahan.

...
Build succeeded.
 0 Warning(s)
 0 Error(s)
...

Memasang pustaka klien

Dalam direktori aplikasi, instal pustaka klien Terjemahan Dokumen untuk .NET:

dotnet add package Azure.AI.Translation.Document --version 1.0.0

Menerjemahkan dokumen atau file batch

  1. Untuk proyek ini, Anda memerlukan dokumen sumber yang diunggah ke kontainer sumber Anda. Anda dapat mengunduh dokumen sampel terjemahan dokumen kami untuk mulai cepat ini. Bahasa sumbernya adalah bahasa Inggris.

  2. Dari direktori proyek, buka file Program.cs di editor atau IDE pilihan Anda. Hapus kode yang sudah ada sebelumnya, termasuk baris Console.WriteLine("Hello World!").

  3. Dalam Program.cs aplikasi , buat variabel untuk kunci dan titik akhir kustom Anda. Untuk informasi selengkapnya, lihatMengambil kunci dan titik akhir domain kustom Anda.

    private static readonly string endpoint = "<your-document-translation-endpoint>";
private static readonly string key = "<your-key>";

  4. StartTranslationAsync Panggil metode untuk Memulai operasi terjemahan untuk satu atau beberapa dokumen dalam satu kontainer blob.

  5. Untuk memanggil StartTranslationAsync, Anda perlu menginisialisasi DocumentTranslationInput objek yang berisi sourceUriparameter , targetUri, dan targetLanguageCode :

    • Untuk otorisasi Identitas Terkelola, buat variabel ini:

      • sourceUri. URL untuk kontainer sumber yang berisi dokumen yang akan diterjemahkan.

      • targetUri URL untuk kontainer target tempat dokumen yang diterjemahkan ditulis.

      • targetLanguageCode. Kode bahasa pemrogram untuk dokumen yang diterjemahkan. Anda dapat menemukan kode bahasa pemrogram di halaman Dukungan bahasa pemrogram kami.

        Untuk menemukan URL sumber dan target Anda, navigasikan ke akun penyimpanan Anda di portal Azure. Di bilah sisi kiri, di bawah Penyimpanan data , pilih Kontainer, dan ikuti langkah-langkah ini untuk mengambil dokumen sumber dan kontainer URLStarget Anda.

        Sumber Target
        1. Pilih kotak centang di samping kontainer sumber 1. Pilih kotak centang di samping kontainer target.
        2. Dari area jendela utama, pilih file atau dokumen untuk diterjemahkan. 2. Pilih elipsis yang terletak di sebelah kanan, lalu pilih Properti.
        3. URL sumber terletak di bagian atas daftar Properti. 3. URL target terletak di bagian atas daftar Properti.

    • Untuk otorisasi Tanda Tangan Akses Bersama (SAS) buat variabel ini

      • sourceUri. SAS URI, dengan token SAS ditambahkan sebagai string kueri, agar kontainer sumber yang berisi dokumen akan diterjemahkan.
      • targetUri URI SAS, dengan token SAS ditambahkan sebagai string kueri, untuk kontainer target tempat dokumen yang diterjemahkan ditulis.
      • targetLanguageCode. Kode bahasa pemrogram untuk dokumen yang diterjemahkan. Anda dapat menemukan kode bahasa pemrogram di halaman Dukungan bahasa pemrogram kami.

Sampel kode

Penting

Jangan lupa menghapus kunci dari kode setelah Anda selesai, dan jangan pernah mempostingnya secara publik. Untuk produksi, gunakan cara yang aman untuk menyimpan dan mengakses kredensial Anda seperti Azure Key Vault. Untuk informasi selengkapnya, lihat Keamanan layanan Azure AI.

Masukkan sampel kode berikut ke dalam file Program.cs aplikasi Anda:


using Azure;
using Azure.AI.Translation.Document;
using System;
using System.Threading;
using System.Text;

class Program {

  // create variables for your custom endpoint and resource key
  private static readonly string endpoint = "<your-document-translation-endpoint>";
  private static readonly string key = "<your-key>";

  static async Task Main(string[] args) {

    // create variables for your sourceUrl, targetUrl, and targetLanguageCode
    Uri sourceUri = new Uri("<sourceUrl>");
    Uri targetUri = new Uri("<targetUrl>");
    string targetLanguage = "<targetLanguageCode>"

    // initialize a new instance  of the DocumentTranslationClient object to interact with the Document Translation feature
    DocumentTranslationClient client = new DocumentTranslationClient(new Uri(endpoint), new AzureKeyCredential(key));

    // initialize a new instance of the `DocumentTranslationInput` object to provide the location of input for the translation operation
    DocumentTranslationInput input = new DocumentTranslationInput(sourceUri, targetUri, targetLanguage);

    // initialize a new instance of the DocumentTranslationOperation class to track the status of the translation operation
    DocumentTranslationOperation operation = await client.StartTranslationAsync(input);

    await operation.WaitForCompletionAsync();

    Console.WriteLine($"  Status: {operation.Status}");
    Console.WriteLine($"  Created on: {operation.CreatedOn}");
    Console.WriteLine($"  Last modified: {operation.LastModified}");
    Console.WriteLine($"  Total documents: {operation.DocumentsTotal}");
    Console.WriteLine($"    Succeeded: {operation.DocumentsSucceeded}");
    Console.WriteLine($"    Failed: {operation.DocumentsFailed}");
    Console.WriteLine($"    In Progress: {operation.DocumentsInProgress}");
    Console.WriteLine($"    Not started: {operation.DocumentsNotStarted}");

    await foreach(DocumentStatusResult document in operation.Value) {
      Console.WriteLine($"Document with Id: {document.Id}");
      Console.WriteLine($"  Status:{document.Status}");
      if (document.Status == DocumentTranslationStatus.Succeeded) {
        Console.WriteLine($"  Translated Document Uri: {document.TranslatedDocumentUri}");
        Console.WriteLine($"  Translated to language: {document.TranslatedToLanguageCode}.");
        Console.WriteLine($"  Document source Uri: {document.SourceDocumentUri}");
      } else {
        Console.WriteLine($"  Error Code: {document.Error.Code}");
        Console.WriteLine($"  Message: {document.Error.Message}");
      }
    }
  }
}

Jalankan aplikasi Anda

Setelah Anda menambahkan sampel kode ke aplikasi Anda, jalankan aplikasi Anda dari direktori proyek dengan mengetik perintah berikut di terminal Anda:

  dotnet run

Berikut adalah cuplikan dari output yang diharapkan:

Screenshot of the Visual Studio Code output in the terminal window.

Itu saja! Anda baru saja membuat program untuk menerjemahkan dokumen dalam kontainer penyimpanan menggunakan pustaka klien .NET.

Menyiapkan proyek Anda

Pastikan bahwa versi terbaru Python diinstal.

Memasang pustaka klien

Instal versi terbaru pustaka klien Terjemahan Dokumen:

pip install azure-ai-translation-document==1.0.0

Menerjemahkan dokumen atau file batch

  1. Untuk proyek ini, Anda memerlukan dokumen sumber yang diunggah ke kontainer sumber Anda. Anda dapat mengunduh dokumen sampel terjemahan dokumen kami untuk mulai cepat ini. Bahasa sumbernya adalah bahasa Inggris.

  2. Dalam file aplikasi Python Anda, buat variabel untuk kunci sumber daya dan titik akhir kustom Anda. Untuk informasi selengkapnya, lihatMengambil kunci dan titik akhir domain kustom Anda.

key = "<your-key>"
endpoint = "<your-custom-endpoint>"

  1. Menginisialisasi DocumentTranslationClient objek yang berisi parameter dan key Andaendpoint.

  2. begin_translation Panggil metode dan teruskan sourceUriparameter , targetUri, dan targetLanguageCode .

    • Untuk otorisasi Identitas Terkelola, buat variabel ini:

      • sourceUri. URL untuk kontainer sumber yang berisi dokumen yang akan diterjemahkan.

      • targetUri URL untuk kontainer target tempat dokumen yang diterjemahkan ditulis.

      • targetLanguageCode. Kode bahasa pemrogram untuk dokumen yang diterjemahkan. Anda dapat menemukan kode bahasa pemrogram di halaman Dukungan bahasa pemrogram kami.

        Untuk menemukan URL sumber dan target Anda, navigasikan ke akun penyimpanan Anda di portal Azure. Di bilah sisi kiri, di bawah Penyimpanan data , pilih Kontainer, dan ikuti langkah-langkah ini untuk mengambil dokumen sumber dan kontainer URLStarget Anda.

        Sumber Target
        1. Pilih kotak centang di samping kontainer sumber 1. Pilih kotak centang di samping kontainer target.
        2. Dari area jendela utama, pilih file atau dokumen untuk diterjemahkan. 2. Pilih elipsis yang terletak di sebelah kanan, lalu pilih Properti.
        3. URL sumber terletak di bagian atas daftar Properti. 3. URL target terletak di bagian atas daftar Properti.

    • Untuk otorisasi Tanda Tangan Akses Bersama (SAS) buat variabel ini

      • sourceUri. SAS URI, dengan token SAS ditambahkan sebagai string kueri, agar kontainer sumber yang berisi dokumen akan diterjemahkan.
      • targetUri URI SAS, dengan token SAS ditambahkan sebagai string kueri, untuk kontainer target tempat dokumen yang diterjemahkan ditulis.
      • targetLanguageCode. Kode bahasa pemrogram untuk dokumen yang diterjemahkan. Anda dapat menemukan kode bahasa pemrogram di halaman Dukungan bahasa pemrogram kami.

Sampel Kode

Penting

Jangan lupa menghapus kunci dari kode setelah Anda selesai, dan jangan pernah mempostingnya secara publik. Untuk produksi, gunakan cara yang aman untuk menyimpan dan mengakses kredensial Anda seperti Azure Key Vault. Untuk informasi selengkapnya, lihat Keamanan layanan Azure AI.

Masukkan sampel kode berikut ke dalam aplikasi Python Anda:


#  import libraries
from azure.core.credentials import AzureKeyCredential
from azure.ai.translation.document import DocumentTranslationClient

# create variables for your resource key, custom endpoint, sourceUrl, targetUrl, and targetLanguage
key = "<your-key>"
endpoint = "<your-custom-endpoint>"
sourceUri = "<your-container-sourceUrl>"
targetUri = "<your-container-targetUrl>"
targetLanguage = "<target-language-code>"


# initialize a new instance of the DocumentTranslationClient object to interact with the Document Translation feature
client = DocumentTranslationClient(endpoint, AzureKeyCredential(key))

# include source and target locations and target language code for the begin translation operation
poller = client.begin_translation(sourceUri, targetUri, targetLanguage)
result = poller.result()

print("Status: {}".format(poller.status()))
print("Created on: {}".format(poller.details.created_on))
print("Last updated on: {}".format(poller.details.last_updated_on))
print(
    "Total number of translations on documents: {}".format(
        poller.details.documents_total_count
    )
)

print("\nOf total documents...")
print("{} failed".format(poller.details.documents_failed_count))
print("{} succeeded".format(poller.details.documents_succeeded_count))

for document in result:
    print("Document ID: {}".format(document.id))
    print("Document status: {}".format(document.status))
    if document.status == "Succeeded":
        print("Source document location: {}".format(document.source_document_url))
        print(
            "Translated document location: {}".format(document.translated_document_url)
        )
        print("Translated to language: {}\n".format(document.translated_to))
    else:
        print(
            "Error Code: {}, Message: {}\n".format(
                document.error.code, document.error.message
            )
        )

Jalankan aplikasi Anda

Setelah Anda menambahkan sampel kode ke aplikasi Anda, ketik perintah berikut di terminal Anda:

python asynchronous-sdk.py

Berikut adalah cuplikan dari output yang diharapkan:

Screenshot of the Python output in the terminal window.

Itu saja! Anda baru saja membuat program untuk menerjemahkan dokumen dalam kontainer penyimpanan menggunakan pustaka klien Python.

Langkah selanjutnya

Pelajari selengkapnya tentang operasi Terjemahan Dokumen