Module | ArkanisDevelopment::SimpleLocalization::Language |
In: |
lib/language.rb
|
This module loads and manages access to the used language files.
current_language | -> | used |
current_language= | -> | use |
entry | -> | [] |
Returns a hash with the meta data of the specified language (defaults to the currently used language). Entries not present in the language file will default to nil. If the specified language file is not loaded an LangFileNotLoaded exception is raised.
Language.about :de # => { :language => 'Deutsch', :author => 'Stephan Soller', :comment => 'Deutsche Sprachdatei. Kann als Basis für neue Sprachdatein dienen.', :website => 'http://www.arkanis-development.de/', :email => nil, # happens if no email is specified in the language file. :date => '2007-01-20' }
# File lib/language.rb, line 260 260: def about(lang = self.current_language) 261: lang = lang.to_sym 262: 263: defaults = { 264: :language => nil, 265: :author => nil, 266: :comment => nil, 267: :website => nil, 268: :email => nil, 269: :date => nil 270: } 271: 272: defaults.update self.find(lang, :about).symbolize_keys 273: end
Returns the name of the currently used language as a symbol.
Language.current_language = :de Language.current_language # => :de
# File lib/language.rb, line 37 37: def current_language 38: @@current_language 39: end
Sets the currently used language. If the specified language file is not loaded a LangFileNotLoaded exception will be raised.
simple_localization :languages => [:de, :en] Language.current_language # => :de Language.current_language = :en Language.current_language # => :en
There are also aliases for the current_language attribute accessor:
simple_localization :languages => [:de, :en] Language.used # => :de Language.use :en Language.used # => :en
# File lib/language.rb, line 58 58: def current_language=(new_lang) 59: if loaded_languages.include? new_lang.to_sym 60: @@current_language = new_lang.to_sym 61: else 62: raise LangFileNotLoaded.new(new_lang, loaded_languages) 63: end 64: end
Returns the specified entry from the currently used language file. It‘s possible to specify nested entries by using more than one parameter.
Language.entry :active_record_messages, :too_short # => "ist zu kurz (mindestens %d Zeichen)."
This will return the too_short entry within the active_record_messages entry. The YAML code in the language file looks like this:
active_record_messages: too_short: ist zu kurz (mindestens %d Zeichen).
If the entry is not found nil is returned.
This method also allows you to substitute values inside the found entry. The substitute_entry method is used for this and there are two ways to do this:
With format:
Just specify an array with the format values as last key:
Language.entry :active_record_messages, :too_short, [5] # => "ist zu kurz (mindestens 5 Zeichen)."
If format fails the reaction depends on the debug option of the Language module. If debug is set to false the unformatted entry is returned. If debug is true an EntryFormatError is raised detailing what went wrong.
With "hash notation" like used by the ActiveRecord conditions:
It‘s also possible to use a hash to specify the values to substitute. This works like the conditions of ActiveRecord:
app: welcome: Welcome :name, you have :number new messages. Language.entry :app, :welcome, :name => 'Mr. X', :number => 5 # => "Welcome Mr. X, you have 5 new messages."
Both approaches allow you to use the \ character to escape colons (:) and percent sings (%).
# File lib/language.rb, line 187 187: def entry(*args) 188: begin 189: entry!(*args) 190: rescue EntryNotFound 191: nil 192: end 193: end
Same as the +Language#entry+ method but it raises an EntryNotFound exception if the specified entry does not exists.
# File lib/language.rb, line 199 199: def entry!(*args) 200: substitute_values = if args.last.kind_of?(Hash) 201: [args.delete_at(-1)] 202: elsif args.last.kind_of?(Array) 203: args.delete_at(-1) 204: else 205: [] 206: end 207: 208: entry = self.find(self.current_language, *args) 209: entry.kind_of?(String) ? substitute_entry(entry, *substitute_values) : entry 210: rescue EntryFormatError => e 211: raise EntryFormatError.new(e.language, args, e.entry_content, e.format_values, e.original_exception) # reraise with more details 212: end
Searches the date of the specified language file for the entry addressed by keys.
If the specified language file is not loaded an LangFileNotLoaded exception is raised. If the entry is not found an EntryNotFound exception is raised.
Language.find :de, :active_record_messages, :not_a_number # => "ist keine Zahl."
# File lib/language.rb, line 132 132: def find(language, *keys) 133: language = language.to_sym 134: if @@languages.empty? or not @@languages[language] 135: raise LangFileNotLoaded.new(language, loaded_languages) 136: end 137: 138: keys.collect!{|key| key.kind_of?(Numeric) ? key : key.to_s} 139: begin 140: @@languages[language].data[*keys] 141: rescue EntryNotFound 142: raise EntryNotFound.new(keys, language) # reraise with more details 143: end 144: end
Loads the specified language files. If currently no language is selected the first one of the specified files will be selected.
The path to the language files can be specified in the lang_file_dirs option.
Language.load :de, :en
This will load the files de.yml and en.yml and all of it‘s parts in the language file directory. If existing the files de.rb and en.rb will be executed. It also selects :de as the active language because it was specified first.
# File lib/language.rb, line 105 105: def load(*languages) 106: languages.flatten! 107: languages.each do |lang_code| 108: lang_file = LangFile.new lang_code, self.lang_file_dirs 109: @@languages[lang_code.to_sym] = lang_file 110: lang_file.load 111: end 112: self.use languages.first if current_language.nil? 113: end
Checks if the specified language is loaded or when called without an argument if at least one language is loaded. Handy to check if the plugin is initialized.
# File lib/language.rb, line 71 71: def loaded?(language_name = nil) 72: if language_name 73: self.loaded_languages.include? language_name 74: else 75: not self.loaded_languages.blank? 76: end 77: end
Returns the language codes of currently loaded languages.
Language.loaded_languages # => [:de, :en]
# File lib/language.rb, line 88 88: def loaded_languages 89: @@languages.keys 90: end
Reload the data of all loaded language files by calling the LangFile#reload method on each language file.
# File lib/language.rb, line 117 117: def reload 118: @@languages.each do |lang_code, lang_file| 119: lang_file.reload 120: end 121: end
Substitutes a string with values by using format or a hash like known from the ActiveRecord conditions.
substitute_entry 'substitute %s and %i', 'this', 10 # => "substitute this and 10" substitute_entry 'escape %%s but not %s', 'this' # => "escape %s but not this" substitute_entry 'substitute :a and :b', :a => 'this', :b => 10 # => "substitute this and 10" substitute_entry 'escape \:a but not :b', :b => 'this' # => "escape :a but not this"
If the format style is used and an error occurs an EntryFormatError will be raised. It contains some extra information as well as the original exception.
# File lib/language.rb, line 225 225: def substitute_entry(string, *values) 226: return unless string 227: if values.last.kind_of?(Hash) 228: string = ' ' + string 229: values.last.each do |key, value| 230: string.gsub!(/([^\\]):#{key}/, "\\1#{value}") 231: end 232: string.gsub!(/([^\\])\\:/, '\\1:') 233: string[1, string.length] 234: elsif not values.empty? 235: begin 236: format(string, *values) 237: rescue StandardError => e 238: self.debug ? raise(EntryFormatError.new(self.current_language, [], string, values, e)) : string 239: end 240: else 241: string 242: end 243: end