Compartir vía

Traductor 3.0: Translate

  • Artículo

Traduce el texto.

URL de la solicitud

Envíe una solicitud POST a:

https://api.cognitive.microsofttranslator.com/translate?api-version=3.0

Consulte Compatibilidad de red virtual con el servicio Translator seleccionado para la configuración y el soporte técnico de la red privada y el punto de conexión privado.

Parámetros de solicitud

Los parámetros de solicitud que se pasaron en la cadena de consulta son:

Parámetros obligatorios

Parámetro de consulta Descripción
api-version Parámetro obligatorio.
Versión de la API que el cliente solicitó. El valor debe ser 3.0.
to Parámetro obligatorio.
Especifica el idioma del texto de salida. El idioma de destino debe ser uno de los idiomas admitidos que están incluidos en el ámbito translation. Por ejemplo, utilice to=de para traducir al alemán.
Es posible traducir a varios idiomas simultáneamente mediante la repetición del parámetro en la cadena de consulta. Por ejemplo, utilice to=de&to=it para traducir al alemán e italiano.

Parámetros opcionales

Parámetro de consulta Descripción
desde Parámetro opcional.
Especifica el idioma del texto de entrada. Busque los idiomas que están disponibles desde los que realizar la traducción mediante la busca de idiomas admitidos con el ámbito translation. Si no se ha especificado el parámetro from, se aplica la detección de idioma automática para determinar el idioma de origen.

Debe usar el parámetro from en lugar de la detección automática cuando use la característica de diccionario dinámico. Nota: La característica de diccionario dinámico distingue mayúsculas de minúsculas.
textType Parámetro opcional.
Define si el texto que se está traduciendo es texto sin formato o texto HTML. El código HTML debe ser un elemento completo y bien formado. Los valores posibles son plain (valor predeterminado) o html.
category Parámetro opcional.
Una cadena que especifica la categoría (dominio) de la traducción. Este parámetro se utiliza para obtener las traducciones de un sistema personalizado creado con Custom Translator. Para usar el sistema personalizado implementado, agregue el identificador de categoría de los detalles del proyecto de Custom Translator al parámetro category. El valor predeterminado es general.
profanityAction Parámetro opcional.
Especifica cómo se deben tratar las palabras soeces en las traducciones. Los valores posibles son: NoAction (valor predeterminado), Markedo Deleted. Para entender las maneras de tratar las palabras soeces, consulte Control de palabras soeces.
profanityMarker Parámetro opcional.
Especifica cómo deben marcarse las palabras soeces en las traducciones. Los valores posibles son Asterisk (valor predeterminado) o Tag. Para entender las maneras de tratar las palabras soeces, consulte Control de palabras soeces.
includeAlignment Parámetro opcional.
Especifica si se debe incluir la proyección de la alineación del texto de origen en el texto traducido. Los valores posibles son true o false (valor predeterminado).
includeSentenceLength Parámetro opcional.
Especifica si se deben incluir los límites de oraciones del texto de entrada y el texto traducido. Los valores posibles son true o false (valor predeterminado).
suggestedFrom Parámetro opcional.
Especifica un idioma de reserva si no se puede identificar el idioma del texto de entrada. La detección automática de idioma se aplica cuando se omite el parámetro from. Si se produce un error en la detección, se asume el idioma suggestedFrom.
fromScript Parámetro opcional.
Especifica el script del texto de entrada.
toScript Parámetro opcional.
Especifica el script del texto traducido.
allowFallback Parámetro opcional.
Especifica que el servicio tiene permiso para recurrir a un sistema general cuando no existe uno personalizado. Los valores posibles son true (valor predeterminado) o false.

allowFallback=false especifica que la traducción solo debe usar sistemas entrenados para la category especificada por la solicitud. Si una traducción del idioma X al idioma Y requiere de encadenamiento mediante un idioma puente E, entonces todos los sistemas de la cadena (X → E y E → Y) deben personalizarse y tener la misma categoría. Si no se encuentra ningún sistema con la categoría específica, la solicitud devuelve un código de estado de 400. allowFallback=true especifica que el servicio tiene permiso para recurrir a un sistema general cuando no existe uno personalizado.

Los encabezados de solicitud incluyen lo siguiente:

