[Task]: Document locale codes accepted by the API

[diox]

Description

We only allow translations in specific locales to be added to add-ons through the API (and devhub, but devhub provides you with a dropdown of all available locales). However we don't document what those locales are...

Because it only makes sense to have translations for locales we display AMO in, the list of locales we allow at any given point matches what locales we have enabled on AMO, and is therefore subject to change. So maybe we should have an endpoint instead of a static documentation ? Alternatively, we could start allowing developers to add translations even for locales that are not currently enabled.

Acceptance Criteria

  ### Milestones/checkpoints
  - [ ] Locales accepted by AMO are documented somewhere

Checks

• [x] If I have identified that the work is specific to a repository, I have removed "repository:addons-server" or "repository:addons-frontend"

┆Issue is synchronized with this Jira Task

[carlosjeurissen]

Having such list is very useful for a bunch of reasons as mentioned https://github.com/w3c/webextensions/issues/131

A potential solution would be exposing the locales in https://github.com/mozilla/web-ext

[diox]

This is different : we are talking about the list of locales for the AMO API, which affects the AMO listing, not the webextension itself (AMO imports translations from the webextension at initial upload time, so that plays a role, but when that happens AMO imports what it can automatically).

[carlosjeurissen]

@diox touché. Was under the impression that issue also discussed the store languages. Thanks for clarifying.

As for the AMO API. What would be helpful is adding support for the primary subtags (en, pa, sv). AMO could, if 'en-US' is requested, simply fall back to 'en' if the extension does not provide localisation data in 'en-US'. This is especially useful for tooling using default_locale (often en) as locale as shown in https://github.com/mozilla/addons/issues/15437.

[diox]

default_locale in #1537 was en-US (it can be checked with the API, which exposes it). en-US is also the value we fall back to for default_locale if it's not set / couldn't be imported from the webextension.

[carlosjeurissen]

@diox Right, with default_locale I was referring to the default_locale set by the manifest file of extension authors. Which is often set to en.

[diox]

Alternatively, we could start allowing developers to add translations even for locales that are not currently enabled

Regardless of whether or not we go that route, we should only accept valid language codes as lang parameter in the API (for any operation/HTTP verb).

[KevinMind]

We can include valid locales in the docs based on the existing supported locales, and additionally we could include in invalid locale requests a link to that page in the response.

Specifically we should distinguish between locales we have "included" in our settings and locales that are disabled due to low translation completion.