Module ArkanisDevelopment::SimpleLocalization::Language
In: lib/language.rb

This module loads and manages access to the used language files.

Methods

External Aliases

current_language -> used
current_language= -> use
entry -> []

Public Class methods

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'
       }

[Source]

     # 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

[Source]

    # 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

[Source]

    # 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 (%).

[Source]

     # 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.

[Source]

     # 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."

[Source]

     # 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

Returns a hash with all loaded LangFile objects.

[Source]

    # File lib/language.rb, line 80
80:         def lang_files
81:           @@languages
82:         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.

[Source]

     # 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.

[Source]

    # 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]

[Source]

    # 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.

[Source]

     # 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.

[Source]

     # 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

[Validate]