Skip to content

Proposal: i18n.getAvailableLanguages() - #942

Open
carlosjeurissen wants to merge 9 commits into
w3c:mainfrom
carlosjeurissen:proposal/i18n.getavailableLanguages
Open

carlosjeurissen wants to merge 9 commits into
w3c:mainfrom
carlosjeurissen:proposal/i18n.getavailableLanguages

Conversation

@carlosjeurissen

@carlosjeurissen carlosjeurissen commented Jan 23, 2026 •

Copy link
Copy Markdown
Member

Corresponding issue: #995

motivation for separate PR:
While a similar method has been proposed in https://github.com/w3c/webextensions/pull/641/changes#diff-a7a555f6d716353fea0a7a15523a1639b33556d7dee81e1e531c320a4f593fcfR70 as i18n.getAllLanguages. I believe splitting it into a separate proposal allows us to move faster for this specific method, considering just this method is already useful without i18n.setLanguage() and would be able to be used with the i18n.withLanguage() proposal. See #274.

A separate PR also allows us to dive deeper in the specifics of this method which seem very valuable.

open ends:

  • should any other transformation other than _ to - be applied? ie, iw -> he?
    -> probably not, as this requires more advanced language negotiations in i18n.setLanguage() and i18n.withLanguage() and removes the use case for using fetch('messages.json').
  • what if an invalid locale tag is used, like "_locales/b/messages.json"? Or a
    directory exists which does not contain a messages.json file?
    -> this seems to be mostly already handled when browsers validate the extension.
  • what if the browser never intents to support a specific language in
    i18n.setLanguage('iw') or i18n.withLanguage('iw')? Should it be excluded
    in getAvailableLanguages?
    -> seems there are no real reasons a browser would avoid specific language tags with the exception of language tags not following bcp47 standards.
  • do we want to reject if the extension is not localised, or return an empty array or return an array with the browser locale?
    -> when the extension is not localised, this method has zero use. It seems most intuitive to return a rejected promise in this case.
  • do we want the returned list to be sorted alphabetically? Potentially put the default_locale at the top?
    -> sorting alphabetically by default seem to be enough to have same behaviour cross-browser. On the other hand, extension developers can easily use .sort() if requested. And may want to eventually sort the list based on human name.
  • what about the name? @hanguokai suggested i18n.getAllLanguages(), @oliverdunk suggested i18n.getParsedLocalesDirectories before.
    -> other alternatives could be i18n.getAvailableResourceLanguages(). All and Available could be ambiguous.

@carlosjeurissen
carlosjeurissen force-pushed the proposal/i18n.getavailableLanguages branch from ea465f8 to 777030f Compare January 23, 2026 16:37
@carlosjeurissen carlosjeurissen added the i18n-tracker Group bringing to attention of Internationalization, or tracked by i18n but not needing response. label Jan 29, 2026
the extension language in the extension settings.

An example of content-script matching is "Category Tabs for Google Keep", which
needs to match it's language with the page in question to properly integrate.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could you show an example of how the API would be used in practice for this use case?

I'm wondering what a browser-defined API can provide that is not already possible by the extension. I'd expect that the extension can pre-generate a list of supported languages in relation to the files output to _locales/, which would be far more efficient than what a browser can offer.

You have already mentioned this possibility in the "Existing Workarounds", so it is clear that you are aware of the possibility.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated the proposal to include the practical example.

The browser-defined API would allow to list the intersection of languages the browser recognises and the extension includes. As mentioned, the set of resource files can be different depending on the extension store.

For Naver Whale specifically, I have a build script which removes unsupported resource files from the extension package after being built. There are even custom scenarios in which too many resource files requires the removal of the majority of resource files. In these scenarios, updating the set of supported languages in some JS file would add another layer of already complex build setup.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Similar to Rob, I'm not convinced that there are use cases which justify the addition of this API.

Adding a build step which exposes the bundled languages to your extension at runtime seems reasonable to me. The API would not provide anything which you could not also achieve in this way.

I can see value if we add the ability to set your extension's locale programatically. At that point, it is useful to know which of your locale directories the browser has parsed. However, it would make sense to add both APIs at the same time (as we discussed in #641), instead of just adding this API in isolation.

@carlosjeurissen carlosjeurissen Jan 30, 2026 •

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@oliverdunk thanks for taking a look at the proposal!

