How can I use OpenAPI overlays to localize API descriptions for different languages?

How can I use OpenAPI overlays to localize API descriptions for different languages? #

Global platforms frequently need to present API documentation in multiple languages. Translating text directly inside the canonical OpenAPI document quickly becomes unmanageable — every translation would require a parallel, hand-maintained copy of the entire spec. The OpenAPI Overlay Specification solves this by keeping the base document in one “source” language and applying a separate overlay file per locale to replace human-readable text fields.

The Core Idea #

A localization overlay only ever touches natural-language fields — summary, description, and similar text — and never touches the structural parts of the API (paths, parameters, schemas, types). This guarantees the localized document remains functionally identical to the original; only the wording changes.

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

Organizing Overlays per Locale #

A common pattern is one overlay file per locale, named by BCP 47 language tag:

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

A build script iterates over each file and produces a fully localized document:

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

Localizing Schema-Level Descriptions #

Field-level descriptions inside components.schemas benefit from localization just as much as operation summaries:

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

Because update merges into an object rather than replacing a scalar directly in some overlay implementations, verify whether your tooling supports targeting a scalar leaf value directly, or whether you need to target the parent object and provide description as a key in the merged object.

Handling Enum Labels and Error Messages #

If your API returns human-readable error messages or enum labels via x- extensions, those can be localized too:

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

Avoiding Duplication Across Locales #

To avoid repeating the same JSONPath targets across every locale file, many teams generate the overlay files themselves from a translation management system (TMS) export (e.g., Phrase, Lokalise, Crowdin), rather than hand-writing YAML. A small script reads the TMS export and produces one overlay per locale automatically, keeping translators out of the YAML entirely.

Validating Localized Output #

After merging, run the localized document through the same validation pipeline as the base document (e.g., redocly lint) to catch any accidental structural changes introduced by a mistake in the overlay.

Learn more about the base mechanism in What is the OpenAPI Overlay Specification?, and see How can I use OpenAPI overlays to generate audience-specific API documentation? for a related multi-output workflow.

Last updated on July 16, 2026.