Biblioteca de clientes de Tradução de Texto do Azure para .NET – versão 1.0.0-beta.1

  • Artigo

A Tradução de Texto é um recurso da API REST baseada em nuvem do serviço Tradutor que usa a tecnologia de tradução automática neural para permitir tradução rápida e precisa de texto de origem para destino em tempo real em todos os idiomas compatíveis.

Use a biblioteca de clientes de Tradução de Texto para .NET para:

  • Retornar uma lista de idiomas compatíveis com as operações Traduzir, Transliteratar e Dicionário.

  • Renderize texto de idioma de origem único em vários textos de linguagem de destino com uma única solicitação.

  • Converter texto de um idioma de origem em letras de um script diferente.

  • Retornar palavras equivalentes para o termo de origem no idioma de destino.

  • Retornar exemplos de contexto e estrutura gramatical para o termo de origem e o par de termos de destino.

Código-fonte | Documentação | de referência da APIDocumentação do produto

Introdução

Instalar o pacote

Instale a biblioteca de clientes de Tradução de Texto do Azure para .NET com o NuGet:

dotnet add package Azure.AI.Translation.Text --prerelease

Esta tabela mostra a relação entre as versões do SDK e as versões de API com suporte do serviço:

Versão do SDK Versão da API do serviço com suporte
1.0.0-beta.1 3.0

Pré-requisitos

Autenticar o cliente

A interação com o serviço que usa a biblioteca de clientes começa com a criação de uma instância da classe TextTranslationClient . Você precisará de uma chave de API ou TokenCredential de instanciar um objeto cliente. Para obter mais informações sobre como autenticar com os Serviços Cognitivos, consulte Autenticar solicitações para o Serviço de Tradução.

Obter uma chave de API

Você pode obter as endpointinformações do recurso e API keyRegion dos Serviços Cognitivos ou do recurso de serviço tradutor no Portal do Azure.

Como alternativa, use o snippet da CLI do Azure abaixo para obter a chave de API do recurso de serviço tradutor.

az cognitiveservices account keys list --resource-group <your-resource-group-name> --name <your-resource-name>

Criar um TextTranslationClient usando uma chave de API e uma credencial de região

Depois de ter o valor da chave de API e região, crie um AzureKeyCredential. Isso permitirá que você atualize a chave de API sem criar um novo cliente.

Com o valor do ponto AzureKeyCredential de extremidade e um Region, você pode criar o TextTranslationClient:

AzureKeyCredential credential = new("<apiKey>");
TextTranslationClient client = new(credential, "<region>");

Principais conceitos

TextTranslationClient

Um TextTranslationClient é a interface principal para desenvolvedores que usam a biblioteca de clientes de Tradução de Texto. Ele fornece operações síncronas e assíncronas para acessar um uso específico do tradutor de texto, como obter detecção de idiomas com suporte ou tradução de texto.

Entrada

Um elemento de texto (string) é uma única unidade de entrada a ser processada pelos modelos de tradução no serviço tradutor. As operações em TextTranslationClient podem ter um único elemento de texto ou uma coleção de elementos de texto. Para limites de comprimento do elemento de texto, tamanho máximo de solicitações e codificação de texto com suporte, consulte aqui.

Retornar valor

Os valores retornados, como Response<IReadOnlyList<TranslatedTextItem>>, são o resultado de uma operação de Conversão de Texto, ela contém matriz com um resultado para cada cadeia de caracteres na matriz de entrada. O valor retornado de uma operação também pode incluir, opcionalmente, informações sobre o elemento de texto de entrada (por exemplo, idioma detectado).

Acesso thread-safe

Garantimos que todos os métodos de instância do cliente sejam thread-safe e independentes uns dos outros (diretriz). Isso garante que a recomendação de reutilize instâncias de cliente seja sempre segura, mesmo entre threads.

Conceitos adicionais

Opções | do cliente Acessando a resposta | Operações de execução prolongada | Tratamento de falhas | Diagnostics | Zombando | Tempo de vida do cliente

Exemplos

A seção a seguir fornece vários snippets de código usando o clientcriado acima e aborda os main recursos presentes nesta biblioteca de clientes. Embora a maioria dos snippets abaixo usem chamadas de serviço assíncronas, tenha em mente que o Azure.AI.Translation.Text pacote dá suporte a APIs síncronas e assíncronas.

Obter idiomas com suporte

Obtém o conjunto de idiomas atualmente compatíveis com outras operações do Tradutor.

