Batch Belge Çevirisi istemci kitaplıkları

  • Makale

Belge Çevirisi, Azure AI Çeviri hizmetinin desteklenen dillerde ve çeşitli dosya biçimlerinde belgelerin tamamını zaman uyumsuz olarak çeviren bulut tabanlı bir özelliğidir. Bu hızlı başlangıçta, kaynak belgeyi hedef dile çevirmek için seçtiğiniz bir programlama diliyle Belge Çevirisi'ni kullanmayı ve yapıyı ve metin biçimlendirmesini korumayı öğrenin.

Önemli

  • Belge Çevirisi şu anda yalnızca Çeviri (tek hizmetli) kaynakta desteklenir ve Azure AI hizmetleri (çok hizmetli) kaynağına dahil değildir.

  • Belge Çevirisi ücretli katmanlarda desteklenir. Language Studio yalnızca S1 veya D3 örnek katmanlarını destekler. Belge Çevirisi'ne geçmek için Standart S1'i seçmenizi öneririz. Bkz.Azure AI hizmetleri fiyatlandırması— Çeviri.

Önkoşullar

Başlamak için gerekli olanlar:

  • Etkin bir Azure hesabı. Hesabınız yoksa ücretsiz bir hesap oluşturabilirsiniz.

  • Tek hizmetli Çeviri kaynağı (çok hizmetli bir Azure AI hizmetleri kaynağı değil). Belge Çevirisi özelliğini yönetilen kimlik yetkilendirmesiyle kullanmayı planlıyorsanız Doğu ABD gibi bir coğrafi bölge seçin. Standart S1 veya D3 ya da fiyatlandırma katmanını seçin.

  • bir Azure Blob Depolama hesabı. kaynak ve hedef dosyalarınız için Azure Blob Depolama hesabınızda kapsayıcılar oluşturacaksınız:

    • Kaynak kapsayıcı. Bu kapsayıcı, dosyalarınızı çeviri için karşıya yüklediğiniz yerdir (gerekli).
    • Hedef kapsayıcı. Bu kapsayıcı, çevrilen dosyalarınızın depolandığı yerdir (gereklidir).

kapsayıcı yetkilendirmeyi Depolama

Çeviri kaynağınıza erişim yetkisi vermek için aşağıdaki seçeneklerden birini belirleyebilirsiniz.

✔️ Yönetilen Kimlik. Yönetilen kimlik, Azure tarafından yönetilen bir kaynak için Microsoft Entra kimliği ve belirli izinler oluşturan bir hizmet sorumlusudur. Yönetilen kimlikler, kodunuzda kimlik bilgilerini eklemek zorunda kalmadan Çeviri uygulamanızı çalıştırmanıza olanak tanır. Yönetilen kimlikler, depolama verilerine erişim vermenin ve paylaşılan erişim imzası belirteçlerini (SAS) kaynak ve hedef URL'lerinizle ekleme gereksinimini değiştirmenin daha güvenli bir yoludur.

Daha fazla bilgi edinmek için bkz. Belge Çevirisi için yönetilen kimlikler.

Screenshot of managed identity flow (RBAC).

✔️ Paylaşılan Erişim İmzası (SAS). Paylaşılan erişim imzası, Çeviri hizmetinize belirli bir süre boyunca kısıtlanmış erişim sağlayan bir URL'dir. Bu yöntemi kullanmak için kaynak ve hedef kapsayıcılarınız için Paylaşılan Erişim İmzası (SAS) belirteçleri oluşturmanız gerekir. vetargetUrl, sourceUrl sorgu dizesi olarak eklenmiş bir Paylaşılan Erişim İmzası (SAS) belirteci içermelidir. Belirteç kapsayıcınıza veya belirli bloblara atanabilir.

  • Kaynak kapsayıcınızın veya blobunuzun okuma ve liste erişimi belirlemesi gerekir.
  • Hedef kapsayıcınızın veya blobunuzun yazma ve liste erişimi belirlemesi gerekir.

Daha fazla bilgi edinmek için bkz. SAS belirteçleri oluşturma.

Screenshot of a resource URI with a SAS token.

Uygulamanızı derleme

C#/.NET uygulamaları oluşturmak, oluşturmak ve çalıştırmak için Çeviri çeşitli araçlar vardır. Burada komut satırı arabirimini (CLI) veya Visual Studio'yu kullanarak size yol göstereceğiz. Başlamak için aşağıdaki sekmelerden birini seçin:

