document bundled locales and how to use them

Readme.md

@@ -31,7 +31,7 @@ The New API in 0.9
 
 The current version, 0.9, deprecates the older API that exported several functions: `strftimeTZ`, `strftimeUTC`, and `localizedStrftime`. In addition to this the exported function referenced itself as `require('strftime').strftime` or `window.strftime.strftime` for consistency with the other functions. *These functions are deprecated in 0.9 and will be removed in 1.0.*
 
-Now you only need the single object exported and you can create a specialized version of it using the functions `utc()`, `localize(locale)`, and `timezone(offset)`. You can no longer pass in a timezone or locale on each call to `strftime` which is a regression. If you need this let me know and we will add it back into the API.
+Now you only need the single object exported and you can create a specialized version of it using the functions `utc()`, `localize(locale)`, `localizeByIdentifier(identifier)`, and `timezone(offset)`. You can no longer pass in a timezone or locale on each call to `strftime` which is a regression. If you need this let me know and we will add it back into the API.
 
 [More details are available in the changelog](https://github.com/samsonjs/strftime/blob/master/Changelog.md).
 
@@ -75,6 +75,17 @@ If you want to localize it:
     console.log(strftimeIT('%B %d, %Y %H:%M:%S', new Date(1307472705067))) // => giugno 7, 2011 18:51:45
 ```
 
+Some locales are bundled and can be used like so:
+
+```JavaScript
+    var strftime = require('strftime') // not required in browsers
+    var strftimeIT = strftime.localizeByIdentifier('it_IT')
+    console.log(strftimeIT('%B %d, %Y %H:%M:%S')) // => aprile 28, 2011 18:21:08
+    console.log(strftimeIT('%B %d, %Y %H:%M:%S', new Date(1307472705067))) // => giugno 7, 2011 18:51:45
+```
+
+_The [full list of bundled locales](#locales) is below._
+
 Time zones can be passed in as an offset from GMT in minutes.
 
 ```JavaScript
@@ -108,11 +119,11 @@ e.g. `%q` becomes `q`. Use `%%` to get a literal `%` sign.
 - B: full month name
 - b: abbreviated month name
 - C: AD century (year / 100), padded to 2 digits
-- c: equivalent to `%a %b %d %X %Y` in en-US (based on locale)
+- c: equivalent to `%a %b %d %X %Y %Z` in en_US (based on locale)
-- D: equivalent to `%m/%d/%y` in en-US (based on locale)
+- D: equivalent to `%m/%d/%y` in en_US (based on locale)
 - d: day of the month, padded to 2 digits (01-31)
 - e: day of the month, padded with a leading space for single digit values (1-31)
-- F: equivalent to `%Y-%m-%d` in en-US (based on locale)
+- F: equivalent to `%Y-%m-%d` in en_US (based on locale)
 - H: the hour (24-hour clock), padded to 2 digits (00-23)
 - h: the same as %b (abbreviated month name)
 - I: the hour (12-hour clock), padded to 2 digits (01-12)
@@ -126,19 +137,19 @@ e.g. `%q` becomes `q`. Use `%%` to get a literal `%` sign.
 - o: day of the month as an ordinal (without padding), e.g. 1st, 2nd, 3rd, 4th, ...
 - P: "am" or "pm" in lowercase (Ruby extension, based on locale)
 - p: "AM" or "PM" (based on locale)
-- R: equivalent to `%H:%M` in en-US (based on locale)
+- R: equivalent to `%H:%M` in en_US (based on locale)
-- r: equivalent to `%I:%M:%S %p` in en-US (based on locale)
+- r: equivalent to `%I:%M:%S %p` in en_US (based on locale)
 - S: the second, padded to 2 digits (00-60)
 - s: the number of seconds since the Epoch, UTC
-- T: equivalent to `%H:%M:%S` in en-US (based on locale)
+- T: equivalent to `%H:%M:%S` in en_US (based on locale)
 - t: tab character
 - U: week number of the year, Sunday as the first day of the week, padded to 2 digits (00-53)
 - u: the weekday, Monday as the first day of the week (1-7)
-- v: equivalent to `%e-%b-%Y` in en-US (based on locale)
+- v: equivalent to `%e-%b-%Y` in en_US (based on locale)
 - W: week number of the year, Monday as the first day of the week, padded to 2 digits (00-53)
 - w: the weekday, Sunday as the first day of the week (0-6)
-- X: equivalent to `%D` in en-US (based on locale)
+- X: equivalent to `%D` in en_US (based on locale)
-- x: equivalent to `%T` in en-US (based on locale)
+- x: equivalent to `%T` in en_US (based on locale)
 - Y: the year with the century
 - y: the year without the century (00-99)
 - Z: the time zone name, replaced with an empty string if it is not found
@@ -150,6 +161,22 @@ For more detail see `man 3 strftime` as the format specifiers should behave iden
 
 Any specifier can be modified with `-`, `_`, `0`, or `:` as well, as in Ruby. Using `%-` will omit any leading zeroes or spaces, `%_` will force spaces for padding instead of the default, and `%0` will force zeroes for padding. There's some redundancy here as `%-d` and `%e` have the same result, but it solves some awkwardness with formats like `%l`. Using `%:` for time zone offset, as in `%:z` will insert a colon as a delimiter.
 
+<a name="locales"></a>
+Bundled Locales
+===============
+
+  - de\_DE
+  - en\_CA
+  - en\_US
+  - es\_MX
+  - fr\_FR
+  - it\_IT
+  - nl\_NL
+  - pt\_BR
+  - ru\_RU
+  - tr\_TR
+  - zh\_CN
+
 Contributors
 ============