try
{
    Response<GetLanguagesResult> response = await client.GetLanguagesAsync(cancellationToken: CancellationToken.None).ConfigureAwait(false);
    GetLanguagesResult languages = response.Value;

    Console.WriteLine($"Number of supported languages for translate operations: {languages.Translation.Count}.");
}
catch (RequestFailedException exception)
{
    Console.WriteLine($"Error Code: {exception.ErrorCode}");
    Console.WriteLine($"Message: {exception.Message}");
}

Para obter exemplos sobre como usar o languages ponto de extremidade, consulte mais exemplos aqui.

Consulte a documentação do serviço para obter uma discussão conceitual sobre idiomas.

Translate

Renderiza um texto de idioma de origem para vários textos de idioma de destino com apenas uma solicitação.

try
{
    string targetLanguage = "cs";
    string inputText = "This is a test.";

    Response<IReadOnlyList<TranslatedTextItem>> response = await client.TranslateAsync(targetLanguage, inputText).ConfigureAwait(false);
    IReadOnlyList<TranslatedTextItem> translations = response.Value;
    TranslatedTextItem translation = translations.FirstOrDefault();

    Console.WriteLine($"Detected languages of the input text: {translation?.DetectedLanguage?.Language} with score: {translation?.DetectedLanguage?.Score}.");
    Console.WriteLine($"Text was translated to: '{translation?.Translations?.FirstOrDefault().To}' and the result is: '{translation?.Translations?.FirstOrDefault()?.Text}'.");
}
catch (RequestFailedException exception)
{
    Console.WriteLine($"Error Code: {exception.ErrorCode}");
    Console.WriteLine($"Message: {exception.Message}");
}

Para obter exemplos sobre como usar o translate ponto de extremidade, consulte mais exemplos aqui.

Consulte a documentação do serviço para obter uma discussão conceitual sobre tradução.

Transliterate

Converte caracteres ou letras de um idioma de origem nos caracteres ou letras correspondentes de um idioma de destino.

try
{
    string language = "zh-Hans";
    string fromScript = "Hans";
    string toScript = "Latn";

    string inputText = "这是个测试。";

    Response<IReadOnlyList<TransliteratedText>> response = await client.TransliterateAsync(language, fromScript, toScript, inputText).ConfigureAwait(false);
    IReadOnlyList<TransliteratedText> transliterations = response.Value;
    TransliteratedText transliteration = transliterations.FirstOrDefault();

    Console.WriteLine($"Input text was transliterated to '{transliteration?.Script}' script. Transliterated text: '{transliteration?.Text}'.");
}
catch (RequestFailedException exception)
{
    Console.WriteLine($"Error Code: {exception.ErrorCode}");
    Console.WriteLine($"Message: {exception.Message}");
}

Para obter exemplos sobre como usar o transliterate ponto de extremidade, consulte mais exemplos aqui.

Consulte a documentação do serviço para obter uma discussão conceitual sobre transliteração.

Interromper a frase

Identifica o posicionamento dos limites de frase em uma parte do texto.

try
{
    string inputText = "How are you? I am fine. What did you do today?";

    Response<IReadOnlyList<BreakSentenceItem>> response = await client.FindSentenceBoundariesAsync(inputText).ConfigureAwait(false);
    IReadOnlyList<BreakSentenceItem> brokenSentences = response.Value;
    BreakSentenceItem brokenSentence = brokenSentences.FirstOrDefault();

    Console.WriteLine($"Detected languages of the input text: {brokenSentence?.DetectedLanguage?.Language} with score: {brokenSentence?.DetectedLanguage?.Score}.");
    Console.WriteLine($"The detected sentece boundaries: '{string.Join(",", brokenSentence?.SentLen)}'.");

}
catch (RequestFailedException exception)
{
    Console.WriteLine($"Error Code: {exception.ErrorCode}");
    Console.WriteLine($"Message: {exception.Message}");
}

Para obter exemplos sobre como usar o break sentece ponto de extremidade, consulte mais exemplos aqui.

Consulte a documentação do serviço para obter uma discussão conceitual sobre a frase de interrupção.

Pesquisa no dicionário

Retorna palavras equivalentes para o termo de origem no idioma de destino.

try
{
    string sourceLanguage = "en";
    string targetLanguage = "es";
    string inputText = "fly";

    Response<IReadOnlyList<DictionaryLookupItem>> response = await client.LookupDictionaryEntriesAsync(sourceLanguage, targetLanguage, inputText).ConfigureAwait(false);
    IReadOnlyList<DictionaryLookupItem> dictionaryEntries = response.Value;
    DictionaryLookupItem dictionaryEntry = dictionaryEntries.FirstOrDefault();

    Console.WriteLine($"For the given input {dictionaryEntry?.Translations?.Count} entries were found in the dictionary.");
    Console.WriteLine($"First entry: '{dictionaryEntry?.Translations?.FirstOrDefault()?.DisplayTarget}', confidence: {dictionaryEntry?.Translations?.FirstOrDefault()?.Confidence}.");

}
catch (RequestFailedException exception)
{
    Console.WriteLine($"Error Code: {exception.ErrorCode}");
    Console.WriteLine($"Message: {exception.Message}");
}

