Module: Hanami::Helpers::I18nHelper::Methods

Included in:
Extensions::Action::I18nHelper, Hanami::Helpers::I18nHelper
Defined in:
lib/hanami/helpers/i18n_helper.rb

Overview

Shared translate / localize (and shorthand) helper methods used by both view-layer consumers and action-layer consumers.

This module is abstract. Including modules must override two private hooks:

  • #_i18n — returns the i18n backend to delegate to.
  • #_resolve_i18n_key — expands relative (leading-dot) keys against the consumer's context, and is a no-op for absolute keys.

Since:

  • 3.0.0

Constant Summary collapse

HTML_SAFE_TRANSLATION_KEY =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.

Matches keys whose final segment is html or whose final segment ends in _html. These translated values are treated as HTML-safe and any string interpolation values are HTML-escaped before substitution.

Since:

  • 3.0.0

/(\b|_)html\z/

Instance Method Summary collapse

Instance Method Details

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

Localizes the given object (e.g. a date, time, or number) using the slice's i18n backend.

Parameters:

  • object (Date, Time, DateTime, Numeric) —

    the object to localize

  • options (Hash) —

    localization options forwarded to the backend (:locale, :format, etc.)

Returns:

  • (String) —

    the localized string

Since:

  • 3.0.0



140
141
142
 
# File 'lib/hanami/helpers/i18n_helper.rb', line 140

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

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

Translates the given key using the slice's i18n backend.

When the key's final segment is html or ends in _html, the result is marked HTML-safe and any string interpolation values are HTML-escaped first.

When a translation is missing and neither :default nor :raise was supplied, returns a <span class="translation_missing"> element containing the missing key, useful for spotting missing translations during development.

When the key begins with a ., it is treated as relative to the consumer's context and expanded by #_resolve_i18n_key.

Parameters:

  • key (String, Symbol) —

    the translation key to look up

  • options (Hash) —

    translation options forwarded to the backend (:locale, :scope, :default, :count, :raise, etc.), plus any interpolation values

Returns:

  • (String) —

    the translated string (marked HTML-safe when hanami-view is bundled and the key ends in _html or html)

Since:

  • 3.0.0



86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
 
# File 'lib/hanami/helpers/i18n_helper.rb', line 86

def translate(key, **options)
  key = _resolve_i18n_key(key)

  html_safe = _html_safe_translation_key?(key)

  options = _escape_translation_options(options) if html_safe

  result =
    if options.key?(:default) || options[:raise]
      _i18n.translate(key, **options)
    else
      begin
        _i18n.translate(key, **options, raise: true)
      rescue ::I18n::MissingTranslationData => exception
        return _missing_translation_markup(key, exception)
      end
    end

  html_safe ? _i18n_mark_html_safe(result.to_s) : result
end

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

Translates the given key, raising an exception if the translation is missing.

Parameters:

  • key (String, Symbol) —

    the translation key to look up

  • options (Hash) —

    translation options forwarded to the backend (:locale, :scope, :default, :count, :raise, etc.), plus any interpolation values

Returns:

  • (String) —

    the translated string (marked HTML-safe when hanami-view is bundled and the key ends in _html or html)

Raises:

  • (I18n::MissingTranslationData) —

    if the translation is missing

Since:

  • 3.0.0



122
123
124
 
# File 'lib/hanami/helpers/i18n_helper.rb', line 122

def translate!(key, **options)
  translate(key, **options, raise: true)
end