Compartir a través de

Biblioteca cliente de Azure Text Translation para .NET: versión 1.0.0-beta.1

  • Artículo

Text Translation es una característica de API REST basada en la nube del servicio Translator que usa la tecnología de traducción automática neuronal para permitir la traducción de texto de origen a destino rápida y precisa en tiempo real en todos los idiomas admitidos.

Use la biblioteca cliente de traducción de texto para .NET para:

  • Devuelve una lista de idiomas admitidos por las operaciones Translate, Transliterate y Dictionary.

  • Representar texto de un solo idioma de origen en varios textos de idioma de destino con una sola solicitud.

  • Convierta el texto de un idioma de origen en letras de un script diferente.

  • Devuelve palabras equivalentes para el término de origen en el idioma de destino.

  • Devuelve ejemplos de contexto y estructura gramatical para el término de origen y el par de términos de destino.

Código | fuente Documentación | de referencia de APIDocumentación del producto

Introducción

Instalar el paquete

Instale la biblioteca cliente de Azure Text Translation para .NET con NuGet:

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

En esta tabla se muestra la relación entre las versiones del SDK y las versiones de la API admitidas del servicio:

Versión del SDK Versión de la API admitidas del servicio
1.0.0-beta.1 3.0

Requisitos previos

Autenticar el cliente

La interacción con el servicio mediante la biblioteca cliente comienza con la creación de una instancia de la clase TextTranslationClient . Necesitará una clave de API o TokenCredential crear una instancia de un objeto de cliente. Para más información sobre la autenticación con Cognitive Services, consulte Autenticación de solicitudes en Translator Service.

Obtención de una clave de API

Puede obtener y desde el endpointAPI keyRegion recurso de Cognitive Services o la información de recursos del servicio Translator en Azure Portal.

Como alternativa, use el fragmento de código de la CLI de Azure siguiente para obtener la clave de API del recurso del servicio Translator.

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

Creación de mediante una TextTranslationClient clave de API y una credencial de región

Una vez que tenga el valor de la clave de API y región, cree un AzureKeyCredential. Esto le permitirá actualizar la clave de API sin crear un nuevo cliente.

Con el valor del punto de conexión AzureKeyCredential y un Region, puede crear TextTranslationClient:

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

Conceptos clave

TextTranslationClient

A TextTranslationClient es la interfaz principal para los desarrolladores que usan la biblioteca cliente de traducción de texto. Proporciona operaciones sincrónicas y asincrónicas para acceder a un uso específico del traductor de texto, como la detección de idiomas compatibles o la traducción de texto.

Entrada

Un elemento de texto (string), es una sola unidad de entrada que los modelos de traducción procesarán en el servicio Translator. Las operaciones en TextTranslationClient pueden tomar un único elemento de texto o una colección de elementos de texto. Para conocer los límites de longitud del elemento de texto, el tamaño máximo de las solicitudes y la codificación de texto admitidas, consulte aquí.

Valor devuelto

Los valores devueltos, como Response<IReadOnlyList<TranslatedTextItem>>, son el resultado de una operación de traducción de texto, contiene una matriz con un resultado para cada cadena de la matriz de entrada. El valor devuelto de una operación también puede incluir información opcional sobre el elemento de texto de entrada (por ejemplo, el idioma detectado).

Seguridad para subprocesos

Garantizamos que todos los métodos de instancia de cliente son seguros para subprocesos e independientes entre sí (instrucciones). Esto garantiza que la recomendación de reutilizar instancias de cliente siempre es segura, incluso entre subprocesos.

Conceptos adicionales

Opciones | de cliente Acceso a la respuesta | Operaciones | de larga duraciónControl de errores | Diagnóstico | Burla | Duración del cliente

Ejemplos

En la sección siguiente se proporcionan varios fragmentos de código con el clientcreado anteriormente y se tratan las características principales presentes en esta biblioteca cliente. Aunque la mayoría de los fragmentos de código siguientes usan llamadas de servicio asincrónicas, tenga en cuenta que el Azure.AI.Translation.Text paquete admite API sincrónicas y asincrónicas.

