Első lépések: Dokumentumfordítási ügyfélkódtárak
A dokumentumfordítás az Azure AI Translator szolgáltatás felhőalapú funkciója, amely aszinkron módon lefordítja a teljes dokumentumokat támogatott nyelveken és különböző fájlformátumokban. Ebben a rövid útmutatóban megtanulhatja, hogyan használhatja a dokumentumfordítást egy tetszőleges programozási nyelvvel a forrásdokumentum célnyelvre való fordításához, miközben megőrzi a szerkezetet és a szövegformázást.
Fontos
- A dokumentumfordítás jelenleg csak a Translator (egyszolgáltatásos) erőforrásban támogatott, és nem szerepel az Azure AI-szolgáltatások (többszolgáltatásos) erőforrásában.
- A dokumentumfordítás fizetős szinteken támogatott. A Language Studio támogatja az S1- vagy D3-példányszinteket. Javasoljuk, hogy válassza a Standard S1 lehetőséget a dokumentumfordítás kipróbálásához. Tekintse meg az Azure AI-szolgáltatások díjszabását – Translator.
- A Dokumentumfordítás nyilvános előzetes verziójú kiadásai korai hozzáférést biztosítanak az aktív fejlesztés alatt lévő funkciókhoz. A funkciók, a megközelítések és a folyamatok az általános rendelkezésre állás (GA) előtt változhatnak a felhasználói visszajelzések alapján.
- A Dokumentumfordítás ügyfélkódtárak nyilvános előzetes verziója alapértelmezés szerint a REST API 2024-05-01-es verziója.
Előfeltételek
A kezdéshez a következők szükségesek:
Aktív Azure-fiók. Ha még nincs fiókja, hozzon létre egy ingyenes fiókot.
Egyszolgáltatásos Translator-erőforrás (nem többszolgáltatásos Azure AI-szolgáltatási erőforrás). Ha felügyelt identitásengedélyezéssel szeretné használni a Dokumentumfordítás funkciót, válasszon egy földrajzi régiót, például az USA keleti régióját. Válassza ki a Standard S1 Standard szolgáltatási csomagot (használatalapú fizetés) vagy A2, C3, C4 vagy D3 mennyiségi kedvezménycsomagokat.
Egy Azure Blob Storage-fiók. Tárolókat fog létrehozni az Azure Blob Storage-fiókjában a forrás- és célfájlokhoz:
- Forrástároló. Ebben a tárolóban töltheti fel a fájlokat fordításra (kötelező).
- Céltároló. Ez a tároló tárolja a lefordított fájlokat (kötelező).
Tároló engedélyezése a tárolóban
A Translator-erőforráshoz való hozzáférés engedélyezéséhez az alábbi lehetőségek közül választhat.
✔️ Felügyelt identitás. A felügyelt identitás egy szolgáltatásnév, amely létrehoz egy Microsoft Entra-identitást és egy Azure-beli felügyelt erőforrásra vonatkozó konkrét engedélyeket. A felügyelt identitások lehetővé teszik a Translator-alkalmazás futtatását anélkül, hogy hitelesítő adatokat kellene beágyaznia a kódba. A felügyelt identitások biztonságosabban biztosítják a tárolási adatokhoz való hozzáférést, és felülírják a közös hozzáférésű jogosultságkódok (SAS) forrás- és cél URL-címekkel való használatára vonatkozó követelményt.
További információ: Felügyelt identitások a dokumentumfordításhoz.
✔️ Közös hozzáférésű jogosultságkód (SAS). A megosztott hozzáférésű jogosultságkód olyan URL-cím, amely korlátozott hozzáférést biztosít a Translator-szolgáltatáshoz egy meghatározott ideig. A módszer használatához közös hozzáférésű jogosultságkód (SAS) jogkivonatokat kell létrehoznia a forrás- és céltárolókhoz. targetUrl
A sourceUrl
lekérdezési sztringként hozzáfűzött közös hozzáférésű jogosultságkód (SAS) jogkivonatot kell tartalmaznia. A jogkivonat hozzárendelhető a tárolóhoz vagy adott blobokhoz.
- A forrástárolónak vagy blobnak olvasási és listahozzáférést kell kijelölnie.
- A céltárolónak vagy blobnak írási és listahozzáférést kell kijelölnie.
További információ: SAS-jogkivonatok létrehozása.
Az alkalmazás összeállítása
Számos eszköz érhető el a Translator C#/.NET-alkalmazások létrehozásához, létrehozásához és futtatásához. Itt végigvezetjük a parancssori felület (CLI) vagy a Visual Studio használatával. Első lépésként válassza az alábbi lapok egyikét:
A projekt beállítása
Egy konzolablakban (például parancsmag, PowerShell vagy Bash) a dotnet new
paranccsal hozzon létre egy új konzolalkalmazást a névvel batch-document-translation
. Ez a parancs egy egyszerű "„Helló világ!” alkalmazás" C#-projektet hoz létre egyetlen forrásfájllal: Program.cs.
dotnet new console -n batch-document-translation
Módosítsa a könyvtárat az újonnan létrehozott alkalmazásmappára. Hozza létre az alkalmazást a következő paranccsal:
dotnet build
A buildkimenet nem tartalmazhat figyelmeztetést vagy hibát.
...
Build succeeded.
0 Warning(s)
0 Error(s)
...
Telepítse az ügyfélkódtárat
Az alkalmazáskönyvtárban telepítse a Dokumentumfordítás ügyfélkódtárat a .NET-hez:
dotnet add package Azure.AI.Translation.Document --version 2.0.0-beta
Dokumentumok aszinkron fordítása
Ehhez a projekthez egy forrásdokumentumot kell feltöltenie a forrástárolóba. Ehhez a rövid útmutatóhoz letöltheti dokumentumfordítási mintadokumentumunkat. A forrásnyelv az angol.
A projektkönyvtárban nyissa meg a Program.cs fájlt az előnyben részesített szerkesztőben vagy IDE-ben. Törölje a már meglévő kódot, beleértve a sort
Console.WriteLine("Hello World!")
is.Az alkalmazás Program.cs hozzon létre változókat a kulcshoz és az egyéni végponthoz. További információ: A kulcs és az egyéni tartományvégpont lekérése.
private static readonly string endpoint = "<your-document-translation-endpoint>"; private static readonly string key = "<your-key>";
A metódus meghívásával
StartTranslationAsync
elindíthat egy fordítási műveletet egy vagy több dokumentumhoz egyetlen blobtárolóban.A híváshoz
StartTranslationAsync
inicializálnia kell egyDocumentTranslationInput
objektumot, amely tartalmazza asourceUri
,targetUri
éstargetLanguageCode
a paramétereket:A felügyelt identitás engedélyezéséhez hozza létre a következő változókat:
sourceUri. A lefordítandó dokumentumokat tartalmazó forrástároló URL-címe.
targetUri Annak a céltárolónak az URL-címe, amelyhez a lefordított dokumentumok meg vannak írva.
targetLanguageCode. A lefordított dokumentumok nyelvi kódja. A nyelvi kódokat a Nyelvi támogatási oldalon találja.
A forrás- és cél URL-címek megkereséséhez keresse meg a tárfiókot az Azure Portalon. A bal oldali oldalsáv Adattárolás területén válassza a Tárolók lehetőséget, és kövesse az alábbi lépéseket a forrásdokumentumok és a céltároló
URLS
lekéréséhez.Forrás Cél 1. Jelölje be a forrástároló melletti jelölőnégyzetet 1. Jelölje be a céltároló melletti jelölőnégyzetet. 2. A főablak területén válassza ki a fordításhoz szükséges fájlt vagy dokumentumokat. 2. Jelölje ki a jobb oldalon található három pontot, majd válassza a Tulajdonságok lehetőséget. 3. A forrás URL-címe a Tulajdonságok lista tetején található. 3. A cél URL-cím a Tulajdonságok lista tetején található.
A közös hozzáférésű jogosultságkód (SAS) engedélyezéséhez hozza létre ezeket a változókat
- sourceUri. Az SAS URI lekérdezési sztringként hozzáfűzött SAS-jogkivonattal a lefordítandó dokumentumokat tartalmazó forrástárolóhoz.
- targetUri Az SAS URI lekérdezési sztringként hozzáfűzött SAS-jogkivonattal ahhoz a céltárolóhoz, amelyhez a lefordított dokumentumok meg vannak írva.
- targetLanguageCode. A lefordított dokumentumok nyelvi kódja. A nyelvi kódokat a Nyelvi támogatási oldalon találja.
Fontos
Ne felejtse el eltávolítani a kulcsot a kódból, amikor elkészült, és soha ne tegye közzé nyilvánosan. Éles környezetben biztonságos módon tárolhatja és érheti el a hitelesítő adatait, például az Azure Key Vaultot. További információ: Azure AI-szolgáltatások biztonsága.
Aszinkron fordítási kódminta
Írja be a következő kódmintát az alkalmazás Program.cs fájljába:
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}");
}
}
}
}
Az alkalmazás futtatása
Miután hozzáadta a kódmintát az alkalmazáshoz, futtassa az alkalmazást a projektkönyvtárból az alábbi parancs beírásával a terminálban:
dotnet run
Íme egy kódrészlet a várt kimenetről:
Szinkron fordítási kódminta
Ehhez a rövid útmutatóhoz letöltheti dokumentumfordítási mintadokumentumunkat. A forrásnyelv az angol.
using Azure;
using Azure.AI.Translation.Document;
using System;
using System.Threading;
using System.Text;
class Program {
string endpoint = "{your-document-translation-endpoint}";
string apiKey = "{your-api-key}";
SingleDocumentTranslationClient client = new SingleDocumentTranslationClient(new Uri(endpoint), new AzureKeyCredential(apiKey));
try
{
string filePath = @"C:\{folder}\document.txt"
using Stream fileStream = File.OpenRead(filePath);
// MultipartFormFileData (string name, System.IO.Stream content, string contentType);
var sourceDocument = new MultipartFormFileData(Path.GetFileName(filePath), fileStream, "application/vnd.openxmlformats-officedocument.wordprocessingml.document");
DocumentTranslateContent content = new DocumentTranslateContent(sourceDocument);
// DocumentTranslate (string targetLanguage, Azure.AI.Translation.Document.DocumentTranslateContent documentTranslateContent, string sourceLanguage = default, string category = default, bool? allowFallback = default, System.Threading.CancellationToken cancellationToken = default);
var response = client.DocumentTranslate("de", content);
Console.WriteLine($"Request string for translation: {requestString}");
Console.WriteLine($"Response string after translation: {responseString}");
}
catch (RequestFailedException exception) {
Console.WriteLine($"Error Code: {exception.ErrorCode}");
Console.WriteLine($"Message: {exception.Message}");
}
}
Ennyi az egész! Most hozott létre egy programot, amely a .NET-ügyfélkódtár használatával lefordítja a dokumentumokat egy tárolóban.
A projekt beállítása
Győződjön meg arról, hogy a Python legújabb verziója telepítve van.
Telepítse az ügyfélkódtárat
Telepítse a Dokumentumfordítás ügyfélkódtár legújabb verzióját:
pip install azure-ai-translation-document==1.1.0b1
Batch-fájlok fordítása
Ehhez a projekthez egy forrásdokumentumot kell feltöltenie a forrástárolóba. Ehhez a rövid útmutatóhoz letöltheti dokumentumfordítási mintadokumentumunkat. A forrásnyelv az angol.
A Python-alkalmazásfájlban hozzon létre változókat az erőforráskulcshoz és az egyéni végponthoz. További információ: A kulcs és az egyéni tartományvégpont lekérése.
key = "{your-api-key}"
endpoint = "{your-document-translation-endpoint}"
Inicializáljon egy
DocumentTranslationClient
objektumot, amely tartalmazza az Önendpoint
éskey
a paramétereket.Hívja meg a metódust
begin_translation
, és adja meg asourceUri
,targetUri
éstargetLanguageCode
paramétereket.A felügyelt identitás engedélyezéséhez hozza létre a következő változókat:
sourceUri. A lefordítandó dokumentumokat tartalmazó forrástároló URL-címe.
targetUri Annak a céltárolónak az URL-címe, amelyhez a lefordított dokumentumok meg vannak írva.
targetLanguageCode. A lefordított dokumentumok nyelvi kódja. A nyelvi kódokat a Nyelvi támogatási oldalon találja.
A forrás- és cél URL-címek megkereséséhez keresse meg a tárfiókot az Azure Portalon. A bal oldali oldalsáv Adattárolás területén válassza a Tárolók lehetőséget, és kövesse az alábbi lépéseket a forrásdokumentumok és a céltároló
URLS
lekéréséhez.Forrás Cél 1. Jelölje be a forrástároló melletti jelölőnégyzetet 1. Jelölje be a céltároló melletti jelölőnégyzetet. 2. A főablak területén válassza ki a fordításhoz szükséges fájlt vagy dokumentumokat. 2. Jelölje ki a jobb oldalon található három pontot, majd válassza a Tulajdonságok lehetőséget. 3. A forrás URL-címe a Tulajdonságok lista tetején található. 3. A cél URL-cím a Tulajdonságok lista tetején található.
A közös hozzáférésű jogosultságkód (SAS) engedélyezéséhez hozza létre ezeket a változókat
- sourceUri. Az SAS URI lekérdezési sztringként hozzáfűzött SAS-jogkivonattal a lefordítandó dokumentumokat tartalmazó forrástárolóhoz.
- targetUri Az SAS URI lekérdezési sztringként hozzáfűzött SAS-jogkivonattal ahhoz a céltárolóhoz, amelyhez a lefordított dokumentumok meg vannak írva.
- targetLanguageCode. A lefordított dokumentumok nyelvi kódja. A nyelvi kódokat a Nyelvi támogatási oldalon találja.
Aszinkron fordítási kódminta
Fontos
Ne felejtse el eltávolítani a kulcsot a kódból, amikor elkészült, és soha ne tegye közzé nyilvánosan. Éles környezetben biztonságos módon tárolhatja és érheti el a hitelesítő adatait, például az Azure Key Vaultot. További információ: Azure AI-szolgáltatások biztonsága.
Adja meg a következő kódmintát a Python-alkalmazásba:
# 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-api-key}'
endpoint = '{your-document-translation-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 asynchronous 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
)
)
Az alkalmazás futtatása
Miután hozzáadta a kódmintát az alkalmazáshoz, írja be a következő parancsot a terminálba:
python asynchronous-sdk.py
Íme egy kódrészlet a várt kimenetről:
Szinkron fordítási kódminta
Ehhez a rövid útmutatóhoz letöltheti dokumentumfordítási mintadokumentumunkat. A forrásnyelv az angol.
import os
from azure.core.credentials import AzureKeyCredential
from azure.ai.translation.document import SingleDocumentTranslationClient
from azure.ai.translation.document.models import DocumentTranslateContent
def sample_single_document_translation():
# create variables for your resource api key, document translation endpoint, and target language
key = "<your-api-key>"
endpoint = "<your-document-translation-endpoint>"
target_language = "{target-language-code}"
# initialize a new instance of the SingleDocumentTranslationClient object to interact with the synchronous Document Translation feature
client = SingleDocumentTranslationClient(endpoint, AzureKeyCredential(key))
# absolute path to your document
file_path = "C:/{your-file-path}/document-translation-sample.docx"
file_name = os.path.path.basename(file_path)
file_type = (
"application/vnd.openxmlformats-officedocument.wordprocessingml.document"
)
print(f"File for translation: {file_name}")
with open(file_name, "r") as file:
file_contents = file.read()
document_content = (file_name, file_contents, file_type)
document_translate_content = DocumentTranslateContent(document=document_content)
response_stream = client.document_translate(
body=document_translate_content, target_language=target_language
)
translated_response = response_stream.decode("utf-8-sig") # type: ignore[attr-defined]
print(f"Translated response: {translated_response}")
if __name__ == "__main__":
sample_single_document_translation()
Ennyi az egész! Most hozott létre egy programot a dokumentumok aszinkron és szinkron fordításához a Python-ügyfélkódtár használatával.