Multilingual support

Hi there,

I'm wondering if there currently is any way to define language-specific values for the descriptive elements in the specification, such as description, or example?

For example:

{
  "title": "Sample Pet Store App",
  "description": "This is a sample server for a pet store.",
  "version": "1.0.1"
}

Might be rewritten to:

{
  "title": "Sample Pet Store App",
  "description": {
    "*": "This is a sample server for a pet store.",
    "fr": "Ceci est un exemple de serveur pour une animalerie.",
  },
  "version": "1.0.1"
}

Where title is a string, so it will be used as the text for all languages, while description is an object consisting of language codes that code generators can use for additional language options (in this example, the * is used as a default wildcard).

Does something like this exist?

There is a discussion to introduce the concept of “Overlays” in OAS (3.1). Overlays would address the use case you are describing by giving the ability to define a separate document that references another OAS document and either overrides or adds to certain fields of that same OAS document. This would be useful for i18z as well as several other use cases.

You might want to check-out those two issues to get a idea of what it would look like:

JSON-LD has language maps. See https://www.w3.org/TR/json-ld/#string-internationalization

I took a look at #274, and that issue has been closed, and I'm not sure what the status is with overlays at the moment. I tend to agree with @i-sf that although overlays provides a lot of flexibility it seems like a hammer in this case. We've also kind of hit a dead-end in terms of allowing for multilingual paths (not sure if anyone has figured out a good way to do that), but offering documentation in multiple languages from a single document would be very helpful

Multilingual support in public documentation is almost certain required by many public policies. Maintaining multiple copies of OpenAPI YAML in different language is chaotic. It'd be a huge life saver to support multiple languages in OpenAPI.

Thanks!

Any news concerning this feature?

I'll just throw in here that "I absolutely need this".

My company maintains public APIs for customers in multiple languages, and our product teams are trying to use OAS3 (or 3.1, depending on tooling) to describe these APIs. In the absence of a solution, we'll probably use an x-description-i18n-type solution with custom tooling to generate multiple documents from a "master" one.

@alexgagnon

I will take a look at if/how overlays can solve this problem. This is part of determining whether overlay spec is sufficient, so I won't comment on other solutions now.

For @alexgagnon's original question, solution would look like

{
  "overlay": "1.0.0",
  "info": {
    "title": "French Language Overlay",
    "version": "1.0.0"
  },
  "actions": [
    {
      "target": "info",
      "update": {
        "title": "Exemple d'application pour animalerie",
        "description": "Ceci est un exemple de serveur pour une animalerie."
      }
    }
  ]
}

A more complicated example, using petstore.json as a base is below.

{ 
  "overlay": "1.0.0",
  "info": {
    "title": "French Language Overlay (Targeted)",
    "version": "1.0.0"
  },
  "actions": [
    {
      "target": "info",
      "update": {
        "title": "Exemple d'application pour animalerie",
        "description": "Ceci est un exemple de serveur pour une animalerie.",
        "x-overlay-applied": "language-fr"
      }
    },
    {
      "target": "paths.\"/pets\".get",
      "update": {
        "summary": "Lister tous les animaux de compagnie"
      }
    },
    {
      "target": "paths.\"/pets\".get.responses.default",
      "update": {
        "description": "D'accord"
      }
    },
    {
      "target": "paths.\"/pets\".post",
      "update": {
        "summary": "Créer un animal de compagnie"
      }
    },
    {
      "target": "paths.\"/pets\".post.responses.201",
      "update": {
        "description": "Réponse nulle"
      }
    },
    {
      "target": "paths.\"/pets/{petId}\".get",
      "update": {
        "summary": "Informations pour un animal spécifique"
      }
    },
    {
      "target": "paths.\"/pets/{petId}\".get.parameters[0]",
      "update": {
        "description": "L'identifiant de l'animal à récupérer"
      }
    },
    {
      "target": "paths.\"/pets/{petId}\".get.responses.200",
      "update": {
        "description": "Réponse attendue à une requête valide"
      }
    }
  ]
}

Are there any updates to this issue?

Navigation Menu

Repository navigation

Multilingual support #1740

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Multilingual support #1740

Description

Activity

jstoiko commented on Nov 3, 2018

akuckartz commented on Nov 4, 2018

alexgagnon commented on Mar 25, 2021

tigerinus commented on Aug 17, 2021

diegopennesi commented on Sep 7, 2021

makdad commented on Dec 30, 2021

kscheirer commented on May 10, 2022

jiangsier-xyz commented on Aug 1, 2023

Valecia2023 commented on Aug 12, 2023

handrews commented on Apr 19, 2024

handrews commented on Oct 16, 2024

Code-Parth commented on Mar 15, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions