Perpustakaan klien Azure Document Translation untuk JavaScript - versi 1.0.0

Terjemahan Dokumen adalah fitur terjemahan mesin berbasis cloud dari layanan Azure AI Penerjemah. Anda dapat menerjemahkan beberapa dokumen dan dokumen kompleks di semua bahasa dan dialek yang didukung sambil mempertahankan struktur dokumen asli dan format data. API Terjemahan Dokumen mendukung dua proses terjemahan:

Terjemahan batch asinkron mendukung pemrosesan beberapa dokumen dan file besar. Proses terjemahan batch memerlukan akun penyimpanan Azure Blob dengan kontainer penyimpanan untuk sumber dan dokumen yang diterjemahkan.

Terjemahan file tunggal sinkron mendukung pemrosesan terjemahan file tunggal. Proses terjemahan file tidak memerlukan akun penyimpanan Azure Blob. Respons akhir berisi dokumen yang diterjemahkan dan dikembalikan langsung ke klien panggilan.

Operasi berikut didukung oleh fitur Terjemahan Dokumen:

  • Terjemahan dokumen sinkron: Digunakan untuk menerjemahkan satu dokumen secara sinkron. Metode ini tidak memerlukan akun penyimpanan Azure Blob.
  • Mulai terjemahan batch: Digunakan untuk menjalankan permintaan terjemahan batch asinkron. Metode ini memerlukan akun penyimpanan Azure Blob dengan kontainer penyimpanan untuk sumber dan dokumen yang diterjemahkan.
  • Dapatkan status untuk semua pekerjaan terjemahan: Digunakan untuk meminta daftar dan status semua pekerjaan terjemahan yang dikirim oleh pengguna (terkait dengan sumber daya).
  • Dapatkan status untuk pekerjaan terjemahan tertentu: Digunakan untuk meminta status pekerjaan terjemahan tertentu. Respons mencakup status pekerjaan keseluruhan dan status untuk dokumen yang sedang diterjemahkan sebagai bagian dari pekerjaan tersebut.
  • Dapatkan status untuk semua dokumen: Digunakan untuk meminta status semua dokumen dalam pekerjaan terjemahan.
  • Dapatkan status untuk dokumen tertentu: Mengembalikan status untuk dokumen tertentu dalam pekerjaan seperti yang ditunjukkan dalam permintaan oleh parameter id dan documentId.
  • Batal terjemahan: Membatalkan pekerjaan terjemahan yang sedang diproses atau sedang antrean (pending). Operasi tidak dibatalkan jika sudah selesai, gagal, atau masih dibatalkan.
  • Dapatkan format yang didukung: Mengembalikan daftar format dokumen atau glosarium yang didukung oleh fitur Terjemahan Dokumen.

Tautan kunci:

Memulai Langkah Pertama

Lingkungan yang didukung saat ini

Lihat kebijakan dukungan kami untuk detail selengkapnya.

Prasyarat

Pasang paket @azure/ai-translation-document

Instal pustaka klien Azure Document Translation untuk JavaScript dengan npm:

npm install @azure/ai-translation-document

Siapkan akun Azure Blob Storage

Terjemahan batch memerlukan akun Azure Blob Storage. Untuk informasi lebih lanjut tentang membuat akun Azure Blob Storage, lihat di sini. Untuk membuat kontainer untuk file sumber dan target Anda, lihat di sini. Pastikan untuk mengotorisasi akses penyimpanan sumber daya Terjemahan Anda, info lebih lanjut di sini.

Ketika "Izinkan Akses Kunci Akun Penyimpanan" dinonaktifkan pada akun penyimpanan, Managed Identity diaktifkan pada sumber daya Translator, dan diberikan peran "Storage Blob Data Contributor" pada akun penyimpanan, maka Anda dapat menggunakan URL kontainer secara langsung dan tidak perlu menghasilkan SAS URI.

Mengautentikasi klien

Perpustakaan ini menampilkan dua klien:

  • DocumentTranslationClient untuk operasi terjemahan batch dan status terjemahan.
  • SingleDocumentTranslationClient untuk terjemahan dokumen tunggal secara sinkron.

Kedua klien dapat mengautentikasi dengan kredensial Microsoft Entra atau kunci API.

Menggunakan kredensial Microsoft Entra

Anda dapat mengautentikasi dengan Microsoft Entra ID menggunakan kredensial dari pustaka @azure/identity. Untuk menggunakan penyedia DefaultAzureCredential yang ditunjukkan di bawah ini, atau penyedia kredensial lain yang disediakan dengan Azure SDK, instal paket :

npm install @azure/identity

Anda juga perlu mendaftarkan aplikasi Microsoft Entra baru dan memberikan akses ke sumber daya Translator dengan menetapkan peran yang sesuai kepada prinsipal layanan Anda.

Dengan menggunakan lingkungan Node.js dan Node-like, Anda dapat menggunakan kelas untuk DefaultAzureCredential mengautentikasi klien:

import { DocumentTranslationClient } from "@azure/ai-translation-document";
import { DefaultAzureCredential } from "@azure/identity";

