¿Cómo admite OpenAPI la internacionalización? #

La internacionalización, abreviada como i18n, es el proceso de diseñar aplicaciones de software de modo que puedan adaptarse a distintos idiomas y regiones sin necesidad de cambios de ingeniería. Con la proliferación de las API web en un mundo conectado globalmente, admitir la internacionalización se ha convertido en un aspecto crucial del diseño de API. OpenAPI, un estándar ampliamente adoptado para definir API, incluye varias funciones y prácticas para dar soporte a la internacionalización. Este artículo explora cómo admite OpenAPI la internacionalización y las consideraciones clave al crear API que deben ser accesibles para un conjunto diverso de usuarios de todo el mundo.

¿Qué es OpenAPI? #

OpenAPI es una especificación para crear API que permite a los desarrolladores describirlas en un formato estandarizado y legible por máquinas. La especificación OpenAPI (OAS) define una interfaz estándar e independiente del lenguaje para las API RESTful, que permite tanto a las personas como a los equipos informáticos comprender las capacidades de un servicio sin acceder al código fuente. Herramientas como Swagger, Redoc y OpenAPI Generator pueden analizar documentos OpenAPI para crear documentación, SDK de cliente y esqueletos de servidor.

Internacionalización en el diseño de API #

Diseñar una API para la internacionalización implica una serie de consideraciones, desde admitir varios idiomas en las cargas útiles de las solicitudes y respuestas, los encabezados y los mensajes de error, hasta asegurar que los formatos de fecha y hora, los formatos numéricos y otros datos específicos de la configuración regional se gestionen correctamente.

Localización de las respuestas #

Al crear una API que atiende a una audiencia global, es esencial que pueda devolver respuestas en el idioma preferido del usuario. OpenAPI lo admite permitiendo a quienes desarrollan la API especificar distintos ejemplos de respuesta para diferentes configuraciones regionales.

Uso de examples y content en OpenAPI #

El objeto content de un documento OpenAPI describe el tipo de medio y la estructura de la respuesta. Este objeto puede incluir un campo examples, en el que puedes proporcionar distintos ejemplos para varios idiomas:

paths:
  /greeting:
    get:
      summary: Retrieve greeting message
      responses:
        '200':
          description: A greeting message
          content:
            application/json:
              schema:
                type: string
              examples:
                en:
                  summary: English Example
                  value: "Hello, World!"
                es:
                  summary: Spanish Example
                  value: "¡Hola, Mundo!"
                fr:
                  summary: French Example
                  value: "Bonjour, le monde!"

Lo anterior es un ejemplo de configuración YAML en el que se proporcionan distintos ejemplos de un mensaje de saludo en inglés (en), español (es) y francés (fr).

Localización de los mensajes de error #

La gestión de errores es una parte fundamental de una API, y los mensajes de error deben ser comprensibles para los usuarios en su idioma preferido. OpenAPI admite la localización de los mensajes de error de forma similar a los mensajes de respuesta.

Encabezados HTTP para la negociación de contenido #

Para entregar contenido en el idioma preferido del usuario, se pueden utilizar encabezados HTTP como Accept-Language. El encabezado Accept-Language le indica al servidor qué idioma prefiere el cliente. El servidor puede usar esta información para devolver respuestas o mensajes de error localizados.

GET /greeting HTTP/1.1
Host: example.com
Accept-Language: fr

En esta solicitud HTTP, el encabezado Accept-Language indica una preferencia por el idioma francés.

Formatos de fecha y hora #

Cada configuración regional da formato a las fechas y horas de manera distinta. Es esencial admitir diversos formatos de fecha y hora para que los usuarios de diferentes regiones puedan entender los datos sin confusión. Aunque OpenAPI no impone por sí mismo un formato concreto para la fecha y la hora, utiliza la palabra clave format para especificar los formatos aceptados, como date para el formato de fecha ISO 8601 (YYYY-MM-DD).

components:
  schemas:
    Event:
      type: object
      properties:
        eventDate:
          type: string
          format: date

Aquí, eventDate se especifica en formato ISO 8601, un estándar internacional ampliamente aceptado.

Compatibilidad con varios formatos de datos #

Además de las fechas y las horas, deben tenerse en cuenta los números y las monedas. Cada configuración regional representa los números de forma distinta (por ejemplo, usando comas en lugar de puntos como separadores decimales). Las API deben diseñarse para manejar estas variaciones, especialmente cuando se trabaja con datos financieros.

Internacionalización de la documentación de la API #

La documentación de la API debe estar disponible en varios idiomas para atender a desarrolladores de todo el mundo. Herramientas de OpenAPI como Swagger UI y Redoc permiten generar documentación interactiva y multilingüe.

Swagger UI #

Swagger UI permite configurar varios archivos de idioma. Los desarrolladores pueden cargar dinámicamente distintos archivos de idioma según las preferencias del usuario.

Ejemplos de técnicas de localización #

1. Endpoints específicos por configuración regional: a veces, las API pueden incluir endpoints específicos para cada configuración regional, como /en/greeting, /es/greeting, etc., aunque esta no es la solución más escalable.
2. Parámetros de consulta: otro enfoque consiste en usar parámetros de consulta como lang. Por ejemplo: GET /greeting?lang=fr.

Buenas prácticas para la internacionalización de las API #

1. Usa encabezados estándar: utiliza siempre encabezados HTTP estándar como Accept-Language para la negociación de contenido.
2. Formatos coherentes: mantén formatos de fecha, hora y números coherentes en toda tu API para facilitar la localización.
3. Metadatos legibles por máquinas: incluye metadatos legibles por máquinas en tus documentos OpenAPI para especificar los idiomas admitidos.
4. Pruebas exhaustivas: realiza pruebas exhaustivas con distintas configuraciones regionales para detectar inconsistencias o traducciones faltantes.
5. Mecanismo de respaldo: implementa un mecanismo de respaldo para los casos en que la configuración regional preferida no esté disponible.

Herramientas y bibliotecas #

Varias herramientas y bibliotecas pueden ayudar a crear API internacionalizadas con OpenAPI:

1. LinguiJS: una biblioteca de internacionalización para JavaScript que se puede aprovechar junto con OpenAPI.
2. I18next: otro framework de internacionalización popular para JavaScript que puede combinarse con OpenAPI para ofrecer traducciones.
3. openapi-comment-parser: esta herramienta ayuda a generar especificaciones OpenAPI a partir de comentarios del código, que pueden incluir información específica de cada configuración regional.

Conclusión #

Admitir la internacionalización en tus API definidas con OpenAPI es indispensable para llegar a una audiencia global. Al aprovechar las funciones de OpenAPI para especificar ejemplos localizados, manejar varios formatos de datos, usar encabezados HTTP estándar para la negociación de contenido y garantizar que la documentación de tu API sea multilingüe, puedes crear API más inclusivas y fáciles de usar. Recuerda considerar todos los aspectos de la internacionalización, desde los mensajes de error hasta el formato de los datos, y realiza siempre pruebas exhaustivas con distintas configuraciones regionales. Con estas prácticas, puedes asegurarte de que tu API atienda de manera eficaz a una base de usuarios de todo el mundo.

Última actualización: 5 de junio de 2024.