First of all, #641 has been stalled for more than a year and has not seen any progress since. Other APIs like the proposed i18n.withLanguage() would go well with i18n.getAvailableLanguages(). Having i18n.getAvailableLanguages() stuck in the i18n.setLanguage() proposal could block it's usage for i18n.withLanguage().

There are many reasons this API is useful in isolation even before i18n.withLanguage() and i18n.setLanguage() are available. besides the build step complexity listed above and the extension store compatibility. There is also the use case of being able to polyfill i18n.withLanguage() and i18n.setLanguage(). With i18n.getAvailableLanguages() one would be able to have a third party dependency polyfilling these potential future APIs. Thus especially now when i18n.withLanguage() and i18n.setLanguage() are not available, i18n.getAvailableLanguages() would unlock these use cases.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the extra context. I was convinced by the argument that a library polyfilling new API methods may not be easily hooked into a build script but would benefit from having an API to fetch the languages.

@xeenon xeenon left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The comments below are about making the behavior exact enough that implementations agree.

@carlosjeurissen

carlosjeurissen commented Oct 31, 2026 •

Copy link
Copy Markdown
Member Author

@xeenon thanks for the review and the great feedback! Updated the proposal document incorporating all the feedback.

@Rob--W updated the Firefox patch to match the new behavior as suggested by @xeenon to not reject in case no languages are available or the extension is not localised. In this case, the API now returns an empty array. See https://phabricator.services.mozilla.com/D327837


The returned array should be sorted by code unit. Each returned language code should be formatted to be a proper BCP47 tag. For example: `zh_hant` should be returned as `zh-Hant`.

However the actual codes themselves should not be modified. For example, `iw` should not be returned as `he`, but as `iw`. So the language tags should only be formatted, not canonicalised.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@eemeli we do this to make it easy for developers to use the code both in other APIs as well as to fetch the language resource files using normal fetch calls.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That seems like a reason to return the codes exactly as they are used in the resource paths, and not formatted at all. If you're already expecting for a consumer to somehow map zh-Hant to zh_hant, why not also expect them to map he into iw?

@carlosjeurissen carlosjeurissen Nov 12, 2026 •

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@eemeli thanks for your reply! The reason for only doing the formatting and not the canonicalisation is due to the historic mistake of no always using BCP47 everywhere. See #642

This is also a compromise between using this method to be used in the i18n.withLanguage() proposal and as manual resource loading from _locales dir.

When we want to consider canonicalisation seems the unicode canonicalisation could be considered too aggressive for the resource loading scenario.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

+1 to returning the names as they appear in _locales/. It's the simplest rule for Safari to implement and test, it is consistent with leaving iw alone, and it avoids implying a validity the API can't guarantee.

@carlosjeurissen carlosjeurissen Nov 13, 2026 •

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If we only return the exact names as appear in _locales/ we limit the API to only resource files. In this case I would rename the method to i18n.getResourceLanguages() or equivalent. Ideally I want this API to work for both use cases.

Given an extension with the following resource files:
`_locales/en/messages.json`, `_locales/es/messages.json` and `_locales/es_419/messages.json`.

The `i18n.getAvailableLanguages()` method would return a promise which resolves with the following array: `['en', 'es', 'es-419']`.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we please be more precise in our definition here, so implementors know how to approach this? For example, if I didn't include _locales/es/messages.json, would we still return es because es_419 is a more specific version?

Or to ask another way, are we listing directory names or listing all tags that could be fulfilled by them?

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@oliverdunk Thanks for reviewing and asking clarification on this! No, it should not return es when only es_419 is available. It should not return the whole fallback tree. We can add this as a suggestion to the proposal document.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

+1 to listing directories and not the fallback tree, and to adding that to the document.

The sentence that lets a browser leave out tags it "does not understand" is still open. Safari lists the entries in _locales/ without validating them, so it would return a different array for the same package than a browser that does. I'd prefer a condition that can be tested, for example: a directory under _locales/ is included if it contains a messages.json file.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated the example and added a note on not including fallback languages.

@oliverdunk oliverdunk left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks Carlos - this is looking good at a high level, but I'd like to see more precise description of the behavior. Also adding @rdcronin to confirm we are supportive of this still given how long it has been since the initial discussions.

@oliverdunk
oliverdunk requested a review from rdcronin November 12, 2026 11:56

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

i18n-tracker Group bringing to attention of Internationalization, or tracked by i18n but not needing response. topic: localization

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants