Minor clarification to initial code example in docs.

[darrin]

Hello all -

First off thanks for this project. Amazing work!

I'm writing bc I made a silly (?) assumption when I started working with this project that almost caused me to go try something else. My mistake I think but I'd like to suggest a minor clarification to a documentation.

I wrote up this stackoverflow issue issue to explain.

I think if you alter the first code example - it would've saved me a chunk of time. In short, my misunderstanding was that Globalize.load( require( "cldr-data" ).entireMainFor( "en", "es" ) ) meant load all locales for English and Spanish. But in fact that didn't seem to work for me.

If you include a language-locale combination in the initial example I think that would help people (me at least) make the mental leap that this isn't doing something more extensive and that the locale is important in addition to the language!

var Globalize = require( "globalize" );
Globalize.load( require( "cldr-data" ).entireSupplemental() );
Globalize.load( require( "cldr-data" ).entireMainFor( "en", "es-MX" ) );

Globalize("en").formatDate(new Date());
// > "11/27/2015"

Globalize("es-MX").formatDate(new Date());
// > "27/11/2015"

Thanks!

[rxaviers]

Hi @darrin, thanks for reporting this issue. Yeap, loading en and es doesn't mean you'll load the data for all English and Spanish spoken places. en means English as spoken in the United States and Latin script (both the territory and script are deduced given they are respectively the most likely region and script used in this place according to CLDR data). Similarly, es means Spanish as spoken in Spain and Latin script.

We definitely need to improve education about locale in our docs. The definition comes from CLDR (UTS#35). The difficulty is that the mapping between the bundle and the locale isn't always a direct map (see the bundle for zh-TW below for example):

Description	locale	bundle to load
English as spoken in US	en = en-US = en-Latn-US	en
English as spoken in England	en-GB = en-Latn-GB	en-GB
English as spoken in India	en-IN = en-Latn-IN	en-IN
Spanish as spoken in Spain	es = es-ES = es-Latn-ES	es
Spain as spoken in Mexico	es-MX = es-Latn-MX	es-MX
Chinese as spoken in China	zh = zh-CN = zh-Hans-CN	zh
Chinese as spoken in Taiwan	zh-TW = zh-Hant-TW	zh-Hant

I liked your idea of updating the initial example to make things more explicit, but I still think we need something more... What do you think of the below? Is is better than what we have today?

var Globalize = require( "globalize" );
Globalize.load( require( "cldr-data" ).entireSupplemental() );
Globalize.load( require( "cldr-data" ).entireMainFor( "en", "es", "es-MX", "zh", "zh-Hant" ) );

// English as spoken in the United States and Latin script.
Globalize("en").formatDate(new Date());
// > "11/27/2015"

// Spanish as spoken in Spain and Latin script.
Globalize("es").formatDate(new Date());
// > "27/11/2015"

Globalize( "es" ).formatRelativeTime( 1, "year" );
// > "el próximo año"

// Spanish as spoken in Mexico and Latin script.
Globalize( "es-MX" ).formatRelativeTime( 1, "year" );
// > "el año próximo"

// Chinese as spoken in China and Simplified Han script.
Globalize("zh").formatRelativeTime( 2, "second" );
// > 2秒钟后

// Chinese as spoken in Taiwan and Traditional Han script.
Globalize("zh-TW").formatRelativeTime( 2, "second" );
// 2 秒後

Would you like to submit a PR updating docs?