Class: ICU4X::Locale

Inherits:
Object
  • Object
show all
Defined in:
lib/icu4x.rb,
lib/icu4x/yard_docs.rb

Overview

Represents a Unicode Locale Identifier (BCP 47).

Locale provides parsing and access to locale components such as language, script, region, and extensions.

Examples:

Parse a locale identifier

locale = ICU4X::Locale.parse("ja-JP")
locale.language  #=> "ja"
locale.region    #=> "JP"

Parse a POSIX locale

locale = ICU4X::Locale.parse_posix("ja_JP.UTF-8")
locale.language  #=> "ja"

See Also:

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.from_env(category: :messages) ⇒ Locale

Creates a Locale from environment variables.

Checks LC_ALL, LC_category, and LANG in order, parsing each as a POSIX locale. Falls back to “C” if none are valid.

Parameters:

  • category (Symbol) (defaults to: :messages) —

    POSIX locale category (default: :messages)

Returns:

Raises:

  • (ArgumentError) —

    if category is not a valid POSIX category



104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
 
# File 'lib/icu4x.rb', line 104

def self.from_env(category: :messages)
  unless POSIX_CATEGORIES.include?(category)
    raise ArgumentError, "unknown locale category: #{category.inspect}"
  end

  env_name = "LC_#{category.to_s.upcase}"
  [ENV["LC_ALL"], ENV[env_name], ENV["LANG"]].each do |value|
    next if value.nil? || value.empty?

    return parse_posix(value)
  rescue LocaleError
    next
  end
  parse_posix("C")
end

.parse(locale_str) ⇒ Locale

Parses a BCP 47 locale identifier string.

Examples:

locale = ICU4X::Locale.parse("en-US")
locale = ICU4X::Locale.parse("ja-JP-u-ca-japanese")

Parameters:

  • locale_str (String) —

    a BCP 47 locale identifier (e.g., “en-US”, “ja-JP-u-ca-japanese”)

Returns:

  • (Locale) —

    a new Locale instance

Raises:



186
 
# File 'lib/icu4x/yard_docs.rb', line 186

def self.parse(locale_str); end

.parse_posix(posix_str) ⇒ Locale

Parses a POSIX locale string.

Converts POSIX-style locale identifiers (e.g., “ja_JP.UTF-8”) to Unicode locale format.

Examples:

locale = ICU4X::Locale.parse_posix("ja_JP.UTF-8")
locale.language  #=> "ja"
locale.region    #=> "JP"

Parameters:

  • posix_str (String) —

    a POSIX locale string

Returns:

  • (Locale) —

    a new Locale instance

Raises:



202
 
# File 'lib/icu4x/yard_docs.rb', line 202

def self.parse_posix(posix_str); end

Instance Method Details

#==(other) ⇒ Boolean

Compares two locales for equality.

Parameters:

  • other (Locale) —

    the locale to compare with

Returns:

  • (Boolean) —

    true if the locales are equal



256
 
# File 'lib/icu4x/yard_docs.rb', line 256

def ==(other); end

#eql?(other) ⇒ Boolean

Compares two locales for equality (used by Hash).

Parameters:

  • other (Locale) —

    the locale to compare with

Returns:

  • (Boolean) —

    true if the locales are equal



128
 
# File 'lib/icu4x.rb', line 128

def eql?(other) = self == other

#extensions ⇒ Hash

Returns the locale extensions.

Examples:

locale = ICU4X::Locale.parse("ja-JP-u-ca-japanese")
locale.extensions[:unicode]  #=> {"ca" => "japanese"}

Returns:

  • (Hash) —

    a hash containing extension data with keys:

    • ‘:unicode` [Hash<String, String>] Unicode extension key-value pairs

    • ‘:transform` [String, nil] Transform extension string

    • ‘:private` [Array<String>] Private use extensions



237
 
# File 'lib/icu4x/yard_docs.rb', line 237

def extensions; end

#hash ⇒ Integer

Returns the hash code for this locale.

Returns:

  • (Integer) —

    hash code



124
 
# File 'lib/icu4x.rb', line 124

def hash = to_s.hash

#inspect ⇒ String

Returns a human-readable representation for debugging.

Returns:

  • (String) —

    debug representation



121
 
# File 'lib/icu4x.rb', line 121

def inspect = "#<ICU4X::Locale:#{self}>"

#language ⇒ String?

Returns the language subtag.

Returns:

  • (String, nil) —

    the language subtag (e.g., “en”, “ja”), or nil if not set



208
 
# File 'lib/icu4x/yard_docs.rb', line 208

def language; end

#maximize ⇒ Locale

Returns a new locale with likely subtags added.

Non-destructive version of #maximize!. The original locale is unchanged.

Examples:

locale = ICU4X::Locale.parse("zh")
expanded = locale.maximize
locale.to_s    #=> "zh" (unchanged)
expanded.to_s  #=> "zh-Hans-CN"

Returns:

  • (Locale) —

    a new locale with likely subtags added



303
 
# File 'lib/icu4x/yard_docs.rb', line 303

def maximize; end

#maximize! ⇒ self?

Maximizes the locale in place using the Add Likely Subtags algorithm (UTS #35).

Adds likely script and region subtags based on the language. This is useful for language negotiation.

Examples:

locale = ICU4X::Locale.parse("en")
locale.maximize!  #=> locale
locale.to_s       #=> "en-Latn-US"

Already maximized

locale = ICU4X::Locale.parse("en-Latn-US")
locale.maximize!  #=> nil

Returns:

  • (self, nil) —

    self if the locale was modified, nil if already maximized

See Also:



289
 
# File 'lib/icu4x/yard_docs.rb', line 289

def maximize!; end

#minimize ⇒ Locale

Returns a new locale with redundant subtags removed.

Non-destructive version of #minimize!. The original locale is unchanged.

Examples:

locale = ICU4X::Locale.parse("zh-Hans-CN")
minimal = locale.minimize
locale.to_s   #=> "zh-Hans-CN" (unchanged)
minimal.to_s  #=> "zh"

Returns:

  • (Locale) —

    a new locale with redundant subtags removed



337
 
# File 'lib/icu4x/yard_docs.rb', line 337

def minimize; end

#minimize! ⇒ self?

Minimizes the locale in place using the Remove Likely Subtags algorithm (UTS #35).

Removes redundant script and region subtags that can be inferred. This is useful for language negotiation.

Examples:

locale = ICU4X::Locale.parse("ja-Jpan-JP")
locale.minimize!  #=> locale
locale.to_s       #=> "ja"

Already minimal

locale = ICU4X::Locale.parse("en")
locale.minimize!  #=> nil

Returns:

  • (self, nil) —

    self if the locale was modified, nil if already minimal

See Also:



323
 
# File 'lib/icu4x/yard_docs.rb', line 323

def minimize!; end

#region ⇒ String?

Returns the region subtag.

Returns:

  • (String, nil) —

    the region subtag (e.g., “US”, “JP”), or nil if not set



224
 
# File 'lib/icu4x/yard_docs.rb', line 224

def region; end

#script ⇒ String?

Returns the script subtag.

Examples:

locale = ICU4X::Locale.parse("zh-Hant-TW")
locale.script  #=> "Hant"

Returns:

  • (String, nil) —

    the script subtag (e.g., “Latn”, “Jpan”), or nil if not set



218
 
# File 'lib/icu4x/yard_docs.rb', line 218

def script; end

#to_s ⇒ String

Returns the string representation of the locale.

Returns:

  • (String) —

    the normalized BCP 47 locale identifier



243
 
# File 'lib/icu4x/yard_docs.rb', line 243

def to_s; end