Repository navigation
Proposal: i18n.getAvailableLanguages() - #942
carlosjeurissen wants to merge 9 commits into
Conversation
ea465f8 to
777030f
Compare
| 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. |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
@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.
There was a problem hiding this comment.
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.
457040a to
dbb20d1
Compare
dbb20d1 to
e70c179
Compare
e70c179 to
e89ba98
Compare
xeenon
left a comment
There was a problem hiding this comment.
The comments below are about making the behavior exact enough that implementations agree.
…ailable to return an empty array
|
@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. |
There was a problem hiding this comment.
@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.
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
@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.
There was a problem hiding this comment.
+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.
There was a problem hiding this comment.
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 the open Firefox patch
| 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']`. |
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
@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.
There was a problem hiding this comment.
+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.
There was a problem hiding this comment.
Updated the example and added a note on not including fallback languages.
oliverdunk
left a comment
There was a problem hiding this comment.
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.
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 withouti18n.setLanguage()and would be able to be used with thei18n.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:
-> probably not, as this requires more advanced language negotiations in
i18n.setLanguage()andi18n.withLanguage()and removes the use case for using fetch('messages.json').directory exists which does not contain a messages.json file?
-> this seems to be mostly already handled when browsers validate the extension.
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.
-> when the extension is not localised, this method has zero use. It seems most intuitive to return a rejected promise in this case.
default_localeat 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.
i18n.getAllLanguages(), @oliverdunk suggestedi18n.getParsedLocalesDirectoriesbefore.-> other alternatives could be
i18n.getAvailableResourceLanguages().AllandAvailablecould be ambiguous.