Russian

Поддержка русского языка для Ruby и Rails при помощи библиотеки I18n.

Russian language support for Ruby and Rails, using I18n library.

If you don’t speak Russian

This code may still be useful for you and Ruby I18n community. You can learn how how to provide support of “standalone” (as defined in Unicode CLDR) month names with I18n and Rails without any custom backends or hacks, and how to use custom pluralization and transliteration locale settings. This library also includes a module (Russian) with a set of helpers to provide simplistic pluralization and strftime for Russian language — in a way that is easier than using I18n methods.

Feel free to shoot an email to Yaroslav Markin ([email protected])

Что это

Russian — это библиотека для полноценной поддержки русского языка (форматирование даты и времени, плюрализация, транслит, локализация в целом) для Ruby и Ruby on Rails.

Цель проекта — построить полноценную среду для русской локализации Ruby и Rails проектов, при этом используя минимально возможное количество хаков, сохраняя при этом поддержку локализации приложения на другие языки, а также форсировать включение в основную ветку I18n и Rails всех функций локализации, необходимых для работы с русским языком. Поскольку сделать в Rails поддержку довольно сложного языка для локализации (каким и является русский) сразу же было проблематично, вместе с командой gem i18n решено было обкатывать решение для русского языка на отдельном gem/плагине, и по мере возможности переносить наиболее общий функционал в “родительскую” библиотеку I18n. Таким образом, общей целью gem russian стала поддержка русского языка до тех пор, пока она не появится в самом I18n.

Russian использует библиотеку I18n (включена в поставку), несколько хаков поверх Rails (хаки хелперов даты-времени, хак для сообщений валидации) и файлы переводов, а также набор хелперов, упрощающий работу с русским языком (простая плюрализация, простой strftime и др.).

Russian стремится быть минимально деструктивной для окружения и быть полностью совместимой с другими языками (таким образом, когда приложение использует Russian, оно остается полностью совместимым с Rails i18n).

Что такое I18n. История

Библиотека I18n входит в состав Ruby on Rails начиная с версии 2.2. I18n — это самое простое и недеструктивное решение для локализации и интернационализации Rails приложений. К сожалению, в первых версиях отсутствовала поддержка нескольких важных возможностей, специфичных для русского языка. Таким образом, русский язык для локализации в Rails 2.2 фактически не поддерживался.

Для исправления этого досадного недоразумения появилась библиотека Russian. Ранее Russian включал в себя собственный бекенд для перегрузки форматирования даты-времени (использование названия месяца или дня недели в зависимости от контекста) и плюрализации (стандартный бекенд поддерживал только плюрализацию для английского языка), несколько хаков для Rails 2.2/2.3 (ActionView, ActiveRecord, ActiveSupport), полную локализацию даты-времени и таблицы переводов Rails на русский язык, и вспомогательные модули (плюрализация и транслитерация). Gem отлично работал на Rails 2, устраняя недостатки gem i18n “из коробки”.

В версии 0.2 gem i18n наконец появились первые средства для поддержки русского языка: в соавторстве с вашим покорным была добавлена поддержка lambda-переводов, благодаря которой стало возможным вынести логику перевода названия месяца/дня недели в таблицу переводов. Далее в gem i18n появилась поддержка хранения правил плюрализации в таблице переводов (опять же, с помощью lambda-переводов) и правил транслитерации. По сути, после этого цель gem russian была практически достигнута: опытные разработчики могли работать с русским языком, используя лишь собственные таблицы переводов в своем приложении и несколько хаков к Rails (по необходимости). Rails 3.0 вышел с последней версией gem i18n, где была уже практически полная поддержка механизмов для русского языка.

Однако, документация по плюрализации и транслитерации в I18n была неочевидной, а поддержка lambda-переводов для локализации даты-времени была практически “спрятана” в исходном коде, поэтому большинство разработчиков в основном использовали самые базовые таблицы переводов: локализацию Rails и, иногда, — плюрализацию. Возникла мысль выпустить gem russian для последней версии gem i18n и Ruby on Rails с поддержкой всех необходимых функций, но, на этот раз, грамотно сделанных через интерфейсы I18n. К сожалению, “хаки” для Ruby on Rails (хелперы даты-времени) вряд ли когда-либо будут включены в дистрибутив Rails, поэтому использовать их придется отдельно.

Требования

Ruby 1.8.7 или 1.9.2 (поддерживается совместимость с JRuby и Rubinius);

Для использования с Rails нужна версия не ниже 3.0 (для более старых версий Rails используйте версии gem russian ветки 0.2);
Для разработки и тестирования библиотеки вам понадобятся Bundler и RSpec.

Установка

