Traductor 3.0: Lenguajes

Artículo
09/01/2024

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

En el caso de las redes virtuales, use el punto de conexión de dominio personalizado:

https://<your-custom-domain>.cognitiveservices.azure.com/languages?api-version=3.0

Para obtener más información, consulte Compatibilidad de red virtual con el servicio Translator, configuración y compatibilidad con puntos de conexión privados seleccionados.

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`.

Consulte el 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 proporcionando una etiqueta de idioma 47 bien formada BCP . 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.

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 proporcionando una etiqueta de idioma 47 bien formada `BCP` . 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 scope parámetro de consulta para definir qué grupos de idiomas se van a enumerar.

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 BCP etiqueta de 47 idiomas. 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 BCP etiqueta de 47 idiomas. 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 BCP etiqueta de 47 idiomas. 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 el recurso no se modifica, 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 modifica y se alinea con la versión especificada por los encabezados `If-None-Match`de solicitud .
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 solicitud.
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"

Compartir a través de