The CLDR data set only includes 4 specific date formats, full, long, medium, and short, so you'll have to choose amongst them for the one that best fits your needs. Yes, it's limiting, but the 4 formats get the job done most of the time :)

Behind the scenes, these convenience methods are creating instances of LocalizedDate, LocalizedTime, and LocalizedDateTime. You can do the same thing if you're feeling adventurous:

Relative Dates and Times

In addition to formatting full dates and times, TwitterCLDR supports relative time spans via several convenience methods and the LocalizedTimespan class. TwitterCLDR tries to guess the best time unit (eg. days, hours, minutes, etc) based on the length of the time span. Unless otherwise specified, TwitterCLDR will use the current date and time as the reference point for the calculation.

Behind the scenes, these convenience methods are creating instances of LocalizedTimespan, whose constructor accepts a number of seconds as the first argument. You can do the same thing if you're feeling adventurous:

Plural Rules

Some languages, like English, have "countable" nouns. You probably know this concept better as "plural" and "singular", i.e. the difference between "strawberry" and "strawberries". Other languages, like Russian, have three plural forms: one (numbers ending in 1), few (numbers ending in 2, 3, or 4), and many (everything else). Still other languages like Japanese don't use countable nouns at all.

TwitterCLDR makes it easy to find the plural rules for any numeric value:

Behind the scenes, these convenience methods use the TwitterCldr::Formatters::Plurals::Rules class. You can do the same thing (and a bit more) if you're feeling adventurous:

# get all rules for the default localeTwitterCldr::Formatters::Plurals::Rules.all # [:one, ... ]# get all rules for a specific localeTwitterCldr::Formatters::Plurals::Rules.all_for(:es) # [:one, :other]TwitterCldr::Formatters::Plurals::Rules.all_for(:ru) # [:one, :few, :many, :other]# get the rule for a number in a specific localeTwitterCldr::Formatters::Plurals::Rules.rule_for(1, :ru) # :oneTwitterCldr::Formatters::Plurals::Rules.rule_for(2, :ru) # :few

Plurals

In addition to providing access to plural rules, TwitterCLDR allows you to embed plurals directly in your source code:

NOTE: If you're using TwitterCLDR with Rails 3, you may see an error if you try to use the % function on a localized string in your views. Strings in views in Rails 3 are instances of SafeBuffer, which patches the gsub method that the TwitterCLDR plural formatter relies on. To fix this issue, simply call to_str on any SafeBuffer before calling localize. More info here. An example:

When you pass a Hash as an argument and specify placeholders with %<foo>d, TwitterCLDR will interpret the hash values as named arguments and format the string according to the instructions appended to the closing >. In this way, TwitterCLDR supports both Ruby 1.8 and 1.9 interpolation syntax in the same string:

Normalize/decompose a Unicode string (NFD, NFKD, NFC, and NFKC implementations available). Note that the normalized string will almost always look the same as the original string because most character display systems automatically combine decomposed characters.

Sorting (Collation)

TwitterCLDR contains an implementation of the Unicode Collation Algorithm (UCA) that provides language-sensitive text sorting capabilities. Conveniently, all you have to do is use the sort method in combination with the familiar localize method. Notice the difference between the default Ruby sort, which simply compares bytes, and the proper language-aware sort from TwitterCLDR in this German example:

Note: The TwitterCLDR collator does not currently pass all the collation tests provided by Unicode, but for some strange reasons. See the summary of these discrepancies if you're curious.

About Twitter-specific Locales

Twitter tries to always use BCP-47 language codes. Data from the CLDR doesn't always match those codes however, so TwitterCLDR provides a convert_locale method to convert between the two. All functionality throughout the entire gem defers to convert_locale before retrieving CLDR data. convert_locale supports Twitter-supported BCP-47 language codes as well as CLDR locale codes, so you don't have to guess which one to use. Here are a few examples:

There are a few functions in TwitterCLDR that don't require a locale code, and instead use the default locale by calling TwitterCldr.get_locale. The get_locale function defers to FastGettext.locale when the FastGettext library is available, and falls back on :en (English) when it's not. (Twitter uses the FastGettext gem to retrieve translations efficiently in Ruby).

Requirements

No external requirements.

Running Tests

bundle exec rake will run our basic test suite suitable for development. To run the full test suite, use bundle exec rake spec:full. The full test suite takes considerably longer to run because it runs against the complete normalization and collation test files from the Unicode Consortium. The basic test suite only runs normalization and collation tests against a small subset of the complete test file.

JavaScript Support

Generating the JavaScript

You can automatically generate the JavaScript version of TwitterCLDR using this Rubygem. Here's the one-liner:

bundle exec rake js:build OUTPUT_DIR=/path/to/desired/output/location

If you'd like to customize the generated output further, you'll need to require the TwitterCldr::Js namespace. You can choose the locales to export and whether to export a minified version alongside the full version for each locale.