Do you mean how to use __addLocaleData()? This was brought up in #41, and I agree that we need something, but right now it's difficult to write something that I know is robust because of how adding the data is set up.

Consider the following code built to use the browser's native Intl implementation:

document.addEventListener('DOMContentLoaded', function () {
    var nf = new Intl.NumberFormat(undefined, {style:'currency', currency:'USD'});

    document.getElementById('widgetprice').textContent = nf.format(19.99);
});

Using the polyfill to support this code is complicated. For example:

<script src="/js/Intl.min.js"></script>
<script>document.write(
  '<script src="/locale-data/'+ (navigator.language||navigator.userLanguage) +'.js"><\/script>'
)</script>

This isn't robust because it's possible we don't have a file to match the user's locale. So we'd have to write an asynchronous fetch of the file with a fallback in case of a 404, which means we're changing the way people would normally use the Internationalisation API (e.g. they'd have to wait for a callback before they could use it).

The most robust approach is to implement the code for choosing the correct datafile at the server, based on the Accept-Language header. So we could write some examples for that, if you like, but it's going to be different based on what the server-side language is. This is another reason I'm leaning towards implementing #37 and ditching __addLocaleData() (or just leaving it in as a build option).

I'm happy to hear what you guys think we should do, @caridy, @drewfish and @ericf.

yes, I don't think anyone will end up doing this the document.write()

if computation of the locale-data is something that we want to people will do very often in the client side, then we should think about providing an array with all available locales or at least a filter method under the polyfill to pick the closest locale, so they can leverage that to be sure that the file is available. but in might experience, the whitelist of available locales for a particular application is normally an small subset from the available locale-data of the polyfill, and should be controlled by the app owner, something like this:

<script src="/js/Intl.min.js"></script>
<script>document.write(
  '<script src="/locale-data/'+ getBestLanguage(navigator.language||navigator.userLanguage) +'.js"><\/script>'
)</script>

and that method getBestLanguage() is on the application land.

back to the main subject, I was referencing to the fact that the polyfill is going to define window.IntlPolyfill rather than window.Intl for the reasons we discussed a while ago. And none of that is really documented, and the fact that they might get confused because after including the polyfill window.Intl is not set.

Well we can at least sort that out right away. I'll do something about that shortly.

Might be its own issue, but relevant to this one is how native functions like toLocaleString are overridden when the Intl.js script is included in the browser.

In the Chrome JavaScript console without Intl.js

> (1.1).toLocaleString
   function toLocaleString() { [native code] }

but after adding a <script src="Intl.js"> tag

> (1.1).toLocaleString
  function () {
        // Satisfy test 13.2.1_1
        if (Object.prototype.toString.call(this) !== '[object Number]')
            throw new TypeError('`this` value must be a number for Number.prototype.toLocaleString()');

        // 1. Let x be this Number value (as defined in ES5, 15.7.4).
        // 2. If locales is not provided, then let locales be undefined.
        // 3. If options is not provided, then let options be undefined.
        // 4. Let numberFormat be the result of creating a new object as if by the
        //    expression new Intl.NumberFormat(locales, options) where
        //    Intl.NumberFormat is the standard built-in constructor defined in 11.1.3.
        // 5. Return the result of calling the FormatNumber abstract operation
        //    (defined in 11.3.2) with arguments numberFormat and x.
        return FormatNumber(new NumberFormatConstructor(arguments[0], arguments[1]), this);
    } 

Should Intl.js detect existing native functions or the "proper" way to include might be?

<script>
 if (!window.Intl) { document.write('<script src="/js/Intl.min.js"><\/script>'); }
</script>

@hakanson, I've opened #58 for that.