encabezados Descripción
Encabezados de autenticación Encabezado de solicitud obligatorio.
Consulte las opciones disponibles para la autenticación.
Content-Type Encabezado de solicitud obligatorio.
Especifica el tipo de contenido de la carga.
El valor aceptado es application/json; charset=UTF-8.
Content-Length Opcional.
Longitud del cuerpo de la solicitud.
X-ClientTraceId Opcional.
GUID generado por el cliente para identificar de forma única la solicitud. Puede omitir este encabezado si incluye el id. de seguimiento en la cadena de la consulta mediante un parámetro de consulta denominado ClientTraceId.

Cuerpo de la solicitud

El cuerpo de la solicitud es una matriz JSON. Cada elemento de la matriz es un objeto JSON con una propiedad de cadena denominada Text, que representa la cadena que se va a traducir.

[
    {"Text":"I would really like to drive your car around the block a few times."}
]

Para obtener información sobre los límites de caracteres y matrices, consulte Límites de solicitud.

Response body

Una respuesta correcta es una matriz JSON con un resultado para cada cadena en la matriz de entrada. Un objeto del resultado incluye las siguientes propiedades:

  • detectedLanguage: objeto que describe el idioma detectado mediante las siguientes propiedades:

    • language: cadena que representa el código del idioma detectado.

    • score: valor flotante que indica la confianza en el resultado. La puntuación varía entre cero y uno, y una puntuación baja indica una confianza baja.

    La propiedad detectedLanguage solo está presente en el objeto de resultado cuando se solicita la detección automática de idioma.

  • translations: matriz de resultados de la traducción. El tamaño de la matriz coincide con el número de idiomas de destino especificados a través del parámetro de consulta to. Cada elemento de la matriz incluye:

    • to: cadena que representa el código del idioma de destino.

    • text: cadena que proporciona el texto traducido.

    • transliteration: objeto que proporciona el texto traducido en el script especificado por el parámetro toScript.

      • script: cadena que especifica el script de destino.

      • text: cadena que proporciona el texto traducido en el script de destino.

      El objeto transliteration no se incluye si no se produce la transliteración.

      • alignment: objeto con una propiedad de cadena única denominada proj, que asigna el texto de entrada al texto traducido. La información de alineación solo se proporciona cuando el parámetro de solicitud includeAlignment es true. La alineación se devuelve como un valor de cadena del siguiente formato: [[SourceTextStartIndex]:[SourceTextEndIndex]–[TgtTextStartIndex]:[TgtTextEndIndex]]. Los dos puntos separan el índice inicial y final, el guión separa los idiomas y el espacio separa las palabras. Una palabra puede alinearse con cero, una o varias palabras en el otro idioma, y las palabras alineadas pueden ser no contiguas. Si no existe información de alineación disponible, el elemento de alineación estará vacío. Consulte Obtener información de alineación para ver un ejemplo y restricciones.

    • sentLen: objeto que devuelve los límites de las oraciones en los textos de entrada y salida.

      • srcSentLen: matriz de enteros que representan las longitudes de las oraciones en el texto de entrada. La longitud de la matriz es el número de oraciones y los valores son la longitud de cada oración.

      • transSentLen: matriz de enteros que representan las longitudes de las frases en el texto traducido. La longitud de la matriz es el número de oraciones y los valores son la longitud de cada oración.

      Los límites de oraciones solo se incluyen cuando el parámetro de solicitud includeSentenceLength es true.

  • sourceText: objeto con una propiedad de cadena única denominada text, que proporciona el texto de entrada en el script predeterminado del idioma de origen. La propiedad sourceText solo está presente cuando la entrada se expresa en un script que no es el habitual del idioma. Por ejemplo, si la entrada fuera árabe escrita en alfabeto latino, sourceText.text sería el mismo texto árabe convertido en script árabe..

En la sección de ejemplos se proporcionan ejemplos de respuestas JSON.

Encabezados de respuesta

encabezados Descripción
X-requestid Valor generado por el servicio para identificar la solicitud utilizada con fines de solución de problemas.
X-mt-system Especifica el tipo de sistema que se usó para la traducción en cada idioma de destino solicitado para la traducción. El valor es una lista de cadenas separadas por comas. Cada cadena indica un tipo:

Custom: la solicitud incluye un sistema personalizado y se ha usado al menos un sistema personalizado durante la traducción.
Team: el resto de solicitudes.
X-metered-usage Especifica el consumo (el número de caracteres que se cobrará al usuario) de la solicitud de trabajo de traducción. Por ejemplo, si la palabra "Hello" se traduce del inglés (en) al francés (fr), este campo devuelve el valor 5.

