Module: ActionView::Helpers::TranslationHelper

Relationships & Source Files
Extension / Inclusion / Inheritance Descendants
Included In: `::ActionDispatch::DebugView`, `::ActionView::Base`, `::ActionView::Helpers`, `::ActionView::TestCase`, `::ActionView::TestCase::Behavior`
Super Chains via Extension / Inclusion / Inheritance
Class Chain: self, `::ActiveSupport::Concern`
Instance Chain: self, `TagHelper`, `OutputSafetyHelper`, `CaptureHelper`
Defined in:	actionview/lib/action_view/helpers/translation_helper.rb

Overview

Action View Translation Helpers

Constant Summary

MISSING_TRANSLATION = private
# File 'actionview/lib/action_view/helpers/translation_helper.rb', line 130
```
-(2**60)
```
NO_DEFAULT = private
# File 'actionview/lib/action_view/helpers/translation_helper.rb', line 133
```
[].freeze
```

`TagHelper` - Included

ARIA_PREFIXES, BOOLEAN_ATTRIBUTES, CLASS_PREFIXES, DATA_PREFIXES, PRE_CONTENT_STRINGS, TAG_TYPES

Class Method Summary

`::ActiveSupport::Concern` - Extended

class_methods	Define class methods from given block.
included	Evaluate given block in context of base class, so that you can write class macros here.
prepended	Evaluate given block in context of base class, so that you can write class macros here.
append_features, prepend_features

Instance Attribute Summary

#raise_on_missing_translations rw

Specify whether an error should be raised for missing translations.

Instance Method Summary

#l(object, **options)

Alias for #localize.
#localize(object, **options) (also: #l)

Delegates to I18n.localize with no additional functionality.
#t(key, **options)

Alias for #translate.
#translate(key, **options) (also: #t)

Delegates to I18n#translate but also performs three additional functions.
#missing_translation(key, options) private
#scope_key_by_partial(key) private
#scope_option_by_partial(scope) private
#scope_prefix private

`TagHelper` - Included

#cdata_section	Returns a CDATA section with the given `content`.
#class_names	Alias for TagHelper#token_list.
#content_tag	Returns an HTML block tag of type `name` surrounding the `content`.
#escape_once	Returns an escaped version of `html` without affecting existing escaped entities.
#tag	Modern syntax.
#token_list	Returns a string of tokens built from `args`.
#build_tag_values, #ensure_valid_html5_tag_name, #tag_builder

`OutputSafetyHelper` - Included

#raw	This method outputs without escaping a string.
#safe_join	This method returns an HTML safe string similar to what `Array#join` would return.
#to_sentence	Converts the array to a comma-separated sentence where the last element is joined by the connector word.

`CaptureHelper` - Included

#capture	The capture method extracts part of a template as a string object.
#content_for	Calling `content_for` stores a block of markup in an identifier for later use.
#content_for?	`content_for?` checks whether any content has been captured yet using `content_for`.
#provide	The same as `content_for` but when used with streaming flushes straight back to the layout.
#with_output_buffer	Use an alternate output buffer for the duration of the block.

DSL Calls

included

[ GitHub ]



17
18
19

# File 'actionview/lib/action_view/helpers/translation_helper.rb', line 17


included do
  mattr_accessor :debug_missing_translation, default: true
end

Instance Attribute Details

#raise_on_missing_translations (rw)

Specify whether an error should be raised for missing translations.

[ GitHub ]

# File 'actionview/lib/action_view/helpers/translation_helper.rb', line 15


singleton_class.attr_accessor :raise_on_missing_translations

Instance Method Details

#l(object, **options)

Alias for #localize.

[ GitHub ]

# File 'actionview/lib/action_view/helpers/translation_helper.rb', line 127


alias :l :localize

#localize(object, **options) Also known as: #l

Delegates to I18n.localize with no additional functionality.

See https://www.rubydoc.info/gems/i18n/I18n/Backend/Base:localize for more information.

[ GitHub ]

# File 'actionview/lib/action_view/helpers/translation_helper.rb', line 124


def localize(object, **options)
  I18n.localize(object, **options)
end

#missing_translation(key, options) (private)

[ GitHub ]

# File 'actionview/lib/action_view/helpers/translation_helper.rb', line 166


def missing_translation(key, options)
  locale = options[:locale] || I18n.locale

  i18n_exception = I18n::MissingTranslation.new(locale, key, options)
  I18n.exception_handler.call(i18n_exception, locale, key, options)

  keys = I18n.normalize_keys(locale, key, options[:scope])

  title = +"translation missing: #{keys.join(".")}"

  options.each do |name, value|
    unless name == :scope
      title << ", " << name.to_s << ": " << ERB::Util.html_escape(value)
    end
  end

  if ActionView::Base.debug_missing_translation
    content_tag("span", keys.last.to_s.titleize, class: "translation_missing", title: title)
  else
    title
  end
end

#scope_key_by_partial(key) (private)

[ GitHub ]

# File 'actionview/lib/action_view/helpers/translation_helper.rb', line 141


def scope_key_by_partial(key)
  if key&.start_with?(".")
    if @virtual_path
      "#{scope_prefix}#{key}"
    else
      raise "Cannot use t(#{key.inspect}) shortcut because path is not available"
    end
  else
    key
  end
