R18n::Filters

Filter is a way, to process translations: escape HTML entries, convert from Markdown syntax, etc.

In translation file filtered content must be marked by YAML type:

filtered: !!custom_type
  This content will be processed by filter

Filter function will be receive filtered content as first argument, struct with filter config as second and filter parameters as next arguments. You can set passive filter, which will process translation only on loading.

R18n::Filters.add('custom_type', :no_space) do |content, config, replace|
  content.gsub(' ', replace)
end
R18n::Filters.add('custom_type', :passive => true) do |content, config|
  content + '!'
end

i18n.filtered('_') #=> "This_content_will_be_processed_by_filter!"

Use String class as type to add global filter for all translated strings:

R18n::Filters.add(String, :escape_html) do |content, config, params|
  escape_html(content)
end

Filter config contain two parameters: translation locale and path. But it is Hash and you can add you own parameter to cross-filter communications:

R18n::Filters.add(String, :hide_truth) do |content, config|
  return content if config[:censorship_check]

  if content.scan(CENSORSHIP_WORDS[config[:locale]]).empty?
    content
  else
    "Error in #{config[:path]}"
  end
end

R18n::Filters.add('passed', :show_lie) do |content, config|
  config[:censorship_check] = true
  content
end

You can disable, enabled and delete filters:

R18n::Filters.off(:no_space))
i18n.filtered('_') #=> "This content will be processed by filter!"
R18n::Filters.on(:no_space)
i18n.filtered('_') #=> "This_content_will_be_processed_by_filter!"
R18n::Filters.delete(:no_space)

You can enabled/disabled filters only for special I18n object:

R18n::I18n.new('en', nil, :on_filters  => [:untranslated_html, :no_space],
                          :off_filters => :untranslated )

Constants

Filter

Attributes

active_enabled[RW]

Hash of types to enabled active filters.

by_type[RW]

Hash of types to all Filters.

defined[RW]

Hash of filter names to Filters.

enabled[RW]

Hash of types to enabled passive and active filters.

passive_enabled[RW]

Hash of types to enabled passive filters.

Public Class Methods

add(types, name = nil, options = {}, &block) click to toggle source

Add new filter for type with name and return filter object. You can use String class as type to add global filter for all translated string.

Filter content will be sent to block as first argument, struct with config as second and filters parameters will be in next arguments.

Options:

  • position – change order on processing several filters for same type.

    Note that passive filters will be always run before active.
  • passive – if true, filter will process only on translation loading. Note that you must add all passive before load translation.

# File lib/r18n-core/filters.rb, line 127
def add(types, name = nil, options = {}, &block)
  options, name = name, nil if name.is_a? Hash
  types = Array(types)

  unless name
    @last_auto_name ||= 0
    begin
      @last_auto_name += 1
      name = @last_auto_name
    end while defined.has_key? name
  else
    delete(name)
  end

  filter = Filter.new(name, types, block, true, options[:passive])
  @defined[name] = filter

  types.each do |type|
    @by_type[type] = [] unless @by_type.has_key? type
    if options.has_key? :position
      @by_type[type].insert(options[:position], filter)
    else
      @by_type[type] << filter
    end
    rebuild_enabled! type
  end

  @new_filter_listener.call(filter) if @new_filter_listener
  filter
end
delete(filter) click to toggle source

Delete filter by name or Filter object.

# File lib/r18n-core/filters.rb, line 159
def delete(filter)
  filter = @defined[filter] unless filter.is_a? Filter
  return unless filter

  @defined.delete(filter.name)
  filter.types.each do |type|
    @by_type[type].delete(filter)
    rebuild_enabled! type
  end
end
listen(&block) click to toggle source

Return filters, which be added inside block.

# File lib/r18n-core/filters.rb, line 189
def listen(&block)
  filters = []
  @new_filter_listener = proc { |i| filters << i }
  yield
  @new_filter_listener = nil
  filters
end
off(filter) click to toggle source

Disable filter by name or Filter object.

# File lib/r18n-core/filters.rb, line 171
def off(filter)
  filter = @defined[filter] unless filter.is_a? Filter
  return unless filter

  filter.enabled = false
  filter.types.each { |type| rebuild_enabled! type }
end
on(filter) click to toggle source

Turn on disabled filter by name or Filter object.

# File lib/r18n-core/filters.rb, line 180
def on(filter)
  filter = @defined[filter] unless filter.is_a? Filter
  return unless filter

  filter.enabled = true
  filter.types.each { |type| rebuild_enabled! type }
end
rebuild_enabled!(type) click to toggle source

Rebuild active_enabled and passive_enabled for type.

# File lib/r18n-core/filters.rb, line 98
def rebuild_enabled!(type)
  @passive_enabled[type] = []
  @active_enabled[type] = []
  @enabled[type] = []

  @by_type[type].each do |filter|
    if filter.enabled?
      @enabled[type] << filter
      if filter.passive?
        @passive_enabled[type] << filter
      else
        @active_enabled[type] << filter
      end
    end
  end
end

[Validate]

Generated with the Darkfish Rdoc Generator 2.