Inicio rápido: API de REST del Traductor de AI de Azure

Pruebe la última versión del Traductor de Azure AI. Si sigue este inicio rápido, podrá comenzar a usar el servicio Translator para traducir texto mediante un lenguaje de programación de su elección o la API de REST. Para este proyecto, se recomienda usar el plan de tarifa gratuito (F0), mientras se familiariza con la tecnología y, posteriormente, actualizarlo a un nivel de pago para producción.

Requisitos previos

Necesita una suscripción de Azure activa. Si no tiene una suscripción de Azure, puede crear una gratis.

• Cuando tenga la suscripción, cree un recurso de Translator en Azure Portal.

• Después de implementar el recurso, seleccione el botón Ir al recurso para obtener la clave y el punto de conexión.

  • Tanto la clave como el punto de conexión del recurso son necesarios para conectar la aplicación al servicio Translator. En una sección posterior de este mismo inicio rápido, va a pegar la clave y el punto de conexión en el código. Puede encontrar estos valores en la página Claves y punto de conexión de Azure Portal:

    

    Nota

    • Para esta guía de inicio rápido, se recomienda usar un recurso global de servicio único de Translator Text.
    • Con el recurso global de un solo servicio, incluirá un encabezado de autorización (Ocp-Apim-Subscription-key) con la solicitud de la API de REST. El valor de Ocp-Apim-Subscription-key es la clave secreta de Azure para la suscripción de Translator Text.
    • Si decide utilizar un recurso de Translator multiservicio o regional de Azure AI, se requerirán dos cabeceras de autenticación: (Ocp-Api-Subscription-Key y Ocp-Apim-Subscription-Region). El valor de Ocp-Apim-Subscription-Region es la región asociada a la suscripción.
    • Para más información sobre cómo utilizar el encabezado Ocp-Apim-Subscription-Region, consulteEncabezados de la API de REST de traducción de texto.

encabezados

Para llamar al servicio Translator a través de la API de REST, debe incluir los siguientes encabezados en cada solicitud. No se preocupe por el código de ejemplo para cada lenguaje de programación, ya que este ya incluye estos encabezados.

Para obtener más información sobre las opciones de autenticación para Translator, consulte la guía de referencia de Translator v3.

Encabezado	Value	Condición
Ocp-Apim-Subscription-Key	En este encabezado se incluye la clave de servicio de Translator de Azure Portal.	• Obligatorio
Ocp-Apim-Subscription-Region	La región donde se creó el recurso.	- Requerido cuando se utiliza un recurso multiservicio o regional (geográfico) de Azure AI como West US. - Opcional cuando se utiliza un Recurso de Traductor global de servicio único.
Content-Type	En este encabezado se especifica el tipo de contenido de la carga. Los valores que se aceptan son application/json o charset=UTF-8.	• Obligatorio
Content-Length	Este encabezado especifica la longitud del cuerpo de la solicitud.	• Opcional

Importante

Recuerde quitar la clave del código cuando haya terminado y no hacerla nunca pública. En el caso de producción, use una forma segura de almacenar sus credenciales y acceder a ellas, como Azure Key Vault. Para más información, consulte el artículo sobre seguridad de los servicios Azure AI.

Traducir texto

La operación básica del servicio Translator consiste en traducir texto. En este inicio rápido creará una solicitud, mediante un lenguaje de programación de su elección, que tome un único origen (from) y proporcione dos salidas (to). Luego, conocerá algunos parámetros que se pueden usar para ajustar tanto la solicitud como la respuesta.

Para obtener información detallada sobre los límites de solicitud del servicio de Traductor de Azure AI, veaLímites de solicitud de traducción de texto.

C#: Visual Studio

Configuración del proyecto de Visual Studio

1. Asegúrese de que tiene instalada la versión más reciente del IDE de Visual Studio.

   Sugerencia

   Si es la primera vez que usa Visual Studio, pruebe el módulo de Learn Introducción a Visual Studio.

2. Abra Visual Studio.

3. En la página Inicio, seleccione Crear un nuevo proyecto.

   

