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 ;-)

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

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

[tigerinus]

Seriously, this issue should be re-opened.

Multilingual support in public documentation is almost certain required by many public policies. Maintaining two copies of OpenAPI YAML in different language is chaotic. Thanks!

[jeremyfiel]

a lot of the suggestions here are good but they seem to depend on some sort of UI generated from the OAS definition. If that's the case, the i18n should be handled by the documentation tooling rather than the specification.

[nacho4d]

There are two main problems to tackle here. Hopefully this explanation helps developers/admins so they re-open this issue.

1. The localized strings that are hardcoded by the tooling. In above screenshot these will be the keywords in blue: "Summary" "Description" "Parameters", etc. These keywords internationalization should be handled by the tooling. So, regarding 1, I agree with @jeremyfiel. These keywords are out of scope of OpenAPI spec. (Although some guidelines or some dictionaries could be defined by OpenAPI team)

2. The localized strings for the content. (Suppose your documentation has 2 audiences, English speakers and Japanese speakers). Obviously, these cannot be hardcoded by the tooling. The tools will never know about the content. Since one single yml file will have various languages Specification should define keys to support various languages. I think @AlbertoLeon idea is accurate and extensible enough.

For example:

paths:
    /products:
        get:
             summary-en: 'Get all the products'
             summary-ja: '全ての商品を取得'
             description-en: 'Get all the products (Long explanation here)'
             description-ja: '全ての商品を取得(詳細な説明をここに記述)'

Aside Note:

I imagine some tools might use the user-agent other tools might have a pull-down menu to trigger the language change, etc. If the tool needs/wants to show a yml in Japanese then the word Description should show as 説明 (This translation will be done by the tooling and it does not need to be defined in the yml file. What is has to be defined in the yml file is the the Japanese description and summary for the /products endpoint. Therefore there should be a place for storing this Japanese string, other for the English string, etc. Hence this IS part of the OpenAPI.

As explained above, Number 2 is IN the scope of OpenAPI specification because it defines what keys should be added and how they should be interpreted/used.

[karenetheridge]

or alternatively (nested objects may be easier for tooling to parse than splitting apart a string):

paths:
  /products:
    get:
      summary:
        en: 'Get all the products'
        jp: '全ての商品を取得'
      description:
        en: 'Get all the products (Long explanation here)'
        jp: '全ての商品を取得(詳細な説明をここに記述)'

[ghahramani]

another suggestion to have an extension for those who uses spring boot and just read from i18n that is already supported by spring, it can be much easier to just put the property key in the OpenAPIDefinition annotation and let the spring handles the i18n for you which mean it can handle it with accept language header

[nacho4d]

Having a tool that generates 1 yaml files per language is a nice feature and if Spring has already implemented it then it is one way to go for now :) In reality OpenAPI is used by several other tools not only Spring. In my opinion OpenAPI is tool agnostic and it should support i18n from design.

[ghahramani]

Yes, that is correct but bear in mind that agnostic tools needs to be agnostic in their core but not in their surface, the OpenAPI core can have i18n (interface) like component base structure (same as what kubernetes does) and then we can have a plugin of OpenAPI that integrates (implement the interface) with spring feature, in this case it is still agnostic but you can use the feature of both world

[minesunny]

I think it would be better if replace with a var name in i18n resource file

openapi: 3.0.3
info:
  title: RuleTemplate
  description: ${rule.template.description}
  version: 1.0.0

[axelsean]

The suggestion from @minesunny would be the way to go here, then it would work for all fields, and a "base" resource file would have the boilerplate translations. This could also be extended to documentation generated from code, which right now pass the text, add functionality to add a resource key.

I don't see this, but a Right-to-Left language has other issues that possibly require a different document template

[handrews]

@axelsean @minesunny is there any reason that this couldn't be done with existing templating and localization systems? Is there a need to handle this in a different way from I18N/L10N of any other document? Since this seems to be about the documentation text in the OpenAPI Description and not things like using HTTP headers to access localized resources.

(EDIT: I don't know exactly why this was closed int he past, so I'm hesitant to re-open unless it's clear that this needs to be intergrated into the spec itself)

[axelsean]

@handrews There's two parts here, Globalization - creating the framework, and Localization actually doing it.

The spec needs to define how an implementor will provide localizable content, for example is it one of the below (stolen from earlier comments).

In either case the actual UI presentation needs to be able to localize the header for description (as others have noted), in some sites this is a language drop down in the UI - that would work here.

description:
    en: A simple API
    fr: Un simple API

or - note this needs resource files per supported language

languages: [en, fr]
...   
description: {my.description.tag}

Personally I favor the resource files approach:

• it is much easier to support when generating documentation from code - which is the way we do this.
• Right-to-Left is supportable easily

[lornajane]

This issue is closed as being out of scope for OpenAPI. The best approach currently is the overlays as recommended earlier in the thread. Perhaps we can request some examples of how this could be done to be added over on learn.openapis.org - but further discussion here isn't helpful.

[iseki0]

It's not out of scope. Besides machine-reading, documentation is designed to read by human. Human using different languages around the world. Why do you think that's "out of scope"? @lornajane

[handrews]

@iseki0 Lorna's comment does not mean that I18N/L10N is out-of-cope for the OpenAPI Initiative, just out-of-scope for the OpenAPI Specification. It is, however, in-scope for the Overlay Specification, and is mentioned in an issue in that repo:

• https://github.com/OAI/Overlay-Specification/issues/31#issuecomment-2188308337

The Overlay spec is about to get an official 1.0 release blessing the current state of the draft which has a few implementations already, followed by a 2.0 effort based on the feedback so far and changes in technology since 1.0 started.