Códigos de estado de respuesta

A continuación se indican los códigos de estado HTTP posibles que devuelve una solicitud.

status code Descripción
200 Correcto.
400 Uno de los parámetros de consulta falta o no es válido. Corrija los parámetros de la solicitud antes de volver a intentarlo.
401 No pudo autenticarse la solicitud. Compruebe que las credenciales que se especificaron sean correctas.
403 La solicitud no está autorizada. Compruebe los detalles del mensaje de error. Este código de estado suele indicar que ha usado todas las traducciones gratuitas proporcionadas con una suscripción de prueba.
408 No se pudo satisfacer la solicitud porque falta un recurso. Compruebe los detalles del mensaje de error. Cuando la solicitud incluye una categoría personalizada, este código de estado suele indicar que el sistema de traducción personalizado todavía no está disponible para atender solicitudes. Se debe reintentar la solicitud tras un período de espera (por ejemplo, 1 minuto).
429 El servidor rechazó la solicitud porque el cliente superó los límites de solicitud.
500 Se ha producido un error inesperado. Si el error continúa, notifíquelo con la fecha y hora del error, el identificador de la solicitud del encabezado de respuesta X-RequestId y el identificador de cliente del encabezado de solicitud X-ClientTraceId.
503 Servidor no disponible temporalmente. Vuelva a intentarlo. Si el error continúa, notifíquelo con la fecha y hora del error, el identificador de la solicitud del encabezado de respuesta X-RequestId y el identificador de cliente del encabezado de solicitud X-ClientTraceId.

Si se produce un error, la solicitud devuelve una respuesta de error JSON. El código de error es un número de 6 dígitos que combina el código de estado HTTP de 3 dígitos y otro número de 3 dígitos que ayuda a categorizar aún más el error. En la página de referencia de Traductor v3 pueden encontrarse los códigos de error comunes.

Ejemplos

Traducción de una única entrada

En este ejemplo se muestra cómo traducir una única oración del inglés al chino simplificado.

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=zh-Hans" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'Hello, what is your name?'}]"

El cuerpo de la respuesta es:

[
    {
        "translations":[
            {"text":"你好, 你叫什么名字？","to":"zh-Hans"}
        ]
    }
]

La matriz translations incluye un elemento, que proporciona la traducción de la parte única de texto en la entrada.

Traducción de una única entrada con la detección automática de idioma

En este ejemplo se muestra cómo traducir una única oración del inglés al chino simplificado. La solicitud no especifica el idioma de entrada. En su lugar, se usa la detección automática del idioma de origen.

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=zh-Hans" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'Hello, what is your name?'}]"

El cuerpo de la respuesta es:

[
    {
        "detectedLanguage": {"language": "en", "score": 1.0},
        "translations":[
            {"text": "你好, 你叫什么名字？", "to": "zh-Hans"}
        ]
    }
]

La respuesta es similar a la respuesta del ejemplo anterior. Dado que se ha solicitado la detección automática de idioma, la respuesta también incluye información sobre el idioma detectado con relación al texto de entrada. La detección automática de idioma funciona mejor con texto de entrada más largo.

Traducción con transliteración

Vamos a ampliar el ejemplo anterior mediante la adición de la transliteración. La siguiente solicitud pide una traducción de chino escrita en alfabeto latino.

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=zh-Hans&toScript=Latn" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'Hello, what is your name?'}]"

El cuerpo de la respuesta es:

[
    {
        "detectedLanguage":{"language":"en","score":1.0},
        "translations":[
            {
                "text":"你好, 你叫什么名字？",
                "transliteration":{"script":"Latn", "text":"nǐ hǎo , nǐ jiào shén me míng zì ？"},
                "to":"zh-Hans"
            }
        ]
    }
]

El resultado de la traducción incluye ahora una propiedad transliteration, que proporciona el texto traducido con caracteres latinos.

Traducción de varios fragmentos de texto

Traducir varias cadenas a la vez es simplemente cuestión de especificar una matriz de cadenas en el cuerpo de la solicitud.

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=zh-Hans" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'Hello, what is your name?'}, {'Text':'I am fine, thank you.'}]"

La respuesta contiene la traducción de todos los fragmentos de texto exactamente en el mismo orden que en la solicitud. El cuerpo de la respuesta es:

