Document behavior when locales parameter is an array

[slorber]

Hi,

This is quite confusing to me and it does not seem to be well explained in the documentation, as all the exemples only always have a single locale.

I had to check the sources to understand.

What I understand is that it take the first locale in the array for which the language match a registered "CLDR data" (I guess it means fr.js / en.js)

So basically it seems that if you are sure you have appropriately loaded the "CLDR data" for a given locale, you do not have to care about the array.

I think it should be clearer because it is quite confusing. It would be far less confusing if the documentation was using "locale" wording instead of "locales", with a note on using an array instead of a single locale string.

See formatjs/formatjs#81

[caridy]

yeah, we want to improve the docs, thanks for the suggestions, we will look at it.

as for the locales, this is propagated down to the primitives defined in ECMA-402, more details here:
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#Locale_identification_and_negotiation

Now, loading fr.js locale data does not necessary means that we have data for locale fr, that file might hold data for fr and fr-CA, since they have different rules. We don't want to provide data for every locale because it is relative small, even when we fold them by root locales. Here is an example of fr.js:

IntlRelativeFormat.__addLocaleData({"locale":"fr","pluralRuleFunction":function (n) {var i=Math.floor(Math.abs(n));n=Math.floor(n);if(i===0||i===1)return"one";return"other";},"fields":{"second":{"displayName":"seconde","relative":{"0":"maintenant"},"relativeTime":{"future":{"one":"dans {0} seconde","other":"dans {0} secondes"},"past":{"one":"il y a {0} seconde","other":"il y a {0} secondes"}}},"minute":{"displayName":"minute","relativeTime":{"future":{"one":"dans {0} minute","other":"dans {0} minutes"},"past":{"one":"il y a {0} minute","other":"il y a {0} minutes"}}},"hour":{"displayName":"heure","relativeTime":{"future":{"one":"dans {0} heure","other":"dans {0} heures"},"past":{"one":"il y a {0} heure","other":"il y a {0} heures"}}},"day":{"displayName":"jour","relative":{"0":"aujourd’hui","1":"demain","2":"après-demain","-2":"avant-hier","-1":"hier"},"relativeTime":{"future":{"one":"dans {0} jour","other":"dans {0} jours"},"past":{"one":"il y a {0} jour","other":"il y a {0} jours"}}},"month":{"displayName":"mois","relative":{"0":"ce mois-ci","1":"le mois prochain","-1":"le mois dernier"},"relativeTime":{"future":{"one":"dans {0} mois","other":"dans {0} mois"},"past":{"one":"il y a {0} mois","other":"il y a {0} mois"}}},"year":{"displayName":"année","relative":{"0":"cette année","1":"l’année prochaine","-1":"l’année dernière"},"relativeTime":{"future":{"one":"dans {0} an","other":"dans {0} ans"},"past":{"one":"il y a {0} an","other":"il y a {0} ans"}}}}});
IntlRelativeFormat.__addLocaleData({"locale":"fr-ca","pluralRuleFunction":function (n) {var i=Math.floor(Math.abs(n));n=Math.floor(n);if(i===0||i===1)return"one";return"other";},"fields":{"second":{"displayName":"seconde","relative":{"0":"maintenant"},"relativeTime":{"future":{"one":"Dans {0} seconde","other":"Dans {0} secondes"},"past":{"one":"Il y a {0} seconde","other":"Il y a {0} secondes"}}},"minute":{"displayName":"minute","relativeTime":{"future":{"one":"Dans {0} minute","other":"Dans {0} minutes"},"past":{"one":"Il y a {0} minute","other":"Il y a {0} minutes"}}},"hour":{"displayName":"heure","relativeTime":{"future":{"one":"Dans {0} heure","other":"Dans {0} heures"},"past":{"one":"Il y a {0} heure","other":"Il y a {0} heures"}}},"day":{"displayName":"jour","relative":{"0":"aujourd’hui","1":"demain","2":"après-demain","-2":"avant-hier","-1":"hier"},"relativeTime":{"future":{"one":"Dans {0} jour","other":"Dans {0} jours"},"past":{"one":"Il y a {0} jour","other":"Il y a {0} jours"}}},"month":{"displayName":"mois","relative":{"0":"Ce mois-ci","1":"Le mois prochain","-1":"Le mois dernier"},"relativeTime":{"future":{"one":"Dans {0} mois","other":"Dans {0} mois"},"past":{"one":"Il y a {0} mois","other":"Il y a {0} mois"}}},"year":{"displayName":"année","relative":{"0":"Cette année","1":"L'année prochaine","-1":"L'année dernière"},"relativeTime":{"future":{"one":"Dans {0} an","other":"Dans {0} ans"},"past":{"one":"Il y a {0} an","other":"Il y a {0} ans"}}}}});

That's the reason why your application can use ['fr-CA', 'fr', 'us'], which will be normalized under the hood to the best match, and it will pick up the right locale data to format the data.

[caridy]

to be clear, you normally don't need to worry much about this, and you just pass one locale in that array, and it will resolve the best match based on the locale data known by the library and the browser in case of primitives.

[slorber]

thanks

So i guess i'll only use one then :)

[caridy]

I will keep this open until we update the documentation.