russian 0.2.7 → 1.0.0

data/lib/russian.rb

@@ -1,119 +1,398 @@
-# -*- encoding: utf-8 -*- 
+# frozen_string_literal: true
 
-if RUBY_VERSION < "1.9"
-  $KCODE = 'u'
-end
-
-$:.push File.join(File.dirname(__FILE__), 'russian')
-require 'transliteration'
+require "date"
+require "i18n"
+require "time"
 
-# I18n require
-unless defined?(I18n)
-  $:.push File.join(File.dirname(__FILE__), 'vendor', 'i18n', 'lib')
-  require 'i18n'
-end
-# Advanced backend
-require 'backend/advanced'
-
-# Rails hacks
-require 'active_record_ext/custom_error_message' if defined?(ActiveRecord)
-if defined?(ActionView::Helpers)
-  require 'action_view_ext/helpers/date_helper' 
-  require 'vendor/i18n_label/init'
-end
-require 'active_support_ext/parameterize' if defined?(ActiveSupport::Inflector)
+require_relative "russian/russian_rails"
+require_relative "russian/strptime"
+require_relative "russian/transliteration"
+require_relative "russian/version"
 
+# Russian language support for Ruby: I18n helpers and Rails integration.
+#
+# The module wraps common gem `I18n` operations, adds its own helpers,
+# and installs Rails-specific patches when Rails is detected.
+#
+# Don't forget to check `README`!
+#
+#
+# Поддержка русского языка для Ruby: библиотеки I18n и интеграция с Rails.
+#
+# Модуль оборачивает типичные операции gem'а `I18n`, добавляет свои,
+# и устанавливает Rails-специфичные патчи, если обнаружен Rails.
+#
+# Не забудьте прочитать `README`!
+#
+# @example
+#   require "russian"
+#   Russian.t(:"date.formats.default")
+#   Russian.l(Date.new(1985, 12, 1), format: :long)
+#   Russian.translit("Привет")
 module Russian
-  extend self
-  
-  module VERSION
-    MAJOR = 0
-    MINOR = 2
-    TINY  = 7
-
-    STRING = [MAJOR, MINOR, TINY].join('.')
-  end
-  
-  # Russian locale
-  LOCALE = :'ru'
+  # Locale used by the gem.
+  #
+  #
+  # Локаль, которую использует gem.
+  #
+  # @return [Symbol] Russian locale identifier.
+  #   Идентификатор русской локали.
+  LOCALE = :ru
 
