swagger-api / swagger-api/swagger-ui

[improvement] Translation: automatic and manual language selection

Open
#2,488 10 comments 37 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

cat: a11y cat: user experience P2 type: feature version: 3.x
Dominant language
JavaScript
Stars
29k
Forks
9.3k
Avg merge
2d 23h
Merged PRs (30d)
25

Description

Problem description:

https://github.com/swagger-api/swagger-ui/blob/1f2a5d7dd74131f0e9886b0f137ac20165aa90d2/dist/lang/translator.js#L6-L8

* To enable translation you should include one of language-files in your index.html
* after <script src='lang/translator.js' type='text/javascript'></script>.
* For example - <script src='lang/ru.js' type='text/javascript'></script>

This is unacceptable in today's internet. Every end user should see his language.
So:

  1. swagger-ui should provide some query parameter (e.g. lang) to set set user's language and apply corresponding translation. (This is needed for integration purposes.)

  2. If the parameter is not specified, swagger-ui should determine user's language automatically using the following variables (actually, all of them in the specified order) and apply corresponding translation:

    1. navigator.languages
    2. navigator.language
    3. navigator.userLanguage
  3. End user should be able to change the language using swagger-ui.

Additional information:
swagger-ui version affected: commit 1f2a5d7
swagger file: not required

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with dist/lang/translator.js, especially the documented language-file loading flow, and inspect the index.html integration described in the issue. Trace how translations are currently selected and loaded. Done means supporting an explicit lang query parameter, the listed browser-language fallbacks, and an end-user language change while applying the corresponding translation.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
frontend, internationalization
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.