4. En la página Crear un proyecto, escriba consola en el cuadro de búsqueda. Elija la plantilla Aplicación de consola y, a continuación, seleccione Siguiente.

   

5. En la ventana de diálogo Configure su nuevo proyecto, escriba translator_quickstart en el cuadro Nombre de proyecto. Deje desactivada la casilla "Colocar la solución y el proyecto en el mismo directorio" y seleccione el botón Siguiente.

   

6. En la ventana de diálogo Información adicional, asegúrese de que esté seleccionado el elemento .NET 6.0 (compatibilidad a largo plazo). Deje la casilla "No usar instrucciones de nivel superior" desactivada y seleccione Crear.

   

Instalación del paquete Newtonsoft.json con NuGet

1. Haga clic con el botón derecho sobre el proyecto formRecognizer_quickstart y seleccione Administrar paquetes NuGet...

   

2. Seleccione la pestaña "Examinar" y escriba Newtonsoft.json.

   

3. Para agregar el paquete al proyecto, seleccione Instalar en la ventana del administrador de paquetes derecha.

   

Compilación de la aplicación de C#

Nota

• A partir de .NET 6, los nuevos proyectos que usan la plantilla console generan un nuevo estilo de programa que difiere de las versiones anteriores.
• El nuevo tipo de salida usa características recientes de C# que simplifican el código que debe escribir.
• Cuando se usa la versión más reciente, solo es necesario escribir el cuerpo del método Main. Es decir, no es necesario incluir instrucciones de nivel superior, directivas Using globales o directivas Using implícitas.
• Para obtener más información, consulte Las nuevas plantillas de C# generan instrucciones de nivel superior.

1. Abra el archivo Program.cs.

2. Elimine el código preexistente, incluida la línea Console.WriteLine("Hello World!"). Copie y pegue el código de ejemplo en el archivo Program.cs de la aplicación. Asegúrese de actualizar la variable de clave con el valor correspondiente de la instancia de Translator de Azure Portal:

using System.Text;
using Newtonsoft.Json;

class Program
{
    private static readonly string key = "<your-translator-key>";
    private static readonly string endpoint = "https://api.cognitive.microsofttranslator.com";

    // location, also known as region.
    // required if you're using a multi-service or regional (not global) resource. It can be found in the Azure portal on the Keys and Endpoint page.
    private static readonly string location = "<YOUR-RESOURCE-LOCATION>";

    static async Task Main(string[] args)
    {
        // Input and output languages are defined as parameters.
        string route = "/translate?api-version=3.0&from=en&to=fr&to=zu";
        string textToTranslate = "I would really like to drive your car around the block a few times!";
        object[] body = new object[] { new { Text = textToTranslate } };
        var requestBody = JsonConvert.SerializeObject(body);

        using (var client = new HttpClient())
        using (var request = new HttpRequestMessage())
        {
            // Build the request.
            request.Method = HttpMethod.Post;
            request.RequestUri = new Uri(endpoint + route);
            request.Content = new StringContent(requestBody, Encoding.UTF8, "application/json");
            request.Headers.Add("Ocp-Apim-Subscription-Key", key);
            // location required if you're using a multi-service or regional (not global) resource.
            request.Headers.Add("Ocp-Apim-Subscription-Region", location);

            // Send the request and get response.
            HttpResponseMessage response = await client.SendAsync(request).ConfigureAwait(false);
            // Read response as a string.
            string result = await response.Content.ReadAsStringAsync();
            Console.WriteLine(result);
        }
    }
}

Ejecute la aplicación C#

Una vez que agregue una muestra de código a su aplicación, elija el botón Iniciar verde junto a formRecognizer_quickstart para crear y ejecutar su programa, o pulse F5.

Salida del servicio Translation:

Si realiza una llamada correcta, debería ver la siguiente respuesta:

[
    {
        "detectedLanguage": {
            "language": "en",
            "score": 1.0
        },
        "translations": [
            {
                "text": "J'aimerais vraiment conduire votre voiture autour du pâté de maisons plusieurs fois!",
                "to": "fr"
            },
            {
                "text": "Ngingathanda ngempela ukushayela imoto yakho endaweni evimbelayo izikhathi ezimbalwa!",
                "to": "zu"
            }
        ]
    }
]