-  # Russian locale
-  def locale
-    LOCALE
-  end
-  
-  # Returns custom backend class for usage with Russian library
-  # 
-  # See I18n::Backend
-  def i18n_backend_class
-    I18n::Backend::Advanced
-  end
-  
-  # Init Russian i18n: set custom backend, set default locale to Russian locale, load all translations
-  # shipped with library.
-  def init_i18n
-    I18n.backend = Russian.i18n_backend_class.new
-    I18n.default_locale = LOCALE
-    I18n.load_path.unshift(*locale_files)
-  end
+  # @private
+  LOCALIZE_ABBR_MONTH_NAMES_MATCH = /(%[-_0^#:]*(\d+)*[EO]?d|%[-_0^#:]*(\d+)*[EO]?e)(.*)(%b)/
+  # @private
+  LOCALIZE_MONTH_NAMES_MATCH = /(%[-_0^#:]*(\d+)*[EO]?d|%[-_0^#:]*(\d+)*[EO]?e)(.*)(%B)/
+  # @private
+  LOCALIZE_STANDALONE_ABBR_DAY_NAMES_MATCH = /^%a/
+  # @private
+  LOCALIZE_STANDALONE_DAY_NAMES_MATCH = /^%A/
+  # @private
+  STRPTIME_DIRECTIVE_MODIFIERS = "-_0^#:"
 
-  # See I18n::translate
-  def translate(key, options = {})
-    I18n.translate(key, options.merge({ :locale => LOCALE }))
-  end        
-  alias :t :translate
-  
-  # See I18n::localize
-  def localize(object, options = {})
-    I18n.localize(object, options.merge({ :locale => LOCALE }))
-  end
-  alias :l :localize
-  
-  # strftime() proxy with Russian localization
-  def strftime(object, format = :default)
-    localize(object, { :format => format })
-  end
-  
-  # Simple pluralization proxy
-  #
-  # Usage: 
-  #   Russian.pluralize(1, "вещь", "вещи", "вещей")
-  #   Russian.pluralize(3.14, "вещь", "вещи", "вещей", "вещи")
-  def pluralize(n, *variants)
-    raise ArgumentError, "Must have a Numeric as a first parameter" unless n.is_a?(Numeric)
-    raise ArgumentError, "Must have at least 3 variants for pluralization" if variants.size < 3
-    raise ArgumentError, "Must have at least 4 variants for pluralization" if (variants.size < 4 && n != n.round)
-    variants_hash = pluralization_variants_to_hash(*variants)
-    I18n.backend.send(:pluralize, LOCALE, variants_hash, n)
-  end
-  alias :p :pluralize
+  class << self
+    # Returns the locale used by the gem.
+    #
+    #
+    # Возвращает локаль, которую использует gem.
+    #
+    # @return [Symbol] Russian locale identifier.
+    #   Идентификатор русской локали.
+    #
+    # @example
+    #   Russian.locale
+    #   # => :ru
+    def locale
+      LOCALE
+    end
 
-  # Transliteration for russian language
-  #
-  # Usage:
-  #  Russian.translit("рубин")
-  #  Russian.transliterate("рубин")
-  def transliterate(str)
-    Russian::Transliteration.transliterate(str)
-  end
-  alias :translit :transliterate
-  
-  protected
-    # Returns all locale files shipped with library
+    # Installs Russian locale files into `I18n` and reloads the I18n backend.
+    #
+    # The method is safe to call repeatedly. It prepends this gem's locale
+    # files to `I18n.load_path`, enables pluralization and transliteration
+    # backends, and then calls `I18n.reload!`.
+    #
+    #
+    # Подключает файлы русской локали к `I18n` и перезагружает backend I18n.
+    #
+    # Метод безопасно вызывать повторно. Он добавляет locale-файлы gem'а в
+    # начало `I18n.load_path`, включает backend'ы pluralization и
+    # transliteration, а затем вызывает `I18n.reload!`.
+    #
+    # @return [void]
+    #
+    # @example
+    #   I18n.load_path.clear
+    #   Russian.init_i18n
+    #   I18n.t(:"date.month_names", locale: :ru)
+    def init_i18n
+      backend = I18n::Backend::Simple
+
+      backend.include(I18n::Backend::Pluralization)
+      backend.include(I18n::Backend::Transliterator)
+
+      I18n.load_path = locale_files + (I18n.load_path - locale_files)
+      I18n.reload!
+    end
+
+    # Translates a key using the Russian locale by default.
+    #
+    # Both the legacy positional hash and modern keyword arguments are
+    # supported.
+    #
+    #
+    # Переводит ключ, по умолчанию используя русскую локаль.
+    #
+    # Поддерживаются и устаревший positional hash, и современные
+    # keyword-аргументы.
+    #
+    # @param key [String, Symbol] Translation key.
+    #   Ключ перевода.
+    # @param options [Hash, nil] Legacy positional I18n options hash.
+    #   Устаревший positional hash с опциями I18n.
+    # @param kwargs [Hash] Keyword I18n options.
+    #   Keyword-опции I18n.
+    # @return [Object] Translation result returned by `I18n`.
+    #   Результат перевода, возвращаемый `I18n`.
+    # @raise [ArgumentError] if `options` is not a hash.
+    #   Если `options` не является hash'ем.
+    #
+    # @example
+    #   Russian.translate(:"date.formats.default")
+    #   Russian.translate(:"date.formats.default", scope: :foo)
+    #   Russian.translate(:"date.formats.default", {scope: :foo})
+    def translate(key, options = nil, **kwargs)
+      I18n.translate(key, **normalize_i18n_options(options, kwargs, locale: LOCALE))
+    end
+    alias_method :t, :translate
+
+    # @!method t(key, options = nil, **kwargs)
+    #   Alias for {.translate}.
+    #
+    #
+    #   Псевдоним для {.translate}.
+    #
+    #   @see .translate
+
+    # Localizes an object using the Russian locale by default.
+    #
+    # Both the legacy positional hash and modern keyword arguments are
+    # supported.
+    #
+    #
+    # Локализует объект, по умолчанию используя русскую локаль.
+    #
+    # Поддерживаются и устаревший positional hash, и современные
+    # keyword-аргументы.
+    #
+    # @param object [Object] Localizable object, usually `Date`, `Time`, or `DateTime`.
+    #   Локализуемый объект, обычно `Date`, `Time` или `DateTime`.
+    # @param options [Hash, nil] Legacy positional I18n options hash.
+    #   Устаревший positional hash с опциями I18n.
+    # @param kwargs [Hash] Keyword I18n options.
+    #   Keyword-опции I18n.
+    # @return [String] Localized string.
+    #   Локализованная строка.
+    # @raise [ArgumentError] if `options` is not a hash.
+    #   Если `options` не является hash'ем.
+    #
+    # @example
+    #   Russian.localize(Date.new(1985, 12, 1), format: :long)
+    #   Russian.localize(Date.new(1985, 12, 1), {format: :long})
+    def localize(object, options = nil, **kwargs)
+      I18n.localize(object, **normalize_i18n_options(options, kwargs, locale: LOCALE))
+    end
+    alias_method :l, :localize
+
+    # @!method l(object, options = nil, **kwargs)
+    #   Alias for {.localize}.
+    #
+    #
+    #   Псевдоним для {.localize}.
+    #
+    #   @see .localize
+
+    # Localizes an object using a `strftime`-style format identifier.
+    #
+    # `Russian.strftime(time, :long)` and
+    # `Russian.strftime(time, format: :long)` are both supported.
+    #
+    #
+    # Локализует объект, используя идентификатор формата в стиле `strftime`.
+    #
+    # Поддерживаются форматы `Russian.strftime(time, :long)` и
+    # `Russian.strftime(time, format: :long)`.
+    #
+    # @param object [Object] Localizable object.
+    #   Локализуемый объект.
+    # @param format [Symbol, Hash] Format name or legacy options hash.
+    #   Имя формата или устаревший hash с опциями.
+    # @param kwargs [Hash] Keyword I18n options.
+    #   Keyword-опции I18n.
+    # @return [String] Localized string.
+    #   Локализованная строка.
+    # @raise [ArgumentError] if a legacy options argument is not a hash.
+    #   Если устаревший аргумент с опциями не является hash'ем.
+    #
+    # @example
+    #   Russian.strftime(Time.new(2008, 9, 1, 11, 12, 43, "+03:00"), :long)
+    #   Russian.strftime(Time.new(2008, 9, 1, 11, 12, 43, "+03:00"), format: :long)
+    def strftime(object, format = :default, **kwargs)
+      options =
+        if format.is_a?(Hash)
+          normalize_i18n_options(format, kwargs)
+        else
+          normalize_i18n_options({format: format}, kwargs)
+        end
+
+      localize(object, **options)
+    end
+
+    # Parses a localized Russian date string with `Date.strptime`.
+    #
+    # The method understands Russian month and weekday names, normalizes them
+    # to the English names expected by Ruby's parser, and then delegates to
+    # `Date.strptime`. All non-localized directives are still handled by the
+    # native Ruby parser.
+    #
+    #
+    # Разбирает локализованную русскую строку даты через `Date.strptime`.
+    #
+    # Метод понимает русские названия месяцев и дней недели, нормализует их
+    # к английским именам, которые ожидает стандартный parser Ruby, а затем
+    # делегирует работу в `Date.strptime`. Все остальные директивы по-прежнему
+    # обрабатываются нативным parser'ом Ruby.
+    #
+    # @param string [String] Localized date string.
+    #   Локализованная строка даты.
+    # @param format [String] Optional `strptime` format string.
+    #   Строка формата `strptime`.
+    # @return [Date] Parsed date.
+    #   Разобранная дата.
+    #
+    # @example
+    #   Russian.date_strptime("01 апреля 2011", "%d %B %Y")
+    #   # => #<Date: 2011-04-01 ...>
+    def date_strptime(string, format = "%F")
+      Strptime.date_strptime(string, format)
+    end
+
+    # Parses a localized Russian date/time string with `Time.strptime`.
+    #
+    # The method uses the same Russian textual token normalization as
+    # {.date_strptime}, then delegates to `Time.strptime`.
+    #
+    #
+    # Разбирает локализованную русскую строку даты и времени через
+    # `Time.strptime`.
+    #
+    # Метод использует ту же нормализацию русских текстовых токенов, что и
+    # {.date_strptime}, а затем делегирует работу в `Time.strptime`.
+    #
+    # @param string [String] Localized date/time string.
+    #   Локализованная строка даты и времени.
+    # @param format [String] `strptime` format string.
+    #   Строка формата `strptime`.
+    # @param now [Time] Optional base time passed to `Time.strptime`.
+    #   Базовое значение времени, передаваемое в `Time.strptime`.
+    # @return [Time] Parsed time.
+    #   Разобранное время.
+    #
+    # @example
+    #   Russian.time_strptime("01 апреля 2011 23:45:05 +0300", "%d %B %Y %H:%M:%S %z")
+    #   # => 2011-04-01 23:45:05 +0300
+    def time_strptime(string, format, now = Time.now)
+      Strptime.time_strptime(string, format, now)
+    end
+
+    # Parses a localized Russian date/time string with `DateTime.strptime`.
+    #
+    # The method uses the same Russian textual token normalization as
+    # {.date_strptime}, then delegates to `DateTime.strptime`.
+    #
+    #
+    # Разбирает локализованную русскую строку даты и времени через
+    # `DateTime.strptime`.
+    #
+    # Метод использует ту же нормализацию русских текстовых токенов, что и
+    # {.date_strptime}, а затем делегирует работу в `DateTime.strptime`.
+    #
+    # @param string [String] Localized date/time string.
+    #   Локализованная строка даты и времени.
+    # @param format [String] Optional `strptime` format string.
+    #   Строка формата `strptime`.
+    # @return [DateTime] Parsed datetime.
+    #   Разобранный `DateTime`.
+    #
+    # @example
+    #   Russian.datetime_strptime("01 апреля 2011 23:45:05 +0300", "%d %B %Y %H:%M:%S %z")
+    #   # => #<DateTime: 2011-04-01T23:45:05+03:00 ...>
+    def datetime_strptime(string, format = "%FT%T%z")
+      Strptime.datetime_strptime(string, format)
+    end
+
+    # Returns the correct Russian plural form for a numeric value.
+    #
+    # For integers, three variants are required: `one`, `few`, and `many`.
+    # For non-integer numbers, a fourth `other` variant is also required.
+    #
+    #
+    # Возвращает правильную русскую форму множественного числа для
+    # числового значения.
+    #
+    # Для целых чисел нужны три варианта: `one`, `few` и `many`.
+    # Для дробных чисел дополнительно нужен четвертый вариант `other`.
+    #
+    # @param n [Numeric] Number used for pluralization.
+    #   Число для выбора формы.
+    # @param variants [Array<Object>] Pluralization variants in the order `one`, `few`, `many`, `other`.
+    #   Варианты в порядке `one`, `few`, `many`, `other`.
+    # @return [Object] Selected pluralization variant.
+    #   Выбранный вариант склонения.
+    # @raise [ArgumentError] if `n` is not numeric or required variants are missing.
+    #   Если `n` не число или не переданы нужные варианты.
+    #
+    # @example
+    #   Russian.pluralize(1, "вещь", "вещи", "вещей")
+    #   # => "вещь"
+    #   Russian.pluralize(3.14, "вещь", "вещи", "вещей", "вещи")
+    #   # => "вещи"
+    def pluralize(n, *variants)
+      raise ArgumentError, "Must have a Numeric as a first parameter" unless n.is_a?(Numeric)
+      raise ArgumentError, "Must have at least 3 variants for pluralization" if variants.size < 3
+      raise ArgumentError, "Must have at least 4 variants for pluralization" if variants.size < 4 && n != n.round
+
+      variants_hash = pluralization_variants_to_hash(*variants)
+      I18n.backend.send(:pluralize, LOCALE, variants_hash, n)
+    end
+    alias_method :p, :pluralize
+
+    # @!method p(n, *variants)
+    #   Alias for {.pluralize}.
+    #
+    #
+    #   Псевдоним для {.pluralize}.
+    #
+    #   @see .pluralize
+
+    # Transliterates a string from Cyrillic to Latin characters.
+    #
+    # The method delegates to {Transliteration.transliterate} and preserves the
+    # historical casing behavior of the gem.
+    #
+    #
+    # Транслитерирует строку из кириллицы в латиницу.
+    #
+    # Метод делегирует работу в {Transliteration.transliterate} и сохраняет
+    # историческое поведение gem'а по работе с регистром.
+    #
+    # @param str [String] String to transliterate.
+    #   Строка для транслитерации.
+    # @return [String] Transliteration result.
+    #   Результат транслитерации.
+    #
+    # @example
+    #   Russian.transliterate("Юлия")
+    #   # => "Yuliya"
+    def transliterate(str)
+      Transliteration.transliterate(str)
+    end
+    alias_method :translit, :transliterate
+
+    # @!method translit(str)
+    #   Alias for {.transliterate}.
+    #
+    #
+    #   Псевдоним для {.transliterate}.
+    #
+    #   @see .transliterate
+
+    private
+
+    # @private
     def locale_files
-      Dir[File.join(File.dirname(__FILE__), "russian", "locale", "**/*")]
+      Dir[File.join(__dir__, "russian", "locale", "**", "*")].select { |path| File.file?(path) }.sort
     end
-    
-    # Converts an array of pluralization variants to a Hash that can be used
-    # with I18n pluralization.
+
+    # @private
     def pluralization_variants_to_hash(*variants)
       {
-        :one => variants[0],
-        :few => variants[1],
-        :many => variants[2],
-        :other => variants[3]
+        one: variants[0],
+        few: variants[1],
+        many: variants[2],
+        other: variants[3]
       }
     end
+
+    # @private
+    def normalize_i18n_options(options = nil, kwargs = {}, defaults = {})
+      legacy_options = options || {}
+
+      raise ArgumentError, "Options must be provided as a Hash or keyword arguments" unless legacy_options.is_a?(Hash)
+
+      defaults.merge(legacy_options).merge(kwargs)
+    end
+  end
 end
 
 Russian.init_i18n

data/russian.gemspec

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "lib/russian/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "russian"
+  spec.version = Russian::VERSION::STRING
+
+  spec.authors = ["Yaroslav Markin"]
+  spec.description = "Russian language support for Ruby and Rails"
+  spec.email = "yaroslav@markin.net"
+  spec.extra_rdoc_files = ["README.md", "LICENSE", "CHANGELOG.md"]
+  spec.files = Dir.glob([
+    "lib/**/*", "sig/**/*", "CHANGELOG.md", "Gemfile",
+    "LICENSE", "Rakefile", "README.md", "russian.gemspec"
+  ])
+  spec.homepage = "https://github.com/yaroslav/russian"
+  spec.license = "MIT"
+  spec.metadata = {
+    "bug_tracker_uri" => "https://github.com/yaroslav/russian/issues",
+    "changelog_uri" => "https://github.com/yaroslav/russian/blob/master/CHANGELOG.md",
+    "documentation_uri" => "https://rubydoc.info/gems/russian",
+    "homepage_uri" => "https://github.com/yaroslav/russian",
+    "rubygems_mfa_required" => "true",
+    "source_code_uri" => "https://github.com/yaroslav/russian"
+  }
+  spec.platform = Gem::Platform::RUBY
+  spec.require_paths = ["lib"]
+  spec.required_ruby_version = ">= 3.2"
+  spec.summary = "Russian language support for Ruby and Rails"
+
+  spec.add_dependency("i18n", ">= 1.14.8", "< 2")
+
+  spec.add_development_dependency("bundler", ">= 2.4")
+  spec.add_development_dependency("irb", ">= 1.15")
+  spec.add_development_dependency("lefthook", "~> 2.1.4")
+  spec.add_development_dependency("rake", ">= 13.0", "< 14")
+  spec.add_development_dependency("rbs", "~> 3.10")
+  spec.add_development_dependency("rdoc", ">= 6.10")
+  spec.add_development_dependency("redcarpet", ">= 3.6")
+  spec.add_development_dependency("rspec", "~> 3.13")
+  spec.add_development_dependency("yard", "~> 0.9")
+end

data/sig/russian.rbs

@@ -0,0 +1,46 @@
+module Russian
+  LOCALE: :ru
+
+  def self.locale: () -> :ru
+  def self.init_i18n: () -> void
+
+  def self.translate: (String | Symbol key, ?Hash[untyped, untyped] options, **untyped) -> untyped
+  def self.t: (String | Symbol key, ?Hash[untyped, untyped] options, **untyped) -> untyped
+
+  def self.localize: (untyped object, ?Hash[untyped, untyped] options, **untyped) -> String
+  def self.l: (untyped object, ?Hash[untyped, untyped] options, **untyped) -> String
+
+  def self.strftime: (untyped object, ?Symbol format, **untyped) -> String
+                   | (untyped object, Hash[untyped, untyped] format, **untyped) -> String
+
+  def self.date_strptime: (String string, ?String format) -> Date
+  def self.time_strptime: (String string, String format, ?Time now) -> Time
+  def self.datetime_strptime: (String string, ?String format) -> DateTime
+
+  def self.pluralize: (Numeric n, *untyped variants) -> untyped
+  def self.p: (Numeric n, *untyped variants) -> untyped
+
+  def self.transliterate: (String str) -> String
+  def self.translit: (String str) -> String
+
+  module RailsIntegration
+    def self.install!: () -> void
+  end
+
+  module Transliteration
+    def self.transliterate: (String str) -> String
+  end
+
+  module Strptime
+    def self.date_strptime: (String string, ?String format) -> Date
+    def self.time_strptime: (String string, String format, ?Time now) -> Time
+    def self.datetime_strptime: (String string, ?String format) -> DateTime
+  end
+
+  module VERSION
+    MAJOR: Integer
+    MINOR: Integer
+    TINY: Integer
+    STRING: String
+  end
+end