¿Cómo puedo usar overlays de OpenAPI para localizar las descripciones de una API en distintos idiomas? #

Las plataformas globales suelen necesitar presentar la documentación de la API en varios idiomas. Traducir el texto directamente dentro del documento OpenAPI canónico se vuelve rápidamente inmanejable: cada traducción exigiría una copia paralela, mantenida a mano, de toda la especificación. La OpenAPI Overlay Specification resuelve este problema manteniendo el documento base en un único idioma “de origen” y aplicando un archivo de overlay independiente por cada configuración regional (locale) para reemplazar los campos de texto legibles por personas.

La idea central #

Un overlay de localización solo toca campos de lenguaje natural (summary, description y similares) y nunca toca las partes estructurales de la API (rutas, parámetros, esquemas, tipos). Esto garantiza que el documento localizado siga siendo funcionalmente idéntico al original; solo cambia la redacción.

overlay: 1.0.0
info:
  title: Spanish (es-ES) Localization Overlay
  version: 1.0.0
actions:
  - target: $.info
    update:
      description: "Una API para gestionar pedidos y clientes."
  - target: $.paths['/orders'].get
    update:
      summary: "Listar todos los pedidos"
      description: "Devuelve una lista paginada de pedidos para el cliente autenticado."

Organizar los overlays por locale #

Un patrón habitual es tener un archivo de overlay por locale, con el nombre basado en la etiqueta de idioma BCP 47:

overlays/
  openapi.overlay.es-ES.yaml
  openapi.overlay.fr-FR.yaml
  openapi.overlay.ja-JP.yaml
  openapi.overlay.pt-BR.yaml

Un script de compilación recorre cada archivo y produce un documento completamente localizado:

for locale in es-ES fr-FR ja-JP pt-BR; do
  redocly join openapi.yaml \
    --overlay "overlays/openapi.overlay.$locale.yaml" \
    -o "dist/openapi.$locale.yaml"
done

Localizar las descripciones a nivel de esquema #

Las descripciones de campos dentro de components.schemas se benefician de la localización tanto como los resúmenes de las operaciones:

  - target: $.components.schemas.Order.properties.status.description
    update: "Estado actual del pedido: pendiente, enviado o entregado."

Como en algunas implementaciones de overlay update se fusiona (merge) en un objeto en lugar de reemplazar directamente un valor escalar, comprueba si tu herramienta admite apuntar directamente a un valor escalar final, o si necesitas apuntar al objeto padre y proporcionar description como una clave del objeto fusionado.

Gestionar las etiquetas de enumeraciones y los mensajes de error #

Si tu API devuelve mensajes de error o etiquetas de enumeraciones legibles por personas mediante extensiones x-, también pueden localizarse:

  - target: $.paths['/payments'].post.responses['402']
    update:
      description: "Pago requerido: el saldo de la cuenta es insuficiente."

Evitar la duplicación entre locales #

Para no repetir los mismos destinos JSONPath en cada archivo de locale, muchos equipos generan los propios archivos de overlay a partir de una exportación de un sistema de gestión de traducciones (TMS) (por ejemplo, Phrase, Lokalise o Crowdin), en lugar de escribir el YAML a mano. Un pequeño script lee la exportación del TMS y genera automáticamente un overlay por locale, de modo que los traductores no tienen que tocar el YAML en absoluto.

Validar la salida localizada #

Después de fusionar, pasa el documento localizado por el mismo pipeline de validación que el documento base (por ejemplo, redocly lint) para detectar cualquier cambio estructural accidental introducido por un error en el overlay.

Lecturas relacionadas #

Descubre más sobre el mecanismo base en ¿Qué es la OpenAPI Overlay Specification?, y consulta ¿Cómo puedo usar overlays de OpenAPI para generar documentación de API específica para cada audiencia? para un flujo de trabajo de múltiples salidas relacionado.

Última actualización: 16 de julio de 2026.