Страница Russian на GitHub — http://github.com/yaroslav/russian/

Для установки:

gem install russian

Чтобы задать локаль по умолчанию в вашем приложении, используйте


I18n.default_locale = :ru

Чтобы установить локаль для текущего треда, используйте


I18n.locale = :ru

Ruby on Rails 3.0 и выше

В вашем Gemfile сделайте ссылку на gem russian:


gem 'russian', '~> 0.6.0'

И установите gem в проект с помощью bundler:

bundle install или bundle update.

Далее, укажите


config.i18n.default_locale = :ru

в config/application.rb. Если по умолчанию нужна другая локаль, или же нужно переключать локали “на ходу”, используйте методы модуля I18n (см. выше). Также ознакомьтесь с документацией к I18n и гидом по интернационализации Ruby on Rails.

Ruby on Rails 2.2 и 2.3

Используйте старые версии gem (0.2.x). Получить код и почитать инструкцию по установке можно здесь.

Использование

gem russian можно использовать как с Ruby on Rails, так и отдельно: с любым другим веб-фреймворком, или в любом другом приложении, не имеющим никакого отношения к вебу. Дело в том, что gem i18n, который Ruby on Rails использует для интернационализации, включен в gem russian как зависимость.

При загрузке Russian подключает библиотеку I18n (либо использует уже подключенную, например, в Rails), добавляет файлы русских переводов из поставки в самое начало пути поиска переводов I18n (это значит, что любой перевод из Russian вы сможете легко переопределить в вашем приложении), добавляет в используемый по умолчанию бекенд I18n поддержку плюрализации и транслитерации, и, наконец, перегружает бекенд.

Предыдущие версии Russian форсированно выставляли локаль I18n по умолчанию в :ru (Русский язык), от этого решено было отказаться: в Rails стало неудобно работать с мультиязычными приложениями, так как конструкция вида config.i18n.default_locale = :en не работала. Теперь для использования русского языка в Rails по умолчанию нужно использовать строку


config.i18n.default_locale = :ru

в config/application.rb. Для использования Russian отдельно от Rails можно выставить локаль I18n в русскую по умолчанию или для текущего треда, соответственно:


I18n.default_locale = :ru

I18n.locale = :ru

Также предыдущие версии Russian заменяли используемый I18n бекенд на собственный: другого способа получить качественную локализацию для даты-времени и поддержку плюрализации не было. Новые версии I18n включают в себя поддержку lambda {} в таблицах переводов (ссылка), поэтому собственный бекенд больше не нужен. Обратите внимание: если вы используете бекенд, отличный от стандартного, вам потребуется включить в него поддержку плюрализации (модуль I18n::Backend::Pluralization) и транслитерации (I18n::Backend::Transliterator).

Если во время загрузки Russian уже загружены библиотеки Rails, происходит загрузка хаков для Rails 3.0 и выше:

1. Хелперы даты получают ключ :use_standalone_month_names (для форсирования использования “отдельностоящего” названия месяца). Если ключ не указан, хелпер самостоятельно будет пытаться определить форму названия месяца: так, например, хелпер для выбора числа, месяца и года будет использовать “контекстную” форму названия месяца.

2. Включается перегрузка валидации для ActiveModel: если сообщение валидации указать с “птичкой” в начале, при выводе сообщений об ошибках (full_messages) для этого конкретного сообщения не будет указано название атрибута, к которому он относится. Этот фукнционал нужен, скорее, для тех, кто привык использовать подобные “хаки”: в Rails 3 эта задача решается с помощью ключа full_messages.format в таблице переводов.

Наконец, становится доступен модуль Russian (инструкция ниже), который нужен для быстрого доступа к некоторым основным и вспомогательным функциям локализации (плюрализация без таблицы переводов, транслитерация) и для методов интернационализации с форсированной локалью русского языка (перевод в русской локали, перевод даты-времени в русской локали).

После загрузки Russian можно использовать все стандартные функции библиотеки I18n, пользоваться измененным функционалом для лучшей поддержки русского языка, или использовать хелперы модуля Russian для еще более простой работы с русским языком.

Документация I18n

Гид по интернационализации Ruby on Rails.

Ключевые отличия от стандартной библиотеки I18n

1. Поддержка двух видов названий месяцев — контекст (“сентября”) и отдельностоящее (“Сентябрь”) и дней недели.

В словарях Russian определены оба варианта названий месяцев. В таблице переводов для русского языка (locale/datetime.rb) указаны правила для перевода: в зависимости от формата строки strftime, используется контекстное или отдельностоящее название.

По аналогии есть поддержка двух видов названий дней недели.