Go

Configure el entorno de Go

Puede usar cualquier editor de texto para escribir aplicaciones de Go. Se recomienda usar la versión más reciente de Visual Studio Code y la extensión Go.

Sugerencia

Si es la primera vez que usa Go, pruebe el módulo de Learn Introducción a Go.

1. Asegúrese de que está instalada la versión más reciente de Go:

   • Descargue la versión del Go lenguaje de programación para el sistema operativo.

   • Cuando se haya completado la descarga, ejecute el instalador.

   • Abra un símbolo del sistema e introduzca el siguiente comando para confirmar que Go esté instalado:

       go version
     

Compilación de la aplicación de Go

1. En una ventana de consola (como CMD, PowerShell o Bash), cree un nuevo directorio para la aplicación que se llame translator-app y vaya hasta él.

2. Cree un nuevo archivo Go denominado translation.go desde el directorio translator-app.

3. Copie y pegue el código de ejemplo que se proporciona a continuación en el archivo translation.go. Asegúrese de actualizar la variable de clave con el valor correspondiente de la instancia de Translator de Azure Portal:

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "log"
    "net/http"
    "net/url"
)

func main() {
    key := "<YOUR-TRANSLATOR-KEY>"
    endpoint := "https://api.cognitive.microsofttranslator.com/"
    uri := endpoint + "/translate?api-version=3.0"

    // location, also known as region.
    // required if you're using a multi-service or regional (not global) resource. It can be found in the Azure portal on the Keys and Endpoint page.
    location := "<YOUR-RESOURCE-LOCATION>"

    // Build the request URL. See: https://go.dev/pkg/net/url/#example_URL_Parse
    u, _ := url.Parse(uri)
    q := u.Query()
    q.Add("from", "en")
    q.Add("to", "fr")
    q.Add("to", "zu")
    u.RawQuery = q.Encode()

    // Create an anonymous struct for your request body and encode it to JSON
    body := []struct {
        Text string
    }{
        {Text: "I would really like to drive your car around the block a few times."},
    }
    b, _ := json.Marshal(body)

    // Build the HTTP POST request
    req, err := http.NewRequest("POST", u.String(), bytes.NewBuffer(b))
    if err != nil {
        log.Fatal(err)
    }
    // Add required headers to the request
    req.Header.Add("Ocp-Apim-Subscription-Key", key)
    // location required if you're using a multi-service or regional (not global) resource.
    req.Header.Add("Ocp-Apim-Subscription-Region", location)
    req.Header.Add("Content-Type", "application/json")

    // Call the Translator API
    res, err := http.DefaultClient.Do(req)
    if err != nil {
        log.Fatal(err)
    }

    // Decode the JSON response
    var result interface{}
    if err := json.NewDecoder(res.Body).Decode(&result); err != nil {
        log.Fatal(err)
    }
    // Format and print the response to terminal
    prettyJSON, _ := json.MarshalIndent(result, "", "  ")
    fmt.Printf("%s\n", prettyJSON)
}

Ejecute la aplicación Go

Una vez que agregue un código de ejemplo a la aplicación, el programa Go se podrá ejecutar mediante un símbolo del sistema o terminal. Asegúrese de que la ruta de acceso del símbolo del sistema esté establecida en la carpeta translator-app y use el siguiente comando:

 go run translation.go

Salida del servicio Translation:

Si realiza una llamada correcta, debería ver la siguiente respuesta:

[
    {
        "detectedLanguage": {
            "language": "en",
            "score": 1.0
        },
        "translations": [
            {
                "text": "J'aimerais vraiment conduire votre voiture autour du pâté de maisons plusieurs fois!",
                "to": "fr"
            },
            {
                "text": "Ngingathanda ngempela ukushayela imoto yakho endaweni evimbelayo izikhathi ezimbalwa!",
                "to": "zu"
            }
        ]
    }
]

Java: Gradle

Configuración del entorno Java

