Per-extension language preferences

[hanguokai]

Update: In order to express it completely and clearly, I reorganized the proposal and edited it many times after 2022-09-12.

Summary

Currently, browser.i18n only display one default language to users. Users can't change the language to other extension supported languages independently. Developers need to use their own solutions to provide users with multiple language select menu.

It makes sense for an app to use another language independently of the operating system. For example, Android supports per-app language preferences (here is its docs and video). The same goes for extensions. This proposal brings per-app language preferences to browser extensions.

Tracking bugs: Chromium-1365283 , Firefox-1791356

Main Content

1. Browser built-in supply a language select menu per extension

Since this is a general purpose feature for all users and extensions, browser built-in support is best.

If browsers built-in support a language select menu per extensions, all developers, all existing extensions and users can get this benefit right away. Ideally, developers just use current i18n api without doing anything. Another benefit is that it's much easier for developers to test i18n.

2. New APIs for developers

/**
 * get the current language used by i18n.getMessage()
 * return the language tag,  e.g. en-US, zh-CN.
 */
i18n.getCurrentLanguage() => code: String.

/**
 * set a new language used in this extension.
 * if code is null, revert to the default state(follow the browser UI language).
 * if code is not valid, reject it.
 * return a Promise, resolved when the operation is complete.
 */
i18n.setCurrentLanguage(code: String) => Promise<void>

/**
 * get all languages that supported by this extensions.
 * return a Promise, resolved with an array of language tags.
 */
i18n.getAllLanguages() => code_array: Promise<Array<String>>

/**
 * After i18n changed to a new language, the browser triggers a language changed event.
 * callback is (new_language_code: String) => void
 */
i18n.onLanguageChanged.addListener(callback)

Ideally, developers just use current i18n api without doing anything if there is a browser-supplied language select menu. The new api is only used to integrate this feature with the developer-supplied language select menu. For example, in the extension's options page, developers use get/setCurrentLanguage and getAllLanguages to create a language select menu for users.

i18n.setCurrentLanguage(code) is persistent. It is a setting per extensions which saved by browsers. If the extension remove a language in the new version and current language is that, then browser fall back to the default language.

code is standard language code, like 'en-US', not 'en_US'(folder name).

How to get language display names? Use Intl.DisplayNames, for example:

const currentLanguage = i18n.getCurrentLanguage();
const displayName = new Intl.DisplayNames([currentLanguage], 
      { type: 'language' , languageDisplay: 'standard' });

const allLanguages = await i18n.getAllLanguages();
for (let code of allLanguages) {
    let name = displayName.of(code)); // language display name for code
    // use code and name to create a language select
}

After changing the language, the browser triggers a onLanguageChanged event. This event is useful for updating UI for already opened extension pages and other UI parts like badgeText, badgeTitle and context menu.

i18n.onLanguageChanged.addListener(function(newCode) {
    // update extension page
    button.textContent = i18n.getMessage(buttonLabel);

    // update extension UI parts
    action.setTitle({title: i18n.getMessage(title)});
    action.setBadgeText({text: i18n.getMessage(text)});
    contextMenus.update(...);
});

3. Another New API (optional for implementation)

i18n.getMessage(messageName, substitutions?,  {language: "langCode"})

At present, i18n.getMessage() doesn't allow specifying a different language. I suggest add a new property to specify a language in the options parameter(the 3rd parameter which already support a "escapeLt" property). Maybe it is useful for some developers or some use cases.

Related References

https://developer.chrome.com/docs/extensions/reference/i18n/
https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/i18n
https://crbug.com/660704
#252

[jcblw]

I have had this similar issue with the i18n library. This caused use to have to write a custom solution that manually fetchs locales based on the user's selection. This would be a greatly welcomed feature in web extensions for my team and I.

[xeenon]

Cool idea!

[hanguokai]

Today, Google publishes a video on Android YouTube channel: Per-app language preferences. I recommend everyone to watch this video in its entirety, which is only 5 minutes. This video is my final purpose for this issue (just replace Android with Browser, and replace app with extension). So I changed the title to "Per-extension language preferences".

If browsers support browser.i18n.getMessage(a-specific-language), then developers can use this API to implement a language select menu for users (save user's preference in storage). Otherwise, developers have to write their own solution.

Further more, browsers can supply a built-in language menu for users, like below:

And supply a related api for developers to integrate this function in their language select menu in extension. For example:
i18n.getCurrentLanguage() / i18n.setCurrentLanguage(), i18n.onCurrentLanguageChanged. In this way, user's language preference is saved by browser, not in storage by developers.

[Juraj-Masiar]

I like the idea of being able to call i18n.setCurrentLanguage and browser would then serve locals from a different file.

Comparing with browser.i18n.getMessage + supplying language code, where one would have to read the "user-selected" language code from somewhere, probably using some async method, which would make the whole call async or one would have to await some "language init" before any language related operations starts, which is a terrible idea.

[hanguokai]

I like the idea of being able to call i18n.setCurrentLanguage and browser would then serve locales from a different file.

Comparing with browser.i18n.getMessage + supplying language code, where one would have to read the "user-selected" language code from somewhere, probably using some async method, which would make the whole call async or one would have to await some "language init" before any language related operations starts, which is a terrible idea.

Yes, I implemented this solution before. First, async read user's language preference from browser.storage.local, then do other things. i18n.setCurrentLanguage(lang) is more easier than i18n.getMessage(lang_code). So I prefer i18n.setCurrentLanguage(lang) or completely let user use browser's extension-language-select UI setting. But i18n.getMessage(lang_code) may be useful for some developers or some use cases. If possible, hopefully both will be supported.

[yankovichv]

Yes, such a solution would be valuable.

[xeenon]

I also prefer the i18n.setCurrentLanguage() proposal too. Avoiding local storage each time a string is needed is good.

[bershanskiy]

The original comment mentions that "if the extension would like to supply a language selecting menu in the extension settings, it can't use i18n.getMessage() and has to use other workarounds." Out of curiosity, I wrote one such workaround and it boils down to loading the locale JSON from extension files via fetch or XmlHttpRequest, parsing it, and taking the required message:

const locale = 'en_US';
const messages = await (await fetch(chrome.runtime.getURL(`/_locales/${locale}/messages.json`))).json()
const message = messages[message_name];

This does not seem too bad and overall this feature is trivially polyfillable even currently. The only caveat is that this workaround would be async while i18n.setCurrentLanguage() is synchronous.

Also, turns out this exact idea was proposed back in 2016 (comment 5, code example it links to), so compatibility should be good.

I also prefer the i18n.setCurrentLanguage() proposal too. Avoiding local storage each time a string is needed is good.

Would this persist across browser restarts/extension reloads? What should happen when a locale is removed during the extension update?