Traductor 3.0: Lenguajes

  • Artículo

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

URL de la solicitud

Envíe una solicitud GET a:

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

ConsulteCompatibilidad de Virtual Network para la configuración y asistencia de la red seleccionada y el punto de conexión privado del servicio Traductor.

Parámetros de solicitud

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

Parámetros de consulta Descripción
api-version Parámetro obligatorio

Versión de la API que el cliente solicitó. El valor debe ser 3.0.
scope Parámetro opcional.

Lista de nombres separados por comas que definen el grupo de idiomas que se devolverá. Los nombres de grupo permitidos son: translation, transliteration y dictionary. Si no se proporciona ningún ámbito, se devuelven todos los grupos, lo que es equivalente a pasar scope=translation,transliteration,dictionary.

Consulteel cuerpo de la respuesta.

Los encabezados de solicitud son:

encabezados Descripción
Accept-Language Encabezado de solicitud opcional.

Idioma que se usará para las cadenas de la interfaz de usuario. Algunos de los campos de la respuesta son nombres de idiomas o regiones. Utilice este parámetro para definir el idioma en que se devolverán los nombres. El idioma se especifica al proporcionar una etiqueta de idioma BCP 47 con el formato correcto. Por ejemplo, utilice el valor fr para solicitar nombres en francés o utilice el valor zh-Hant para solicitar nombres en chino tradicional.
Los nombres se proporcionan en inglés cuando no se especifica un idioma de destino o cuando la localización no está disponible.
X-ClientTraceId Encabezado de solicitud opcional.
GUID generado por el cliente para identificar de forma única la solicitud.

No es obligatorio que la autenticación obtenga recursos de idioma.

Response body

Un cliente usa el parámetro de consulta scope para definir los grupos de idiomas en los que está interesado.

  • scope=translation proporciona los idiomas admitidos para traducir texto de un idioma a otro;

  • scope=transliteration proporciona funcionalidades para convertir texto en un idioma de un script a otro;

  • scope=dictionary proporciona pares de idiomas para los que las operaciones de Dictionary devuelven datos.

Un cliente puede recuperar varios grupos simultáneamente mediante la especificación de una lista de nombres separados por comas. Por ejemplo, scope=translation,transliteration,dictionary devolvería los idiomas admitidos para todos los grupos.

Una respuesta correcta es un objeto JSON con una propiedad para cada grupo solicitado:

{
    "translation": {
        //... set of languages supported to translate text (scope=translation)
    },
    "transliteration": {
        //... set of languages supported to convert between scripts (scope=transliteration)
    },
    "dictionary": {
        //... set of languages supported for alternative translations and examples (scope=dictionary)
    }
}

El valor de cada propiedad es el siguiente.

  • Propiedad translation

    El valor de la propiedad translation es un diccionario de pares (clave, valor). Cada clave es una etiqueta de idioma BCP 47. Una clave identifica un idioma de origen o destino para la traducción de un texto. El valor asociado a la clave es un objeto JSON con propiedades que describen el idioma:

    • name: nombre para mostrar del idioma en la configuración regional solicitada a través del encabezado Accept-Language.

    • nativeName: nombre para mostrar del idioma en la configuración regional nativa del idioma.

    • dir: direccionalidad, que es rtl para los idiomas de derecha a izquierda o ltr para los idiomas de izquierda a derecha.

    Ejemplo:

    {
  "translation": {
    ...
    "fr": {
      "name": "French",
      "nativeName": "Français",
      "dir": "ltr"
    },
    ...
  }
}

  • Propiedad transliteration

    El valor de la propiedad transliteration es un diccionario de pares (clave, valor). Cada clave es una etiqueta de idioma BCP 47. Una clave identifica un idioma para el que se puede convertir texto de un script a otro. El valor asociado a la clave es un objeto JSON con propiedades que describen el idioma y sus scripts admitidos:

    • name: nombre para mostrar del idioma en la configuración regional solicitada a través del encabezado Accept-Language.

    • nativeName: nombre para mostrar del idioma en la configuración regional nativa del idioma.

    • scripts: lista de scripts de origen de la conversión. Cada elemento de la lista scripts tiene las siguientes propiedades:

      • code: código de identificación del script.

      • name: nombre para mostrar del script en la configuración regional solicitada a través del encabezado Accept-Language.

      • nativeName: nombre para mostrar del idioma en la configuración regional nativa del idioma.

      • dir: direccionalidad, que es rtl para los idiomas de derecha a izquierda o ltr para los idiomas de izquierda a derecha.

      • toScripts: lista de scripts disponibles como destino para la conversión de texto. Cada elemento de la lista toScripts tiene las propiedades code, name, nativeName y dir descritas anteriormente.

    Ejemplo:

    {
  "transliteration": {
    ...
    "ja": {
      "name": "Japanese",
      "nativeName": "日本語",
      "scripts": [
        {
          "code": "Jpan",
          "name": "Japanese",
          "nativeName": "日本語",
          "dir": "ltr",
          "toScripts": [
            {
              "code": "Latn",
              "name": "Latin",
              "nativeName": "ラテン語",
              "dir": "ltr"
            }
          ]
        },
        {
          "code": "Latn",
          "name": "Latin",
          "nativeName": "ラテン語",
          "dir": "ltr",
          "toScripts": [
            {
              "code": "Jpan",
              "name": "Japanese",
              "nativeName": "日本語",
              "dir": "ltr"
            }
          ]
        }
      ]
    },
    ...
  }
}

  • Propiedad dictionary

    El valor de la propiedad dictionary es un diccionario de pares (clave, valor). Cada clave es una etiqueta de idioma BCP 47. La clave identifica un idioma para el que existen traducciones alternativas y traducciones inversas disponibles. El valor es un objeto JSON que describe los idiomas de origen y destino con las traducciones disponibles:

    • name: nombre para mostrar del idioma de origen en la configuración regional solicitada a través del encabezado Accept-Language.

    • nativeName: nombre para mostrar del idioma en la configuración regional nativa del idioma.

    • dir: direccionalidad, que es rtl para los idiomas de derecha a izquierda o ltr para los idiomas de izquierda a derecha.

    • translations: lista de idiomas con traducciones alternativas y ejemplos para la consulta expresada en el idioma de origen. Cada elemento de la lista translations tiene las siguientes propiedades:

      • name: nombre para mostrar del idioma de destino en la configuración regional solicitada a través del encabezado Accept-Language.

      • nativeName: nombre para mostrar del idioma de destino en la configuración regional nativa del idioma de destino.

      • dir: direccionalidad, que es rtl para los idiomas de derecha a izquierda o ltr para los idiomas de izquierda a derecha.

      • code: código de idioma que identifica el idioma de destino.

    Ejemplo:

    "es": {
  "name": "Spanish",
  "nativeName": "Español",
  "dir": "ltr",
  "translations": [
    {
      "name": "English",
      "nativeName": "English",
      "dir": "ltr",
      "code": "en"
    }
  ]
},

La estructura del objeto de respuesta no cambia sin un cambio en la versión de la API. Para la misma versión de la API, la lista de idiomas disponibles puede cambiar con el tiempo porque Microsoft Translator amplía continuamente la lista de idiomas admitidos en sus servicios.

La lista de idiomas admitidos no cambia con frecuencia. Para ahorrar ancho de banda de red y mejorar la capacidad de respuesta, una aplicación cliente debe considerar el almacenamiento en caché de los recursos de idioma y la correspondiente etiqueta de entidad (ETag). A continuación, la aplicación cliente puede consultar periódicamente (por ejemplo, una vez cada 24 horas) al servicio para capturar el conjunto más reciente de idiomas admitidos. Pasar el valor ETag actual en un campo de encabezado If-None-Match permite al servicio optimizar la respuesta. Si no se ha modificado el recurso, el servicio devuelve el código de estado 304 y un cuerpo de respuesta vacío.

Encabezados de respuesta

encabezados Descripción
ETag Valor actual de la etiqueta de entidad para los grupos de idiomas admitidos solicitados. Para mejorar la eficacia de solicitudes posteriores, el cliente puede enviar el valor ETag en un campo de encabezado If-None-Match.
X-RequestId Valor generado por el servicio para identificar la solicitud. Se usa para solucionar problemas.

Códigos de estado de respuesta

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

Código de estado Descripción
200 Correcto.
304 El recurso no se ha modificado desde la versión especificada por los encabezados de solicitud If-None-Match.
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.
429 El servidor rechazó la solicitud porque el cliente superó los límites de solicitudes.
500 Se ha producido un error inesperado. Si el error continúa, notifíquelo con: fecha y hora del error, identificador de la solicitud del encabezado de respuesta X-RequestId e 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: fecha y hora del error, identificador de la solicitud del encabezado de respuesta X-RequestId e identificador de cliente del encabezado de solicitud X-ClientTraceId.

Si se produce un error, la solicitud también 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

En el ejemplo siguiente se muestra cómo recuperar los idiomas admitidos para la traducción de texto.

curl "https://api.cognitive.microsofttranslator.com/languages?api-version=3.0&scope=translation"