repository·master·Indexed 20 days ago
https://github.com/twitter/twitter-cldr-rbA Ruby library that uses Unicode's Common Locale Data Repository (CLDR) to provide localized formatting for dates, times, currencies, decimals, percentages, and symbols. It includes tools for pluralization, relative time formatting, Unicode normalization, casefolding, and language/territory code conversion.
TwitterCldr leverages Unicode's Common Locale Data Repository (CLDR) to provide localized formatting for various text types. It is designed to transform data into its culturally appropriate equivalent based on locale. Supported text types include:
If the library does not support a specific locale you need, you can add it by running the add_locale rake task. This process requires an internet connection to download CLDR, ICU, and Unicode data files. You must run the task under both MRI and JRuby.
Using Rake: Run the task passing the locale in square brackets:
bundle exec rake add_locale[bo]Using the helper script:
If you use rbenv or rvm, it is recommended to use the add_locale.sh script, which automates the installation of required Ruby versions and executes the rake tasks:
./script/add_locale.sh boYou can handle complex pluralization in strings using two methods:
%<...> syntax.Note for Rails 3 users: If using localized strings in views, call .to_str before .localize to avoid errors with SafeBuffer objects.
# Method 1: Replacement Hash
replacements = {
:horse_count => 3,
:horses => {
:one => "is 1 horse",
:other => "are %{horse_count} horses"
}
}
"there %{horse_count:horses} in the barn".localize % replacements
# Method 2: JSON Embedding
str = 'there %<{ "horse_count": { "one": "is one horse", "other": "are %{horse_count} horses" } }> in the barn'
str.localize % { :horse_count => 3 }
# Rails 3 Fix
'%<{"count": {"one": "only one", "other": "tons more!"}}'.to_str.localize % { :count => 2 }To use TwitterCldr for localized text formatting, install the gem using the following command:
gem install twitter_cldrYou can break strings into sentences using the LocalizedString#each_sentence method or the TwitterCldr::Segmentation::BreakIterator class.
To improve accuracy for special cases like abbreviations (e.g., "Mr.", "Ms."), enable the :use_uli_exceptions option in the BreakIterator.
# Using LocalizedString
"The. Quick. Brown. Fox.".localize.each_sentence do |sentence|
puts sentence.to_s # "The. ", "Quick. ", "Fox."
end
# Using BreakIterator directly with ULI exceptions
iterator = TwitterCldr::Segmentation::BreakIterator.new(:en, :use_uli_exceptions => true)
iterator.each_sentence("I like Ms. Murphy, she's nice.") do |sentence|
puts sentence # "I like Ms. Murphy, she's nice."
endYou can abbreviate or expand number notation using the format option within #to_decimal.
:short: Abbreviates notation (e.g., "1M" for 1,000,000).:long: Uses full notation (e.g., "1 million").2337.localize.to_decimal.to_s(format: :short) # "2K"
1337123.localize.to_decimal.to_s(format: :short) # "1M"
2337.localize.to_decimal.to_s(format: :long) # "2 thousand"
1337123.localize.to_decimal.to_s(format: :long) # "1 million"Use the localize(locale).plural_rule method on a number to find its grammatical plural category (e.g., :one, :few, :many, :other) for a specific language. You can also use TwitterCldr::Formatters::Plurals::Rules to inspect all rules for a locale or find a specific rule for a number.
# Get rule for a number
1.localize(:ru).plural_rule # :one
2.localize(:ru).plural_rule # :few
5.localize(:ru).plural_rule # :many
10.0.localize(:ru).plural_rule # :other
# Inspecting rules via Rules class
TwitterCldr::Formatters::Plurals::Rules.all # [:one, :other]
TwitterCldr::Formatters::Plurals::Rules.all_for(:ru) # [:one, :few, :many, :other]
TwitterCldr::Formatters::Plurals::Rules.rule_for(1, :ru) # :oneThe TwitterCldr::Shared::TerritoriesContainment API allows you to determine relationships between territories (e.g., finding parents or children of a territory) based on UN M.49 standards. You can also use the Territory class or the to_territory method on a LocalizedString.
Key methods:
children(territory_code): Returns a list of child territories.parents(territory_code): Returns a list of parent territories.contains?(parent_code, child_code): Returns true if the parent contains the child.# Using the containment API directly
TwitterCldr::Shared::TerritoriesContainment.children('151') # ["BG", "BY", ...]
TwitterCldr::Shared::TerritoriesContainment.parents('013') # ["003", "019", "419"]
TwitterCldr::Shared::TerritoriesContainment.contains?('151', 'RU') # true
# Using the Territory class
TwitterCldr::Shared::Territory.new("013").parents # ["003", "019", "419"]
# Using LocalizedString
'419'.localize.to_territory.contains?('BZ') # trueTo ensure Ruby symbols and Unicode characters are dumped correctly in YAML, use the TwitterCLDR YAML dumper. You can call .localize.to_yaml on an Array, Hash, or String, or use the TwitterCldr::Shared::YAML.dump method directly.
# Using convenience methods
{ :hello => "world" }.localize.to_yaml
# Using the Shared::YAML class
TwitterCldr::Shared::YAML.dump({ :hello => "world" })Transliteration converts text from one script to another (e.g., Japanese Hiragana to Latin) to preserve pronunciation.
LocalizedString#transliterate_into(target_locale). You can provide hints by specifying source and target scripts (e.g., :ja_Hiragana to :en_Latin).TwitterCldr::Transforms::Transformer. You must provide an exact transform ID. Use Transformer.each_transform to list available IDs or TwitterCldr::Transforms::TransformId.find(source, target) to find the best matching ID for a locale pair.# High-level transliteration
"くろねこさま".localize.transliterate_into(:en) # "kuronekosama"
"くろねこさま".localize(:ja_Hiragana).transliterate_into(:en_Latin) # "kuronekosama"
# Low-level Transformer usage
id = TwitterCldr::Transforms::TransformId.find('ja_Hiragana', 'en')
rule_set = TwitterCldr::Transforms::Transformer.get(id)
rule_set.transform('くろねこさま') # "kuronekosama"TwitterCLDR supports Time, DateTime, and Date objects.
Convenience methods provide four standard formats: #to_full_s, #to_long_s, #to_medium_s, and #to_short_s.
CLDR supports many locale-specific formats beyond the standard four.
#additional_formats to get a list of available format strings for a locale.#to_additional_s(format_string) to apply a specific format.Note: If an exact match for a format isn't available in a locale, TwitterCLDR will attempt to approximate it.
# Standard formats
DateTime.now.localize(:es).to_full_s # "viernes, 14 de febrero de 2014, 12:20:05 (tiempo universal coordinado)"
DateTime.now.localize(:es).to_short_s # "14/2/14, 12:20"
# Additional formats
# Returns list like: ["Bh", "Bhm", "E", ...]
DateTime.now.localize(:ja).additional_formats
# Using an additional format
# "14日金曜日"
DateTime.now.localize(:ja).to_additional_s("EEEEd")Functions that do not explicitly require a locale code will use the default locale provided by TwitterCldr.locale.
TwitterCldr.get_locale returns the current locale (defaults to :en if FastGettext is not present).fast_gettext gem is available, TwitterCldr.locale defers to FastGettext.locale.Example of setting the locale via FastGettext:
require 'fast_gettext'
FastGettext.locale = "ru"
TwitterCldr.locale # will return :ru