const endpoint = "https://<translator-instance>.cognitiveservices.azure.com";
const client = new DocumentTranslationClient(endpoint, new DefaultAzureCredential());

Untuk lingkungan browser, gunakan InteractiveBrowserCredential dari @azure/identity paket untuk mengautentikasi:

import { InteractiveBrowserCredential } from "@azure/identity";
import { DocumentTranslationClient } from "@azure/ai-translation-document";

const credential = new InteractiveBrowserCredential({
  tenantId: "<YOUR_TENANT_ID>",
  clientId: "<YOUR_CLIENT_ID>",
});
const client = new DocumentTranslationClient("<endpoint>", credential);

Menggunakan kunci API

Anda juga dapat mengautentikasi dengan kunci API sumber daya menggunakan KeyCredential:

import { KeyCredential } from "@azure/core-auth";
import { DocumentTranslationClient } from "@azure/ai-translation-document";

const endpoint = "https://<translator-instance>.cognitiveservices.azure.com";
const credential: KeyCredential = { key: "YOUR_SUBSCRIPTION_KEY" };
const client = new DocumentTranslationClient(endpoint, credential);

Bundel JavaScript

Untuk menggunakan pustaka klien ini di browser, pertama-tama Anda perlu menggunakan bunder. Untuk detail tentang cara melakukan ini, silakan lihat dokumentasi bundling kami.

Konsep Utama

DocumentTranslationClient

DocumentTranslationClient adalah antarmuka untuk terjemahan batch asinkron dan untuk menanyakan status terjemahan dan dokumen. Terjemahan batch memerlukan akun Azure Blob Storage dengan kontainer untuk dokumen sumber dan terjemahan Anda.

SingleDocumentTranslationClient

SingleDocumentTranslationClient adalah antarmuka untuk terjemahan dokumen tunggal secara sinkron. Tidak memerlukan akun Azure Blob Storage; dokumen terjemahan dikembalikan langsung dalam respons.

Examples

Bagian berikut menyediakan beberapa potongan kode yang mencakup fitur utama perpustakaan klien ini.

Terjemahan dokumen sinkron

Digunakan untuk menerjemahkan satu dokumen secara sinkron. Metode ini tidak memerlukan akun penyimpanan Azure Blob.

import { SingleDocumentTranslationClient } from "@azure/ai-translation-document";
import { DefaultAzureCredential } from "@azure/identity";
import { writeFile } from "node:fs/promises";

const endpoint = "https://<translator-instance>.cognitiveservices.azure.com";
const client = new SingleDocumentTranslationClient(endpoint, new DefaultAzureCredential());
const response = await client.translate("hi", {
  document: {
    contents: "This is a test.",
    contentType: "text/html",
    filename: "test-input.txt",
  },
});
if (response.readableStreamBody) {
  await writeFile("test-output.txt", response.readableStreamBody);
}

Terjemahan dokumen secara batch

Digunakan untuk menjalankan permintaan terjemahan batch asinkron. Metode ini memerlukan akun penyimpanan Azure Blob dengan kontainer penyimpanan untuk sumber dan dokumen yang diterjemahkan. Berikan URL kontainer sumber dan target (dengan token SAS jika diperlukan) dan polling sampai operasi selesai.

import { DocumentTranslationClient } from "@azure/ai-translation-document";
import { DefaultAzureCredential } from "@azure/identity";

const endpoint = "https://<translator-instance>.cognitiveservices.azure.com";
const client = new DocumentTranslationClient(endpoint, new DefaultAzureCredential());
const poller = client.startTranslation({
  inputs: [
    {
      source: { sourceUrl: "<source container SAS URL>" },
      targets: [{ targetUrl: "<target container SAS URL>", language: "fr" }],
    },
  ],
});
const result = await poller.pollUntilDone();
console.log(`Translation status: ${result.status}`);

Dapatkan format yang didukung

Mengembalikan daftar format dokumen yang didukung oleh fitur Terjemahan Dokumen.

import { DocumentTranslationClient } from "@azure/ai-translation-document";
import { DefaultAzureCredential } from "@azure/identity";

const endpoint = "https://<translator-instance>.cognitiveservices.azure.com";
const client = new DocumentTranslationClient(endpoint, new DefaultAzureCredential());
const formats = await client.getSupportedFormats("Document");
for (const format of formats.value) {
  console.log(format.format);
}

Troubleshooting

Penebangan kayu

Mengaktifkan pengelogan dapat membantu menemukan informasi yang berguna tentang kegagalan. Untuk melihat log permintaan dan respons HTTP, atur variabel lingkungan AZURE_LOG_LEVEL ke info. Atau, pengelogan dapat diaktifkan saat runtime dengan memanggil setLogLevel di @azure/logger:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Untuk instruksi lebih rinci tentang cara mengaktifkan log, Anda dapat melihat dokumen paket @azure/logger.

Contributing

Jika Anda ingin berkontribusi pada pustaka ini, baca panduan berkontribusi untuk mempelajari selengkapnya tentang cara membuat dan menguji kode.

  • Last updated on