Projenizi ayarlama

Bir konsol penceresinde (cmd, PowerShell veya Bash gibi), adlı batch-document-translationyeni bir konsol uygulaması oluşturmak için komutunu kullanındotnet new. Bu komut, tek bir kaynak dosyayla basit bir "Merhaba Dünya" C# projesi oluşturur: Program.cs.

dotnet new console -n batch-document-translation

Dizininizi yeni oluşturulan uygulama klasörüyle değiştirin. Aşağıdaki komutla uygulamanızı derleyin:

dotnet build

Derleme çıkışı hiçbir uyarı veya hata içermemelidir.

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

İstemci kitaplığını yükleme

Uygulama dizininde .NET için Belge Çevirisi istemci kitaplığını yükleyin:

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

Belgeyi veya toplu iş dosyalarını çevirme

  1. Bu proje için kaynak kapsayıcınıza yüklenmiş bir kaynak belge gerekir. Bu hızlı başlangıç için belge çevirisi örnek belgemizi indirebilirsiniz. Kaynak dil İngilizcedir.

  2. Proje dizininden Program.cs dosyasını tercih ettiğiniz düzenleyicide veya IDE'de açın. satırı Console.WriteLine("Hello World!")da dahil olmak üzere önceden var olan kodu silin.

  3. Uygulamanın Program.cs anahtarınız ve özel uç noktanız için değişkenler oluşturun. Daha fazla bilgi için bkz. Anahtarınızı ve özel etki alanı uç noktanızı alma.

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

  4. Tek bir blob kapsayıcısında StartTranslationAsync bir veya daha fazla belge için çeviri işlemi başlatmak için yöntemini çağırın.

  5. çağrısı StartTranslationAsyncyapmak için , targetUrive targetLanguageCode parametrelerini içeren sourceUribir DocumentTranslationInput nesne başlatmanız gerekir:

    • Yönetilen Kimlik yetkilendirmesi için şu değişkenleri oluşturun:

      • sourceUri. Çevrilecek belgeleri içeren kaynak kapsayıcının URL'si.

      • targetUri Çevrilen belgelerin yazıldığı hedef kapsayıcının URL'si.

      • targetLanguageCode. Çevrilen belgelerin dil kodu. Dil kodlarını Dil desteği sayfamızda bulabilirsiniz.

        Kaynak ve hedef URL'lerinizi bulmak için Azure portalında depolama hesabınıza gidin. Sol kenar çubuğunda, Veri depolama altında Kapsayıcılar'ı seçin ve kaynak belgelerinizi ve hedef kapsayıcınızı URLSalmak için bu adımları izleyin.

        Source Target
        1. Kaynak kapsayıcının yanındaki onay kutusunu seçin 1. Hedef kapsayıcının yanındaki onay kutusunu seçin.
        2. Ana pencere alanından çeviri için bir dosya veya belge seçin. 2. Sağ tarafta bulunan üç noktayı ve ardından Özellikler'i seçin.
        3. Kaynak URL, Özellikler listesinin en üstünde bulunur. 3. Hedef URL, Özellikler listesinin en üstünde bulunur.

    • Paylaşılan Erişim İmzası (SAS) yetkilendirmesi için bu değişkenleri oluşturun

      • sourceUri. Belge içeren kaynak kapsayıcının çevrilmesi için sorgu dizesi olarak sas belirtecinin eklendiği SAS URI'si.
      • targetUri Çevrilmiş belgelerin yazıldığı hedef kapsayıcı için sorgu dizesi olarak eklenmiş bir SAS belirteci bulunan SAS URI'si.
      • targetLanguageCode. Çevrilen belgelerin dil kodu. Dil kodlarını Dil desteği sayfamızda bulabilirsiniz.

Kod örneği

Önemli

İşiniz bittiğinde anahtarı kodunuzdan kaldırmayı unutmayın ve asla herkese açık olarak göndermeyin. Üretim için Azure Key Vault gibi kimlik bilgilerinizi depolamanın ve bunlara erişmenin güvenli bir yolunu kullanın. Daha fazla bilgi için bkz . Azure AI hizmetleri güvenliği.

Uygulamanızın Program.cs dosyasına aşağıdaki kod örneğini girin:


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