• Debe tener instalada la versión más reciente de Visual Studio Code o del IDE que prefiera usar. Consulte Java en Visual Studio Code.

  Sugerencia

  • Visual Studio Code ofrece un paquete de codificación para Java para Windows y macOS. El paquete de codificación es un conjunto de VS Code, el Kit de desarrollo de Java (JDK) y una colección de extensiones sugeridas por Microsoft. El paquete de codificación también se puede usar para corregir un entorno de desarrollo existente.
  • Si usa VS Code y el paquete de codificación para Java, instale la extensión Gradle para Java.

• Si no usa Visual Studio Code, asegúrese de que tiene lo siguiente instalado en el entorno de desarrollo:

  • Java Development Kit (OpenJDK) en versión 8 o posterior.

  • Gradle, versión 6.8 o posterior.

Creación de un proyecto de Gradle

1. En una ventana de consola (como CMD, PowerShell o Bash), cree un nuevo directorio para la aplicación que se llame translator-text-app y vaya hasta él.

   mkdir translator-text-app && translator-text-app
   

    mkdir translator-text-app; cd translator-text-app
   

2. Ejecute el comando gradle init desde el directorio translator-text-app. Este comando crea archivos de compilación esenciales para Gradle, como build.gradle.kts, que se usa en el runtime para crear y configurar la aplicación.

   gradle init --type basic
   

3. Cuando se le solicite que elija un DSL, seleccione Kotlin.

4. Acepte el nombre predeterminado del proyecto (translator-text-app). Para ello, presione la tecla INTRO o ENTRAR.

5. Actualice build.gradle.kts con el siguiente código:

plugins {
  java
  application
}
application {
  mainClass.set("TranslatorText")
}
repositories {
  mavenCentral()
}
dependencies {
  implementation("com.squareup.okhttp3:okhttp:4.10.0")
  implementation("com.google.code.gson:gson:2.9.0")
}

Creación de una aplicación de Java

1. En el directorio translator-text-app, ejecute el siguiente comando:

   mkdir -p src/main/java
   

   Va a crear la estructura de directorios siguiente:

   

2. Vaya al directorio java y cree un archivo denominado TranslatorText.java.

   Sugerencia

   • Puede crear un nuevo archivo mediante PowerShell.

   • Abra una ventana de PowerShell en el directorio del proyecto. Para ello, mantenga presionada la tecla Mayús y haga clic con el botón derecho en la carpeta.

   • Escriba el siguiente comando: New-Item TranslatorText.java.

   • También puede crear un nuevo archivo en el IDE que se llame TranslatorText.java y guardarlo en el directorio java.

3. Abra el archivo TranslatorText.java en el IDE y copie el siguientes código de ejemplo para pegarlo en la aplicación. Asegúrese de actualizar la variable de clave con el valor correspondiente de la instancia de Translator de Azure Portal:

import java.io.IOException;

import com.google.gson.*;
import okhttp3.MediaType;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;

public class TranslatorText {
    private static String key = "<your-translator-key";

    // location, also known as region.
   // required if you're using a multi-service or regional (not global) resource. It can be found in the Azure portal on the Keys and Endpoint page.
    private static String location = "<YOUR-RESOURCE-LOCATION>";


    // Instantiates the OkHttpClient.
    OkHttpClient client = new OkHttpClient();

    // This function performs a POST request.
    public String Post() throws IOException {
        MediaType mediaType = MediaType.parse("application/json");
        RequestBody body = RequestBody.create(mediaType,
                "[{\"Text\": \"I would really like to drive your car around the block a few times!\"}]");
        Request request = new Request.Builder()
                .url("https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=fr&to=zu")
                .post(body)
                .addHeader("Ocp-Apim-Subscription-Key", key)
                // location required if you're using a multi-service or regional (not global) resource.
                .addHeader("Ocp-Apim-Subscription-Region", location)
                .addHeader("Content-type", "application/json")
                .build();
        Response response = client.newCall(request).execute();
        return response.body().string();
    }

    // This function prettifies the json response.
    public static String prettify(String json_text) {
        JsonParser parser = new JsonParser();
        JsonElement json = parser.parse(json_text);
        Gson gson = new GsonBuilder().setPrettyPrinting().create();
        return gson.toJson(json);
    }