[
    {
        "translations":[
            {"text":"你好, 你叫什么名字？","to":"zh-Hans"}
        ]
    },
    {
        "translations":[
            {"text":"我很好，谢谢你。","to":"zh-Hans"}
        ]
    }
]

Traducción a varios idiomas

En este ejemplo se muestra cómo traducir la misma entrada a diferentes idiomas en una sola solicitud.

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=zh-Hans&to=de" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'Hello, what is your name?'}]"

El cuerpo de la respuesta es:

[
    {
        "translations":[
            {"text":"你好, 你叫什么名字？","to":"zh-Hans"},
            {"text":"Hallo, was ist dein Name?","to":"de"}
        ]
    }
]

Control de palabras soeces

Normalmente, el servicio Traductor conserva las palabras soeces que están presentes en el origen de la traducción. El grado de palabras soeces y el contexto que hace que las palabras profanas difieren entre las culturas y, como resultado, el grado de soece en el idioma de destino se puede amplificar o reducir.

Si quiere evitar obtener palabras soeces en la traducción, independientemente de su presencia en el texto de origen, puede usar la opción de filtrado de palabras soeces. La opción permite elegir si quiere que se eliminen las palabras soeces, si quiere marcarlas con etiquetas adecuadas (lo que le ofrece la opción de agregar su propio posprocesamiento) o si no quiere que se realice ninguna acción. Los valores aceptados de ProfanityAction son Deleted, Markedy NoAction (valor predeterminado).

Valor de ProfanityAction aceptado Valor de ProfanityMarker Acción Ejemplo: Origen: español Ejemplo: Destino: inglés
NoAction Predeterminada. Igual que si no se configura la opción. Las blasfemias pasan del origen al destino. Que coche de<insert-profane-word> What a <insertar-blasfemia> car
Marked Asterisk Los asteriscos reemplazan las palabras soeces (valor predeterminado). Que coche de<insert-profane-word> What a *** car
Marked Etiqueta Las palabras soeces aparecerán rodeadas por etiquetas XML <profanity>...</profanity>. Que coche de<insert-profane-word> What a <profanity><insertar-blasfemia></profanity> car
Deleted Las palabras soeces se quitan de la salida sin reemplazo. Que coche de<insert-profane-word> What a car

En los ejemplos anteriores, <insertar-blasfemia> es un marcador de posición para palabras soeces.

Por ejemplo:

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=de&profanityAction=Marked" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'This is an <expletive> good idea.'}]"

Esta solicitud devuelve lo siguiente:

[
    {
        "translations":[
            {"text":"Das ist eine *** gute Idee.","to":"de"}
        ]
    }
]

Comparar con:

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=de&profanityAction=Marked&profanityMarker=Tag" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'This is an <expletive> good idea.'}]"

La última solicitud devuelve:

[
    {
        "translations":[
            {"text":"Das ist eine <profanity>verdammt</profanity> gute Idee.","to":"de"}
        ]
    }
]

Traducción de contenido que incluye marcado

Es habitual traducir el contenido que incluye marcado, como contenido de una página HTML o de un documento XML. Incluya el parámetro de consulta textType=html al traducir contenido con etiquetas. Además, a veces resulta útil para excluir contenido específico de la traducción. Puede utilizar el atributo class=notranslate para especificar contenido que debería permanecer en el idioma original. En el ejemplo siguiente, el contenido del primer elemento div no se traduce, mientras que el del segundo elemento div, sí.

<div class="notranslate">This will not be translated.</div>
<div>This will be translated. </div>

A continuación, se muestra una solicitud de ejemplo a modo ilustrativo.

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=zh-Hans&textType=html" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'<div class=\"notranslate\">This will not be translated.</div><div>This will be translated.</div>'}]"

La respuesta es:

[
    {
        "translations":[
            {"text":"<div class=\"notranslate\">This will not be translated.</div><div>这将被翻译。</div>","to":"zh-Hans"}
        ]
    }
]

Obtención de información de alineación

La alineación se devuelve como un valor de cadena del siguiente formato para cada palabra del origen. La información de cada palabra se divide por un espacio, incluso en el caso de los idiomas no separados por espacios (scripts), como el chino:

[[SourceTextStartIndex]\:[SourceTextEndIndex]–[TgtTextStartIndex]\:[TgtTextEndIndex]] *

Cadena de alineación de ejemplo: "0:0-7:10 1:2-11:20 3:4-0:3 3:4-4:6 5:5-21:21".