Uygulamanızı çalıştırma

Kod örneğini uygulamanıza ekledikten sonra terminalinize aşağıdaki komutu yazarak proje dizininden uygulamanızı çalıştırın:

  dotnet run

Beklenen çıkışın kod parçacığı aşağıdadır:

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

İşte hepsi bu! .NET istemci kitaplığını kullanarak bir depolama kapsayıcısında belgeleri çevirmek için bir program oluşturdunuz.

Projenizi ayarlama

Python'ın en son sürümünün yüklü olduğundan emin olun.

İstemci kitaplığını yükleme

Belge Çevirisi istemci kitaplığının en son sürümünü yükleyin:

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

Belgeyi veya toplu iş dosyalarını çevirme

  1. Bu proje için kaynak kapsayıcınıza yüklenmiş bir kaynak belge gerekir. Bu hızlı başlangıç için belge çevirisi örnek belgemizi indirebilirsiniz. Kaynak dil İngilizcedir.

  2. Python uygulama dosyanızda kaynak anahtarınız ve özel uç noktanız için değişkenler oluşturun. Daha fazla bilgi için bkz. Anahtarınızı ve özel etki alanı uç noktanızı alma.

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

  1. ve key parametrelerinizi endpoint içeren bir DocumentTranslationClient nesne başlatın.

  2. yöntemini çağırın begin_translation ve , targetUrive targetLanguageCode parametrelerini geçirinsourceUri.

    • Yönetilen Kimlik yetkilendirmesi için şu değişkenleri oluşturun:

      • sourceUri. Çevrilecek belgeleri içeren kaynak kapsayıcının URL'si.

      • targetUri Çevrilen belgelerin yazıldığı hedef kapsayıcının URL'si.

      • targetLanguageCode. Çevrilen belgelerin dil kodu. Dil kodlarını Dil desteği sayfamızda bulabilirsiniz.

        Kaynak ve hedef URL'lerinizi bulmak için Azure portalında depolama hesabınıza gidin. Sol kenar çubuğunda, Veri depolama altında Kapsayıcılar'ı seçin ve kaynak belgelerinizi ve hedef kapsayıcınızı URLSalmak için bu adımları izleyin.

        Source Target
        1. Kaynak kapsayıcının yanındaki onay kutusunu seçin 1. Hedef kapsayıcının yanındaki onay kutusunu seçin.
        2. Ana pencere alanından çeviri için bir dosya veya belge seçin. 2. Sağ tarafta bulunan üç noktayı ve ardından Özellikler'i seçin.
        3. Kaynak URL, Özellikler listesinin en üstünde bulunur. 3. Hedef URL, Özellikler listesinin en üstünde bulunur.

    • Paylaşılan Erişim İmzası (SAS) yetkilendirmesi için bu değişkenleri oluşturun

      • sourceUri. Belge içeren kaynak kapsayıcının çevrilmesi için sorgu dizesi olarak sas belirtecinin eklendiği SAS URI'si.
      • targetUri Çevrilmiş belgelerin yazıldığı hedef kapsayıcı için sorgu dizesi olarak eklenmiş bir SAS belirteci bulunan SAS URI'si.
      • targetLanguageCode. Çevrilen belgelerin dil kodu. Dil kodlarını Dil desteği sayfamızda bulabilirsiniz.

Kod Örneği

Önemli

İşiniz bittiğinde anahtarı kodunuzdan kaldırmayı unutmayın ve asla herkese açık olarak göndermeyin. Üretim için Azure Key Vault gibi kimlik bilgilerinizi depolamanın ve bunlara erişmenin güvenli bir yolunu kullanın. Daha fazla bilgi için bkz . Azure AI hizmetleri güvenliği.

Python uygulamanıza aşağıdaki kod örneğini girin:


#  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
            )
        )

Uygulamanızı çalıştırma

Kod örneğini uygulamanıza ekledikten sonra terminalinize aşağıdaki komutu yazın:

python asynchronous-sdk.py

Beklenen çıkışın kod parçacığı aşağıdadır:

Screenshot of the Python output in the terminal window.

İşte hepsi bu! Python istemci kitaplığını kullanarak bir depolama kapsayıcısında belgeleri çevirmek için bir program oluşturdunuz.

Sonraki adım

Belge Çevirisi işlemleri hakkında daha fazla bilgi edinin