    public static void main(String[] args) {
        try {
            TranslatorText translateRequest = new TranslatorText();
            String response = translateRequest.Post();
            System.out.println(prettify(response));
        } catch (Exception e) {
            System.out.println(e);
        }
    }
}

Compilación y ejecución de la aplicación de Java

Una vez que agregue un código de ejemplo a la aplicación, vuelva al directorio principal del proyecto: translator-text-app. A continuación, abra una ventana de consola e introduzca los siguientes comandos:

1. Compile la aplicación con el comando build:

   gradle build
   

2. Ejecute la aplicación con el comando run:

   gradle run
   

Salida del servicio Translation:

Si realiza una llamada correcta, debería ver la siguiente respuesta:

[
  {
    "translations": [
      {
        "text": "J'aimerais vraiment conduire votre voiture autour du pâté de maisons plusieurs fois!",
        "to": "fr"
      },
      {
        "text": "Ngingathanda ngempela ukushayela imoto yakho endaweni evimbelayo izikhathi ezimbalwa!",
        "to": "zu"
      }
    ]
  }
]

JavaScript: Node.js

Configuración del proyecto de Node.js Express

1. Asegúrese de que está instalada la versión más reciente de Node.js. La instalación de Node.js incluye el administrador de paquetes de nodos (npm).

   Sugerencia

   Si es la primera vez que usa Node.js, pruebe el módulo de Learn Introducción a Node.js.

2. En una ventana de consola (como CMD, PowerShell o Bash), cree un directorio para la aplicación que se llame translator-app y vaya a él.

       mkdir translator-app && cd translator-app
   

     mkdir translator-app; cd translator-app
   

3. Ejecute el comando "npm init" para inicializar la aplicación y aplicar la técnica scaffolding al proyecto.

      npm init
   

4. Especifique los atributos del proyecto mediante las indicaciones que se presentan en el terminal.

   • Los atributos más importantes son el nombre, el número de versión y el punto de entrada.
   • Se recomienda mantener index.js para el nombre del punto de entrada. La descripción, el comando de prueba, el repositorio de GitHub, las palabras clave, el autor y la información de la licencia son atributos opcionales; se pueden omitir para este proyecto.
   • Acepte las sugerencias entre paréntesis seleccionando Retorno o Entrar.
   • Después de completar las solicitudes, se creará un archivo package.json en el directorio translator-app.

5. Abra una ventana de consola y use el comando npm para instalar la biblioteca HTTP axios y el paquete uuid:

      npm install axios uuid
   

6. Cree el archivo index.js en el directorio de la aplicación.

   Sugerencia

   • Puede crear un nuevo archivo mediante PowerShell.

   • Abra una ventana de PowerShell en el directorio del proyecto. Para ello, mantenga presionada la tecla Mayús y haga clic con el botón derecho en la carpeta.

   • Escriba el siguiente comando New-Item index.js.

   • También puede crear un nuevo archivo en el IDE que se llame index.js y guardarlo en el directorio translator-app.

Compilación de la aplicación de JavaScript

Agregue el siguiente código de ejemplo al archivo index.js. Asegúrese de actualizar la variable de clave con el valor correspondiente de la instancia de Translator de Azure Portal:

    const axios = require('axios').default;
    const { v4: uuidv4 } = require('uuid');

    let key = "<your-translator-key>";
    let endpoint = "https://api.cognitive.microsofttranslator.com";

    // location, also known as region.
    // required if you're using a multi-service or regional (not global) resource. It can be found in the Azure portal on the Keys and Endpoint page.
    let location = "<YOUR-RESOURCE-LOCATION>";

    axios({
        baseURL: endpoint,
        url: '/translate',
        method: 'post',
        headers: {
            'Ocp-Apim-Subscription-Key': key,
             // location required if you're using a multi-service or regional (not global) resource.
            'Ocp-Apim-Subscription-Region': location,
            'Content-type': 'application/json',
            'X-ClientTraceId': uuidv4().toString()
        },
        params: {
            'api-version': '3.0',
            'from': 'en',
            'to': 'fr,zu'
        },
        data: [{
            'text': 'I would really like to drive your car around the block a few times!'
        }],
        responseType: 'json'
    }).then(function(response){
        console.log(JSON.stringify(response.data, null, 4));
    })