end

#scope_option_by_partial(scope) (private)

[ GitHub ]

# File 'actionview/lib/action_view/helpers/translation_helper.rb', line 153


def scope_option_by_partial(scope)
  if (scope.is_a?(String) || scope.is_a?(Symbol)) && scope.start_with?(".")
    if @virtual_path
      resolved = "#{scope_prefix}#{scope}"
      scope.is_a?(Symbol) ? resolved.to_sym : resolved
    else
      raise "Cannot use scope: #{scope.inspect} shortcut because path is not available"
    end
  else
    scope
  end
end

#scope_prefix (private)

[ GitHub ]

# File 'actionview/lib/action_view/helpers/translation_helper.rb', line 136


def scope_prefix
  @_scope_key_by_partial_cache ||= {}
  @_scope_key_by_partial_cache[@virtual_path] ||= @virtual_path.gsub(%r{/_?}, ".")
end

#t(key, **options)

Alias for #translate.

[ GitHub ]

# File 'actionview/lib/action_view/helpers/translation_helper.rb', line 118


alias :t :translate

#translate(key, **options) Also known as: #t

Delegates to I18n#translate but also performs three additional functions.

First, it will ensure that any thrown MissingTranslation messages will be rendered as inline spans that:

Have a translation-missing class applied
Contain the missing key as the value of the title attribute
Have a titleized version of the last key segment as text

For example, the value returned for the missing translation key "blog.post.title" will be:

<span
 class="translation_missing"
 title="translation missing: en.blog.post.title">Title</span>

This allows for views to display rather reasonable strings while still giving developers a way to find missing translations.

If you would prefer missing translations to raise an error, you can opt out of span-wrapping behavior globally by setting config.i18n.raise_on_missing_translations = true or individually by passing raise: true as an option to translate.

Second, if the key or the :scope option starts with a period, translate will scope it by the current partial. Calling translate(".foo") or translate("bar", scope: ".foo") from the people/index.html.erb template is equivalent to calling translate("people.index.foo") or translate("bar", scope: "people.index.foo") respectively. This makes it less repetitive to translate many keys within the same partial and provides a convention to scope keys consistently. The key takes precedence: if the key itself starts with a period, the :scope option's own leading period is left as-is rather than expanded, preserving the pre-existing behavior for calls like translate(".bar", scope: ".foo").

Third, the translation will be marked as html_safe if the key has the suffix "_html" or the last element of the key is "html". Calling translate("footer_html") or translate("footer.html") will return an HTML safe string that won't be escaped by other HTML helper methods. This naming convention helps to identify translations that include HTML tags so that you know what kind of output to expect when you call translate in a template and translators know which keys they can provide HTML values for.

To access the translated text along with the fully resolved translation key, translate accepts a block:

<%= translate(".relative_key") do |translation, resolved_key| %>
  <span title="<%= resolved_key %>"><%= translation %></span>
<% end %>

This enables annotate translated text to be aware of the scope it was resolved against.

[ GitHub ]

# File 'actionview/lib/action_view/helpers/translation_helper.rb', line 79


def translate(key, **options)
  return key.map { |k| translate(k, **options) } if key.is_a?(Array)
  key = key&.to_s unless key.is_a?(Symbol)

  alternatives = if options.key?(:default)
    options[:default].is_a?(Array) ? options.delete(:default).compact : [options.delete(:default)]
  end

  options[:scope] = scope_option_by_partial(options[:scope]) if options[:scope] && !key&.start_with?(".")

  options[:raise] = true if options[:raise].nil? && TranslationHelper.raise_on_missing_translations
  default = MISSING_TRANSLATION

  translation = while key || alternatives.present?
    if alternatives.blank? && !options[:raise].nil?
      default = NO_DEFAULT # let I18n handle missing translation
    end

    key = scope_key_by_partial(key)

    translated = ActiveSupport::HtmlSafeTranslation.translate(key, **options, default: default)

    break translated unless translated == MISSING_TRANSLATION

    if alternatives.present? && !alternatives.first.is_a?(Symbol)
      break alternatives.first && I18n.translate(nil, **options, default: alternatives)
    end

    first_key ||= key
    key = alternatives&.shift
  end

  if key.nil? && !first_key.nil?
    translation = missing_translation(first_key, options)
    key = first_key
  end

  block_given? ? yield(translation, key) : translation
end

Module: ActionView::Helpers::TranslationHelper

Overview

Action View Translation Helpers

Constant Summary

TagHelper - Included

Class Method Summary

::ActiveSupport::Concern - Extended

Instance Attribute Summary

Instance Method Summary

TagHelper - Included

OutputSafetyHelper - Included

CaptureHelper - Included

DSL Calls

included

Instance Attribute Details

#raise_on_missing_translations (rw)

Instance Method Details

#l(object, **options)

#localize(object, **options) Also known as: #l

#missing_translation(key, options) (private)

#scope_key_by_partial(key) (private)

#scope_option_by_partial(scope) (private)

#scope_prefix (private)

#t(key, **options)

#translate(key, **options) Also known as: #t

`TagHelper` - Included

`::ActiveSupport::Concern` - Extended

`TagHelper` - Included

`OutputSafetyHelper` - Included

`CaptureHelper` - Included