Multilingual support

[alexgagnon]

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?

[jstoiko]

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:

• Yet another Overlay proposal Overlay-Specification#36
• RAML Overlay equivalent? Overlay-Specification#35

[akuckartz]

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

[ghost]

Additional previous discussion: #274. Localization, internationalization or multilingual support, whatever you call it, is a must for products aiming to document something. Overlays may be overkill, and something better integrated with the specification is probably better.

It might be enough to support what was suggested in the original post: anywhere a string is supported, support an object where the keys are the language code, and the values are the translation.

[alexgagnon]

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

[tigerinus]

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!

[diegopennesi]

Any news concerning this feature?

[makdad]

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.

[kscheirer]

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"
      }
    }
  ]
}

[jiangsier-xyz]

Are there any updates to this issue?

[handrews]

See also discussion #2460

[handrews]

Given that Overlay 1.0.0 is in the final week-long approval period for release, and @kscheirer demonstrated that the current Overlay spec can do the job, I'm going to close this. If there's more to discuss regarding this use case, please add your comments in that repository:

• Known use cases for Overlays Overlay-Specification#9

The Overlay project intends to move quickly on to a 2.0, so if there are problems with 1.0 as a solution, the discussion linked above is the place to get them heard!