I18n(0.9.3)のコードリーディングをしました。
まず簡単な使い方から。
require 'i18n'
I18n.load_path << 'config/locales/en.yml'
# I18n.locale = :ja
I18n.t('hoge')
Railsを使っていると特に何も考えなくてもconfig/locales/から設定ファイルをロードしたり色々やってくれて便利なんですが、I18n単体でもこんなにシンプルに書けます。Railsでやっている処理に関しては後半に紹介します。
まずI18n.load_pathの処理をみてみます。load_pathはconfigに処理を委譲しており、configはI18n::Configのインスタンスです。
module I18n
class Config
def load_path
@@load_path ||= []
end
def load_path=(load_path)
@@load_path = load_path
@@available_locales_set = nil
backend.reload!
end
load_pathはI18n::Configのクラス変数の@@load_pathの操作になります。
translate
#tは#translateのエイリアスです。config.backendはBackend::Simpleのインスタンスが入ります。module I18n
module Base
def translate(*args)
options = args.last.is_a?(Hash) ? args.pop.dup : {}
key = args.shift
backend = config.backend
locale = options.delete(:locale) || config.locale
handling = options.delete(:throw) && :throw || options.delete(:raise) && :raise # TODO deprecate :raise
enforce_available_locales!(locale)
result = catch(:exception) do
if key.is_a?(Array)
key.map { |k| backend.translate(locale, k, options) }
else
backend.translate(locale, key, options)
end
end
result.is_a?(MissingTranslation) ? handle_exception(handling, result, locale, key, options) : result
end
alias :t :translate
#enforce_available_locales!はconfig.enforce_available_localesがtrueの場合、ロケールが利用可能かどうかをチェックします。@@enforce_available_localesはデフォルトtrueなので未設定の場合は必ず#locale_available?が呼ばれます。
# Returns true when the passed locale, which can be either a String or a
# Symbol, is in the list of available locales. Returns false otherwise.
def locale_available?(locale)
I18n.config.available_locales_set.include?(locale)
end
# Raises an InvalidLocale exception when the passed locale is not available.
def enforce_available_locales!(locale)
if config.enforce_available_locales
raise I18n::InvalidLocale.new(locale) if !locale_available?(locale)
end
end
#locale_available?はさらにI18n::Config#available_locales_set経由でbackend.available_localesを呼び出します。
module I18n
class Config
def available_locales
@@available_locales ||= nil
@@available_locales || backend.available_locales
end
def available_locales_set #:nodoc:
@@available_locales_set ||= available_locales.inject(Set.new) do |set, locale|
set << locale.to_s << locale.to_sym
end
end
I18n::Backend::Simple#available_localesは初期化されていない場合は#init_translations経由で#load_translationsを呼び出します。
module I18n
module Backend
class Simple
(class << self; self; end).class_eval { public :include }
module Implementation
include Base
def initialized?
@initialized ||= false
end
def available_locales
init_translations unless initialized?
translations.inject([]) do |locales, (locale, data)|
locales << locale unless data.size <= 1 && (data.empty? || data.has_key?(:i18n))
locales
end
end
protected
def init_translations
load_translations
@initialized = true
end
#load_translationsはI18n.load_pathに設定されたファイルパスを#load_fileの引数に渡します。
module I18n
module Backend
module Base
include I18n::Backend::Transliterator
def load_translations(*filenames)
filenames = I18n.load_path if filenames.empty?
filenames.flatten.each { |filename| load_file(filename) }
end
protected
def load_file(filename)
type = File.extname(filename).tr('.', '').downcase
raise UnknownFileType.new(type, filename) unless respond_to?(:"load_#{type}", true)
data = send(:"load_#{type}", filename)
unless data.is_a?(Hash)
raise InvalidLocaleData.new(filename, 'expects it to return a hash, but does not')
end
data.each { |locale, d| store_translations(locale, d || {}) }
end
def load_yml(filename)
begin
YAML.load_file(filename)
rescue TypeError, ScriptError, StandardError => e
raise InvalidLocaleData.new(filename, e.inspect)
end
end
#loadfileは”load#{ファイルの拡張子}“のメソッドを呼び出します。予め定義されているのはload_ymlとload_rbになります。YAMLの拡張子に.yamlが使えないのはこれが理由だったりします。普通にalias貼れば解決しそうな感じはしますが…。
読み込んだデータはstore_translationsによってメモリ上に保存されます。
module I18n
module Backend
class Simple
module Implementation
def store_translations(locale, data, options = {})
if I18n.available_locales_initialized? &&
!I18n.available_locales.include?(locale.to_sym) &&
!I18n.available_locales.include?(locale.to_s)
return data
end
locale = locale.to_sym
translations[locale] ||= {}
data = data.deep_symbolize_keys
translations[locale].deep_merge!(data)
end
Hash#deep_symbolize_keysによって全てのキーがシンボル化された上で#translations経由で翻訳データが保存されます。
#translateの後半が実際の翻訳処理になります（以下、再掲）
module I18n
module Base
def translate(*args)
# ...
result = catch(:exception) do
if key.is_a?(Array)
key.map { |k| backend.translate(locale, k, options) }
else
backend.translate(locale, key, options)
end
end
result.is_a?(MissingTranslation) ? handle_exception(handling, result, locale, key, options) : result
backend.translateを呼び出します。色々と処理しているのですが本質的なところだけ抜き出しました↓
module I18n
module Backend
module Base
def translate(locale, key, options = {})
# ...
entry = lookup(locale, key, options[:scope], options) unless key.nil?
if entry.nil? && options.key?(:default)
entry = default(locale, key, options[:default], options)
else
entry = resolve(locale, key, entry, options)
end
# ...
deep_interpolation = options[:deep_interpolation]
values = options.except(*RESERVED_KEYS)
if values
entry = if deep_interpolation
deep_interpolate(locale, entry, values)
else
interpolate(locale, entry, values)
end
end
entry
end
I18n::Backend::Simple#lookupは以下のようになっており、
def lookup(locale, key, scope = [], options = {})
init_translations unless initialized?
keys = I18n.normalize_keys(locale, key, scope, options[:separator])
keys.inject(translations) do |result, _key|
_key = _key.to_sym
return nil unless result.is_a?(Hash) && result.has_key?(_key)
result = result[_key]
result = resolve(locale, _key, result, options.merge(:scope => nil)) if result.is_a?(Symbol)
result
end
end
#normalize_keyはキーをセパレータで区切って配列にします
def normalize_key(key, separator)
@@normalized_key_cache[separator][key] ||=
case key
when Array
key.map { |k| normalize_key(k, separator) }.flatten
else
keys = key.to_s.split(separator)
keys.delete('')
keys.map! { |k| k.to_sym }
keys
end
end
#resolveは値がシンボルやProcだった場合、追加処理をするものです。シンボルの場合は、その値をキーとしてI18n.tを再帰的に呼び出すリンク的な処理をしたり、Procの場合はcallして評価した上でさらにresolveします。ProcはYAMLで表現できないので、Rubyの翻訳ファイルを読み込んだときだけ利用可能な機能っぽいです（コード読んで初めて知った）
def resolve(locale, object, subject, options = {})
return subject if options[:resolve] == false
result = catch(:exception) do
case subject
when Symbol
I18n.translate(subject, options.merge(:locale => locale, :throw => true))
when Proc
date_or_time = options.delete(:object) || object
resolve(locale, object, subject.call(date_or_time, options))
else
subject
end
end
result unless result.is_a?(MissingTranslation)
end
#lookup内のresolveと#translate内のresolveは役割が異なっており、キー評価の途中の解決は#lookup、キー評価後の最後の値に対して解決するのが#translateです。
例えば、キーがfoo.bar.bazでfooの値がシンボルの場合は、そのシンボルを解決するのが#lookup内のresolve、キーがfoo.bar.bazでbazの値がシンボルの場合は、そのシンボルを解決するのが#translate内のresolveとなります。
さらに、#translate内ではパラメータをバインドするinterpolationの処理も行います。
localize
#lは#localizeのエイリアスです。まず、backend.localizeを呼び出します。def localize(object, options = nil)
options = options ? options.dup : {}
locale = options.delete(:locale) || config.locale
format = options.delete(:format) || :default
enforce_available_locales!(locale)
config.backend.localize(locale, object, format, options)
end
objectにはDate、DateTime、Timeオブジェクトが入ります。formatは”#{type}.formats.#{key}”のキーで取得したデータを利用して、strftimeで文字列に置き換えます。
def localize(locale, object, format = :default, options = {})
if object.nil? && options.include?(:default)
return options[:default]
end
raise ArgumentError, "Object must be a Date, DateTime or Time object. #{object.inspect} given." unless object.respond_to?(:strftime)
if Symbol === format
key = format
type = object.respond_to?(:sec) ? 'time' : 'date'
options = options.merge(:raise => true, :object => object, :locale => locale)
format = I18n.t(:"#{type}.formats.#{key}", options)
end
format = translate_localization_format(locale, object, format, options)
object.strftime(format)
end
#translate_localization_formatではロケールごとの月や曜日などの名前をString#gsubで変換していきます。
def translate_localization_format(locale, object, format, options)
format.to_s.gsub(/%[aAbBpP]/) do |match|
case match
when '%a' then I18n.t(:"date.abbr_day_names", :locale => locale, :format => format)[object.wday]
when '%A' then I18n.t(:"date.day_names", :locale => locale, :format => format)[object.wday]
when '%b' then I18n.t(:"date.abbr_month_names", :locale => locale, :format => format)[object.mon]
when '%B' then I18n.t(:"date.month_names", :locale => locale, :format => format)[object.mon]
when '%p' then I18n.t(:"time.#{object.hour < 12 ? :am : :pm}", :locale => locale, :format => format).upcase if object.respond_to? :hour
when '%P' then I18n.t(:"time.#{object.hour < 12 ? :am : :pm}", :locale => locale, :format => format).downcase if object.respond_to? :hour
end
end
end
Railsでやっていること
Railsの場合、I18n::RailtieというRailtieが定義されており、I18nの初期設定やconfigで設定したものを読み出します。module I18n
class Railtie < Rails::Railtie
def self.initialize_i18n(app)
# ...
reloadable_paths = []
app.config.i18n.each do |setting, value|
case setting
when :railties_load_path
reloadable_paths = value
app.config.i18n.load_path.unshift(*value.map(&:existent).flatten)
when :load_path
I18n.load_path += value
else
I18n.send("#{setting}=", value)
end
end
# ...
end
またRails::Engineではi18n.railties_load_pathにpaths[“config/locales”]を追加しています。これによってconfig/locales以下のファイルがI18n.load_pathに追加されます。
module Rails
class Engine < Railtie
initializer :add_locales do
config.i18n.railties_load_path << paths["config/locales"]
end
また、ビューファイル内ではI18n.lではなくlがエイリアスとして使えます。これはビューをレンダリングするコンテキストのクラスがActionView::Baseを継承していて、ActionView::BaseがActionView::Helpers（HelpersはさらにTranslationHelperをinclude）をincludeしているためです。
module ActionView
module Helpers
module TranslationHelper
def translate(key, options = {})
# ...
end
alias :t :translate
def localize(*args)
I18n.localize(*args)
end
alias :l :localize
module ActionView #:nodoc:
class Base
include Helpers, ::ERB::Util, Context
module ActionView
module Rendering
module ClassMethods
def view_context_class
# ...
Class.new(ActionView::Base) do
if routes
include routes.url_helpers(supports_path)
include routes.mounted_helpers
end
if helpers
include helpers
end
end
