Proposal: `i18n.getLanguageDictionary`

[carlosjeurissen]

As requested by @Rob--W, splitting this proposal off from #258

Why

• To be able to fetch messages from a different language than the browser UI language. This can for example be useful if you want to display your extension in a different language.
• Fetching the language files manually is not really a doable alternative as it does not handle fallbacks to less specific language tags and English while adding a lot of boilerplate.

Proposal A

Introduce a i18n.getLanguageDictionary method. In which the first and only parameter is the language tag as string. Returning a promise with the languageDictionary allowing you to request messages from as follows:

browser.i18n.getLanguageDictionary('pt-BR').then((api) => {
  let someMessage = api.getMessage('some_id');
});

Or with async/await:

const brazilApi = await browser.i18n.getLanguageDictionary('pt-BR');
let someMessage = brazilApi.getMessage('some_id');

The name of this method can be worked on. Potential alternatives are createLanguageInstance and getLanguageInstance.

A variant on this is directly passing the getMessage method as suggested by @hanguokai in #274 (comment) .

browser.i18n.getLanguageDictionary('pt-BR').then((getMessage) => {
  let someMessage = getMessage('some_id');
});

Or with async/await:

const getPtBrMessage = await browser.i18n.getLanguageDictionary('pt-BR');
let someMessage = getPtBrMessage('some_id');

Proposal B

Introduce a i18n.getLanguageDictionary method. In which the first and only parameter is the language tag as string. Returning a promise with the languageDictionary allowing you to request messages from as follows:

browser.i18n.getLanguageDictionary('pt-BR').then((languageDictionary) => {
  let someMessage = browser.i18n.getMessage('some_id', substitutions?, {
    dictionary: languageDictionary,
  });
});

Proposal C

Introduce an asynci18n.initLanguage method. In which the first and only parameter is the language tag as string. This would initialise the messagedictionary on the background. The messages can then be fetched sync by passing the language parameter as option.

browser.i18n.initLanguage('pt-BR').then(() => {
  let someMessage = browser.i18n.getMessage('some_id', substitutions?, {
    language:'pt-BR',
  });
});

Proposal D

Allow passing the requested language synchronously. Most convenient for developers however potentially tricky implementation-wise.

  let someMessage = browser.i18n.getMessage('some_id', substitutions?, {
    language:'pt-BR',
  });

Proposal E

(from @hanguokai comment #274 (comment))

// set language to fr
await browser.i18n.setLanguage('fr');
browser.i18n.getMessage('hello'); // return France message: "Bonjour"

// set language to zh-CN
await browser.i18n.setLanguage('zh-CN');
browser.i18n.getMessage('hello'); // return  Simplified Chinese message: "你好"

This is similar to #258 . The difference is that #258 change the default language globally (all contexts) and persistently, but this proposal only change the language in the current context. For example, it doesn't affect another extension page.

Edge cases

• If the passed language parameter is not of type string, it should throw an exception.
• If the language tag can not be found, just like the normal getMessage method, it attempt to check for other available files. In the above example, it would first check pt-BR, then pt, then the default_locale (often english). Firefox skips the pt if the message is not present in pt-BR, yet is available in pt. We might want to raise a separate issue for this.

[xeenon]

What about getLocale or getLocaleMessages for this, to match the naming of the _locales directory and messages.json file?

[carlosjeurissen]

@xeenon is true webExtensions currently mention "locale" here and there. This is something we can talk about as well.

From most use cases I have seen, the getMessage API in browser extensions is mostly used for language and not locale. The region part of the language tag is mostly used to make the language more specific vs for region purposes. Especially now we have the Intl web API, taking care of most regional formatting use cases.

This, and the fact most of the languages we currently handle in browserExtensions completely lack a regional suffix, would make me prefer language over locale not just for this API, but also in other areas of extensions.

[dotproto]

In abstract, I think Chrome is supportive of an end user's desire to change an extension's language independent of the browser UI or an extension developer's desire to show strings in multiple languages. That said, we're a bit hesitant with the i18n.getLanguageDictionary() approach described in the original issue description.

As an alternative, what if we were to modify the signature of i18n.getMessage() to take a language property in an options object? (Note: Firefox does not currently support an options object.) The TypeScript signature for this method might look like this:

function getMessage(
    messageName: string,
    substitutions?: string|string[],
    options?: {
        escapeLt: boolean,
        // New! Takes a locale string such as "pt-BR"
        locale: string
    },
): Promise<string>

This approach may be more ergonomic for developers that wish to work with multiple languages while still allowing developers that wish to use the dictionary pattern to opt into it.

function getLocaleDictionary(locale: string) {
  return function(
      messageName: string,
      substitutions?: string|string[],
      options?: { escapeLt: boolean }
  ) {
    return browser.i18n.getMessage(messageName, substitutions, {...options, locale});
  }
}
let getPtBrMessage = getLocaleDictionary("pt-BR");
let message = getPtBrMessage("example_message");

[hanguokai]

As an alternative, what if we were to modify the signature of i18n.getMessage() to take a language property in an options object?

@dotproto This is the original proposal of #258 (see edited history -> oldest). Then it evolves into a more perfect proposal, and still keep the api that can specify language parameter for getMessage.