Obtener idiomas admitidos

Obtiene el conjunto de idiomas admitidos actualmente por otras operaciones de Traductor.

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 obtener ejemplos sobre el uso del languages punto de conexión, consulte más ejemplos aquí.

Consulte la documentación del servicio para obtener una explicación conceptual de los idiomas.

Translate

Traduce texto de un solo idioma de origen en textos en varios idiomas de destino con una sola solicitud.

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 obtener ejemplos sobre el uso del translate punto de conexión, consulte más ejemplos aquí.

Consulte la documentación del servicio para obtener una explicación conceptual de la traducción.

Transliterar

Convierte caracteres o letras de un idioma de origen en los caracteres o letras correspondientes de un 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 obtener ejemplos sobre el uso del transliterate punto de conexión, consulte más ejemplos aquí.

Consulte la documentación del servicio para obtener una explicación conceptual de la transliteración.

División de la oración

Identifica el posicionamiento de los límites de las oraciones en un fragmento de 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 obtener ejemplos sobre el uso del break sentece punto de conexión, consulte más ejemplos aquí.

Consulte la documentación del servicio para obtener una explicación conceptual de la frase de interrupción.

Búsqueda en diccionario

Devuelve palabras equivalentes del término de origen en el 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 obtener ejemplos sobre el uso del dictionary lookup punto de conexión, consulte más ejemplos aquí.

Consulte la documentación del servicio para obtener una explicación conceptual de la búsqueda de diccionarios.

Ejemplos de diccionario

Devuelve ejemplos de contexto y estructura gramatical para el término de origen y el par de términos 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 obtener ejemplos sobre el uso del dictionary examples punto de conexión, consulte más ejemplos aquí.

Consulte la documentación del servicio para obtener una explicación conceptual de los ejemplos de diccionario.

Solución de problemas

Al interactuar con el servicio Translator mediante la biblioteca cliente de traducción de texto, los errores devueltos por el servicio Translator corresponden a los mismos códigos de estado HTTP devueltos para las solicitudes de la API REST.

Por ejemplo, si envía una solicitud de traducción sin un idioma de traducción de destino, se devuelve un 400 error que indica "Solicitud incorrecta".

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

Observará que se registra información adicional, como el identificador de solicitud de cliente de la operación.

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

Configuración del registro de la consola

La manera más sencilla de ver los registros es habilitar el registro de la consola. Para crear un agente de escucha de registro del SDK de Azure que genere mensajes en la consola, use el método AzureEventSourceListener.CreateConsoleLogger.

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

Para más información sobre otros mecanismos de registro, consulte aquí.

Pasos siguientes

Los ejemplos que muestran cómo usar esta biblioteca cliente están disponibles en este repositorio de GitHub. Se proporcionan ejemplos para cada área funcional principal y, para cada área, se proporcionan muestras en modo sincronizado y asincrónico.

Contribuir

Consulte la CONTRIBUTING.md para obtener más información sobre la compilación, las pruebas y la contribución a esta biblioteca.

Este proyecto agradece las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia para el colaborador (CLA) que declara que tiene el derecho a concedernos y nos concede los derechos para usar su contribución. Para obtener más información, visite cla.microsoft.com.

Cuando se envía una solicitud de incorporación de cambios, un bot de CLA determinará de forma automática si tiene que aportar un CLA y completar la PR adecuadamente (por ejemplo, la etiqueta, el comentario). Solo siga las instrucciones que le dará el bot. Solo será necesario que lo haga una vez en todos los repositorios con nuestro CLA.

Este proyecto ha adoptado el Código de conducta de Microsoft Open Source. Para más información, consulte las preguntas más frecuentes del código de conducta o póngase en contacto con opencode@microsoft.com si tiene cualquier otra pregunta o comentario.