Allowing customization of URL-based locale detection rule

[mesr]

I would like to propose and, if approved, offer to implement the possibility for client code to customize — and even de-activate — the URL-based language detection rule that is currently hard-coded around the lang query-string parameter. Use cases for such a feature abound in the wild:

• Wikipedia uses subdomains (e.g. fr.wikipedia.org);
• Mozilla Developer Network uses path prefixes (e.g. developer.mozilla.org/en-US/...);
• Sites, such as Amazon, who own a collection of related domains with country-specific TLDs might want to map them to each country's official language (amazon.uk → "en", amazon.mx → "es", etc.);
• Embedded components and applications, as well as those that forward parts of the URL as-is to a back-end, might prefer a different query-string parameter name for easier integration (e.g. ...?l=en, ...?locale=en-UK, etc.), or implement a completely different channel for determining the correct locale to use, such as a parameter passed upon initialization.

Updates to the source code would preserve compatibility with the current I18n module's API by keeping the current hard-coded rule as a default value, while providing an additional setter function (namely setLocaleDetectionRule(rule)) for changing or de-activating the locale detection rule dynamically.

The rule function, by its nature, would actually not be limited to URL-based detection. It is easy to imagine that such a function could pull its return value from e.g. an attribute defined on the component, an app-wide store or an async HTTP request to a back-end server. Therefore, rule functions returning a promise that resolve to a locale string would also be supported.

Types, tests and documentation would be updated accordingly.

What would be the maintainer's position on such a feature? Any additional suggestions?

[ducksoupdev]

@mesr I really like your idea, it will allow locale detection to be flexible and keep the API lightweight. Go ahead and submit a PR and we'll be happy to review it.

[mesr]

Great! Thank you @ducksoupdev.

In the current source code, the detected locale is guarantied to be a string, since it is obtained through properties or functions that are themselves guarantied to hold or return string values. Allowing client code to determine that value means that we now need to deal with arbitrary types. I am trying to account for all possible cases in a simple, meaningful and intuitive manner without doing error-checking and hard-coding throw statements.

As a general approach, when the rule parameter passed by client code to the new setLocaleDetectionRule(rule) function is itself a function, it is internally saved as is. In all other cases, it is taken as a constant value and is internally converted to a function that invariably returns that value.

The question is then: how do we handle the various types that can be returned by that function? I see two possibilities:

1. string vs non-string: If the return type is a string, or a promise that resolves to a string, it is interpreted as a locale string and the active locale is set to that value. All other types are considered invalid, prompting the locale detection mechanism to proceed with the fallback detection methods. This would have the consequence of allowing the empty string as a valid locale name;

2. truthy vs falsy: If the return type is a truthy value, or a promise that resolves to a truthy value, it is assumed to be a locale name and, if not already a string, type-casted to a string before setting the active locale to that value. Receiving a falsy value, or a promise that resolves to a falsy value, would prompt the locale detection mechanism to proceed with the fallback detection methods. This would have the consequence of allowing objects that convert to e.g. '[object Object]' as valid locale names, while disallowing the empty string and the number 0.

Your feedback on which approach would be more in line with FicusJS' design philosophy would be appreciated. Thank you in advance.

[mesr]

I have submitted the PR for the update to the i18n package and am currently working on updating the documentation accordingly.

A few noteworthy points:

• I went with option 1 above since it felt simpler and more natural to me by avoiding such situations as the ugly, meaningless '[object Object]' object-to-string conversion and the number 0 as a particular case, but please let me know if option 2 is preferred (a simple 1-liner update to the code);
• I have assigned a very permissive any type to the rule parameter in types/i18n.d.ts but I don't use TypeScript myself so I'm wondering whether TypeScript coders would instead prefer a stricter type, such as null | string | Function;
• This is a small detail, but I'm pondering whether we should shorten the new setLocaleDetectionRule(rule) function's name to setLocaleDetection(rule) instead;
• The I18n constructor does not currently accept parameters and striving to disturb the current API as little as possible leads to the unavoidable necessity of switching locale twice when registering a custom detection rule (a first time upon instantiation and a second time when registering the custom rule).

[ducksoupdev]

Implemented with #54