NB: обратите внимание на нестандартные названия ключей при перечислении месяцев и дней недели в locale/datetime.yml.
NB: на необычных форматах strftime-строк контекст может не распознаваться; просто “дробите” в таком случае строку strftime на части.

2. Плюрализация

Включены правила плюрализации для русского языка (согласно CLDR). Их можно использовать как через интерфейс I18n, так и с помощью метода Russian::pluralize.

3. Транслитерация

Включен модуль для транслитерации русского алфавита: им можно пользоваться как через собственный интерфейс (Russian::transliterate), так и через интерфейс I18n.

Ruby on Rails

Переводы

При использовании с Ruby on Rails загружаются все стандартные переводы, и русский язык становится годным к использованию для локализации. В поставку включены все нужные переводы для ActionView, ActiveRecord, ActiveSupport, ActiveModel, которые можно переопределять по необходимости стандартными средствами I18n из вашего приложения.

Хелперы

Хелперы даты-времени получают ключ :use_standalone_month_names для форсирования отображения отдельностоящего названия месяца (“Сентябрь” а не “сентября”). Такое имя месяца используется когда включен ключ :use_standalone_month_names (для отдельностоящего select_month он включается по умолчанию), либо когда есть ключ :discard_day.

Валидация

На тот случай, если по каким-то причинам нельзя воспользоваться ключом full_messages.format в таблице переводов, Russian перегружает вывод “полных сообщений” об ошибках в ActiveModel.

Так, например,

validates_acceptance_of :accepted_terms, :message => 'нужно принять соглашение'

при валидации выдаст сообщение

Accepted terms нужно принять соглашение

или, например

Соглашение об использовании нужно принять соглашение

если вы указали перевод для имени атрибута.

Но

validates_acceptance_of :accepted_terms, :message => '^Нужно принять соглашение'

даст сообщение

Нужно принять соглашение

Параметризация строк

Метод parameterize инфлектора ActiveSupport использует механизмы транслитерации I18n. Если русская локаль является текущей, он сможет поддерживать транслитерацию букв русского алфавита.

Пример:


class Person
  def to_param
    "#{id}-#{name.parameterize}"
  end
end

@person = Person.find(1)
# => #<Person id: 1, name: "Дональд Кнут">

<%= link_to(@person.name, person_path(@person)) %>
# => <a href="/person/1-donald-knut">Дональд Кнут</a>

NB: Для простоты иногда проще воспользоваться методом Russian::transliterate напрямую (чтобы не зависеть от текущей локали).

Справочник

Примеры и справка по переводам (I18n)

Небольшую справку по переводам (I18n) и пример того, как можно переводить имена моделей, атрибутов, и многие другие вещи, определенные в Rails или I18n, можно посмотреть в директории lib/russian/locale. Там находятся файлы переводов, которые используются в Russian, со всеми комментариями.

Вспомогательные методы модуля Russian


Russian.locale
Russian::LOCALE

— возвращает локаль русского языка (:'ru').


Russian::init_i18n

— инициализация Russian. Добавление русских переводов в путь загрузки, включение модулей для плюрализации и транслитерации и перегрузка I18n.

NB: Выполняется автоматически при загрузке.


Russian::translate
Russian::t

— прокси для метода translate I18n, форсирует использование русской локали.


Russian::localize
Russian::l

— прокси для метода localize I18n, форсирует использование русской локали.


Russian::strftime

Russian::strftime(Time.now)
=> "Пн, 01 сент. 2008, 11:12:43 +0300"
Russian::strftime(Time.now, "%d %B")
>> "01 сентября"
Russian::strftime(Time.now, "%B")
=> "Сентябрь"

— strftime с форсированием русской локали (упрощенный вариант localize)


Russian::pluralize
Russian::p

Russian.p(1, "вещь", "вещи", "вещей")
=> "вещь"
Russian.p(2, "вещь", "вещи", "вещей")
=> "вещи"
Russian.p(10, "вещь", "вещи", "вещей")
=> "вещей"
Russian.p(3.14, "вещь", "вещи", "вещей", "вещи") # последний вариант используется для дробных величин
=> "вещи"

— упрощенная (без использования хешей I18n) плюрализация для русского языка


Russian::transliterate
Russian::translit

Russian.translit("рубин")
=> "rubin"
Russian.translit("Hallo Юлику Тарханову")
=> "Hallo Yuliku Tarhanovu"

— транслитерация русских букв в строке.

Авторы

Для сообщений об ошибках, обнаруженных неточностях и предложений:

Ярослав Маркин ([email protected])

При участии:

Огромное спасибо:

Юлику Тарханову за rutils

yaroslav/russian

yaroslav

Reviews

Repository Details