En otras palabras, los dos puntos separan el índice inicial y final, el guión separa los idiomas y el espacio separa las palabras. Una palabra puede alinearse con cero, una o varias palabras en el otro idioma, y las palabras alineadas pueden ser no contiguas. Si no existe información de alineación disponible, el elemento de alineación está vacío. El método no devuelve ningún error en ese caso.

Para recibir información de alineación, especifique includeAlignment=true en la cadena de consulta.

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=fr&includeAlignment=true" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'The answer lies in machine translation.'}]"

La respuesta es:

[
    {
        "translations":[
            {
                "text":"La réponse se trouve dans la traduction automatique.",
                "to":"fr",
                "alignment":{"proj":"0:2-0:1 4:9-3:9 11:14-11:19 16:17-21:24 19:25-40:50 27:37-29:38 38:38-51:51"}
            }
        ]
    }
]

La información de alineación empieza por 0:2-0:1, lo que significa que los tres primeros caracteres del texto de origen (The) se asignan a los dos primeros caracteres del texto traducido (La).

Limitaciones

La obtención de información de alineación es una característica experimental que hemos habilitado para la creación de prototipos de investigación y experiencias con posibles asignaciones de frases. Estas son algunas de las restricciones más importantes en las que no se admiten las alineaciones:

  • La alineación no está disponible para texto en formato HTML, es decir, textType=html.
  • La alineación solo se devuelve para un subconjunto de los pares de idioma:
    • Inglés a/desde cualquier otro idioma excepto chino tradicional, cantoés (tradicional) o serbio (cirílico)
    • de japonés a coreano o coreano a japonés
    • de japonés a chino simplificado y chino simplificado a japonés
    • de chino simplificado a chino tradicional y chino tradicional a chino simplificado
  • No recibirá alineación si la frase es una traducción preestablecida. El ejemplo de una traducción cannada es This is a test, I love youy otras oraciones de alta frecuencia
  • La alineación no está disponible cuando se aplica cualquiera de los enfoques para evitar la traducción como se describe aquí

Obtención de los límites de oración

Para recibir información acerca de la longitud de la oración del texto de origen y del texto traducido, especifique includeSentenceLength=true en la cadena de consulta.

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=fr&includeSentenceLength=true" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'The answer lies in machine translation. The best machine translation technology cannot always provide translations tailored to a site or users like a human. Simply copy and paste a code snippet anywhere.'}]"

La respuesta es:

[
    {
        "translations":[
            {
                "text":"La réponse se trouve dans la traduction automatique. La meilleure technologie de traduction automatique ne peut pas toujours fournir des traductions adaptées à un site ou des utilisateurs comme un être humain. Il suffit de copier et coller un extrait de code n'importe où.",
                "to":"fr",
                "sentLen":{"srcSentLen":[40,117,46],"transSentLen":[53,157,62]}
            }
        ]
    }
]

Traducción con diccionario dinámico

Si ya conoce la traducción que quiere aplicar a una palabra o frase, puede proporcionarla como marcado dentro de la solicitud. El diccionario dinámico solo es seguro para los nombres propios, como nombres de personas y nombres de productos. Nota: La característica de diccionario dinámico distingue mayúsculas de minúsculas.

El marcado que se va a proporcionar utiliza la sintaxis siguiente.

<mstrans:dictionary translation="translation of phrase">phrase</mstrans:dictionary>

Por ejemplo, considere la frase en inglés "The word wordomatic is a dictionary entry" (La palabra "wordomatic" es una entrada de diccionario). Para conservar la palabra wordomatic en la traducción, envíe la solicitud siguiente:

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=de" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'The word <mstrans:dictionary translation=\"wordomatic\">wordomatic</mstrans:dictionary> is a dictionary entry.'}]"

El resultado es el siguiente:

[
    {
        "translations":[
            {"text":"Das Wort \"wordomatic\" ist ein Wörterbucheintrag.","to":"de"}
        ]
    }
]

Esta característica de diccionario dinámico funciona del mismo modo con textType=text o con textType=html. La característica debe usarse con moderación. La mejor forma de personalización de traducción, y más adecuada, es mediante el uso de Custom Translator. Custom Translator hace un uso completo del contexto y las probabilidades estadísticas. Si puede crear datos de entrenamiento que muestren el trabajo o la frase en contexto, obtendrá resultados mucho mejores. Más información acerca de Custom Translator.

Pasos siguientes

Probar el inicio rápido de Translator