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 swagger-api/swagger-editor#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 #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 ;-)

[nakamorichi]

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.