Para obter exemplos sobre como usar o dictionary lookup ponto de extremidade, consulte mais exemplos aqui.

Consulte a documentação do serviço para obter uma discussão conceitual sobre a pesquisa de dicionário.

Exemplos de dicionário

Retorna exemplos de contexto e estrutura gramatical para o termo de origem e o par de termos de destino.

try
{
    string sourceLanguage = "en";
    string targetLanguage = "es";
    IEnumerable<InputTextWithTranslation> inputTextElements = new[]
    {
        new InputTextWithTranslation("fly", "volar")
    };

    Response<IReadOnlyList<DictionaryExampleItem>> response = await client.LookupDictionaryExamplesAsync(sourceLanguage, targetLanguage, inputTextElements).ConfigureAwait(false);
    IReadOnlyList<DictionaryExampleItem> dictionaryEntries = response.Value;
    DictionaryExampleItem dictionaryEntry = dictionaryEntries.FirstOrDefault();

    Console.WriteLine($"For the given input {dictionaryEntry?.Examples?.Count} examples were found in the dictionary.");
    DictionaryExample firstExample = dictionaryEntry?.Examples?.FirstOrDefault();
    Console.WriteLine($"Example: '{string.Concat(firstExample.TargetPrefix, firstExample.TargetTerm, firstExample.TargetSuffix)}'.");

}
catch (RequestFailedException exception)
{
    Console.WriteLine($"Error Code: {exception.ErrorCode}");
    Console.WriteLine($"Message: {exception.Message}");
}

Para obter exemplos sobre como usar o dictionary examples ponto de extremidade, consulte mais exemplos aqui.

Consulte a documentação do serviço para obter uma discussão conceitual sobre exemplos de dicionário.

Solução de problemas

Quando você interage com o Serviço de Tradução usando a biblioteca de clientes de Tradução de Texto, os erros retornados pelo serviço tradutor correspondem aos mesmos códigos http status retornados para solicitações da API REST.

Por exemplo, se você enviar uma solicitação de tradução sem um idioma de tradução de destino, um 400 erro será retornado, indicando "Solicitação Incorreta".

try
{
    var translation = client.TranslateAsync(Array.Empty<string>(), new[] { new InputText { Text = "This is a Test" } }).ConfigureAwait(false);
}
catch (RequestFailedException e)
{
    Console.WriteLine(e.ToString());
}

Você observará que informações adicionais são registradas, como a ID de solicitação do cliente da operação.

Message:
    Azure.RequestFailedException: Service request failed.
    Status: 400 (Bad Request)

Content:
    {"error":{"code":400036,"message":"The target language is not valid."}}

Headers:
    X-RequestId: REDACTED
    Access-Control-Expose-Headers: REDACTED
    X-Content-Type-Options: REDACTED
    Strict-Transport-Security: REDACTED
    Date: Mon, 27 Feb 2023 23:31:37 GMT
    Content-Type: text/plain; charset=utf-8
    Content-Length: 71

Configuração do registro em log do console

A maneira mais simples de ver os logs é habilitar o log do console. Para criar um ouvinte de log do SDK do Azure que gera mensagens para o console, use o método AzureEventSourceListener.CreateConsoleLogger.

// Setup a listener to monitor logged events.
using AzureEventSourceListener listener = AzureEventSourceListener.CreateConsoleLogger();

Para saber mais sobre outros mecanismos de registro em log, confira aqui.

Próximas etapas

Exemplos que mostram como usar essa biblioteca de clientes estão disponíveis neste repositório GitHub. Os exemplos são fornecidos para cada main área funcional e, para cada área, os exemplos são fornecidos no modo de sincronização e assíncrono.

Participante

Consulte o CONTRIBUTING.md para obter detalhes sobre como criar, testar e contribuir para essa biblioteca.

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder, e de fato concede, os direitos de usar sua contribuição. Para obter detalhes, visite cla.microsoft.com.

Quando você envia uma solicitação de pull, um bot do CLA determina automaticamente se você precisa fornecer um CLA e preencher a PR corretamente (por exemplo, rótulo, comentário). Basta seguir as instruções fornecidas pelo bot. Você só precisará fazer isso uma vez em todos os repositórios que usam nosso CLA.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, confira as Perguntas frequentes sobre o Código de Conduta ou contate opencode@microsoft.com para enviar outras perguntas ou comentários.