Ejecución de la aplicación de JavaScript

Una vez que agregue un código de ejemplo a la aplicación, ejecute el programa de la siguiente forma:

1. Vaya al directorio de la aplicación (translator-app).

2. Escriba el siguiente comando en el terminal:

   node index.js
   

Salida del servicio Translation:

Si realiza una llamada correcta, debería ver la siguiente respuesta:

[
    {
        "translations": [
            {
                "text": "J'aimerais vraiment conduire votre voiture autour du pâté de maisons plusieurs fois!",
                "to": "fr"
            },
            {
                "text": "Ngingathanda ngempela ukushayela imoto yakho endaweni evimbelayo izikhathi ezimbalwa!",
                "to": "zu"
            }
        ]
    }
]

Python

Configuración del proyecto de Python

1. Asegúrese de que está instalada la versión más reciente de Python 3.x. La instalación de Python incluye el paquete del instalador de Python (pip).

   Sugerencia

   Si es la primera vez que usa Python, pruebe el módulo de Learn Introducción a Python.

2. Abra una ventana de terminal y use el comando pip para instalar la biblioteca de solicitudes y el paquete uuid0:

      pip install requests uuid
   

   Nota

   También usaremos un paquete integrado de Python denominado json. Este se usa para trabajar con datos JSON.

Compilación de la aplicación de Python

1. Cree un archivo Python que se llame translator-app.py en el editor o IDE que prefiera usar.

2. Agregue el siguiente código de ejemplo al archivo translator-app.py. Asegúrese de actualizar la variable de clave con el valor correspondiente de la instancia de Translator de Azure Portal.

import requests, uuid, json

# Add your key and endpoint
key = "<your-translator-key>"
endpoint = "https://api.cognitive.microsofttranslator.com"

# location, also known as region.
# required if you're using a multi-service or regional (not global) resource. It can be found in the Azure portal on the Keys and Endpoint page.
location = "<YOUR-RESOURCE-LOCATION>"

path = '/translate'
constructed_url = endpoint + path

params = {
    'api-version': '3.0',
    'from': 'en',
    'to': ['fr', 'zu']
}

headers = {
    'Ocp-Apim-Subscription-Key': key,
    # location required if you're using a multi-service or regional (not global) resource.
    'Ocp-Apim-Subscription-Region': location,
    'Content-type': 'application/json',
    'X-ClientTraceId': str(uuid.uuid4())
}

# You can pass more than one object in body.
body = [{
    'text': 'I would really like to drive your car around the block a few times!'
}]

request = requests.post(constructed_url, params=params, headers=headers, json=body)
response = request.json()

print(json.dumps(response, sort_keys=True, ensure_ascii=False, indent=4, separators=(',', ': ')))

Ejecución de la aplicación de Python

Una vez agregado un ejemplo de código a la aplicación, compile y ejecute el programa:

1. Vaya al archivo translator-app.py.

2. Escriba el siguiente comando en la ventana de consola:

   python translator-app.py
   

Salida del servicio Translation:

Si realiza una llamada correcta, debería ver la siguiente respuesta:

[
  {
    "translations": [
      {
        "text": "J'aimerais vraiment conduire votre voiture autour du pâté de maisons plusieurs fois!",
        "to": "fr"
      },
      {
        "text": "Ngingathanda ngempela ukushayela imoto yakho endaweni evimbelayo izikhathi ezimbalwa!",
        "to": "zu"
      }
    ]
  }
]

Pasos siguientes

Eso es todo, ¡enhorabuena! Acaba de aprender cómo usar el servicio Translator para traducir texto.

Explore nuestra documentación paso a paso y profundice en las funcionalidades del servicio Translator:

• Traducción de texto

• Transliteración de texto

• Detección e identificación del idioma

• Obtención de la longitud de las frases

• Búsqueda en el diccionario y traducciones alternativas