Openapi-specification: Internationalization

[mohsen1]

For Swagger.Next we need to add i18n to description fields. We can have two forms of description. It can be a string or an object that has a pair of key,value for each locale/language. We can use ISO 639-2 standard (for example _eng_ for English)

For example:

  description:
    eng: A simple API
    esp: Un simple API
    chi: 一个简单的API

[mohsen1]

title and summary could have i18n too

[fehguy]

This has come up a couple times, with different suggestions. The current work around (and possible a good way to do this) is to identify sections of the spec with IDs (we're currently using vendor extensions) and map to a resource bundle, rather than jumble it all into the spec. I don't know which is better, but that's one approach.

[noirbizarre]

Another approach is to have different specifications generated for each languages.
It's more complex to maintain when specifications are manually written but far more easy when the specification is code driven coupled with something like gettext.
The language selector can be specified either by a path parameter or a query string and resolved by your framework:

/api/1/swagger.json (default to english)
/api/1/en/swagger.json (forced to english)
/api/1/fr/swagger.json (forced to french)
/api/1/swagger.json?lang=en (forced to english)
/api/1/swagger.json?lang=fr (forced to french)

[nacho4d]

I wrote this issue https://github.com/swagger-api/swagger-editor/issues/591 which is basically about internatinalization of labels and titles.

Basically what I had in mind is this:

would become:

What I had in mind is that labels and titles will be translated without modifying the yam file (ex: Summary→概要, Description→説明, Parameters→パラメーター, Responses→リスポンス, Code→コード, Default→デフォルト, etc...) . I imagine swagger will have a bunch of predefined dictionaries only with those words.

Regarding selecting the language, in addition to reading url path or parameters (like @noirbizarre suggested) I thought reading header Accept-Language could be an option too.

[AlbertoLeon]

Another proposal:

description-en: 'for English descriptions'
description-sp: 'for Spanish descriptions'

title-en ....

I think should be treated as different properties.

[webron]

Closed as not supported, following https://github.com/OAI/OpenAPI-Specification/pull/639.

[nacho4d]

@webron #639 and #70 Seems to be about _content_ language that an API returns.
This is about the _documentation_ language. I still looking forward to see swagger in other languages ;-)

[Kitanotori]

I agree with @nacho4d , API content language is totally different thing from the documentation language. There are cases when we want to have documentation language in one language and content language in other. The approach suggested by @mohsen1 seems fine: allow specifying the documentation language via ISO 639-3 language code.

[Frank591]

Hello. What about support of several languages for "description" and "summary" fields? All tasks about that problem was closed, but i don't see into specification any ways to translate API description to several languages. What standard way to translate OpenAPI3 document to several languages?

[Frank591]

Are there any news about internationalization support? We really need this functional in our project

[webron]

We're looking into introducing the concept of Overlays to the spec. Overlays would allow to modify existing content and/or add to it. If this is approved, it would allow users to create language overlays that can be used to modify existing descriptions.

[anticlockwise]

@webron I'm not sure if Overlays should be overloaded to solve the internationalization issue though... It's unclear to me whether the Overlay document will become a separate API or overriding things on the original API? What if I wanted to build yet another Overlay document on the API, then which of the translation Overlay document should I reference?

[webron]

That's the idea with overlays. They are meant as additional layers on top of your API and or not independent APIs. In order to get the 'result', you'd need to run the overlay with the API definition through a pre-processor. That way, you can have an English overlay, a French overlay, a Chinese overlay, and that way get different language versions after pre-processing.

[daniol]

This issue was wrongly closed by @webron as @nacho4d and @Kitanotori pointed out; it should be reopened!

In order to close this issue, the overlays concept should be finished and an example somewhere available, on how to use overlays to create translations.