Module: Hanami::Helpers::I18nHelper

Included in:
Extensions::View::StandardHelpers
Defined in:
lib/hanami/helpers/i18n_helper.rb

Overview

Helper methods for translating and localizing content using the slice’s i18n backend.

These helpers will be automatically available in your view templates, part classes, and scope classes when the ‘i18n` gem is bundled.

Since:

  • x.x.x

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:

  • x.x.x

/(\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.

Examples:

<%= localize(Date.today, format: :long) %>

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:

  • x.x.x



128
129
130
 
# File 'lib/hanami/helpers/i18n_helper.rb', line 128

def localize(object, **options)
  _context.i18n.localize(object, **options)
end

#translate(key, **options) ⇒ String, Hanami::View::HTML::SafeString 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 currently-rendering template and expanded against its name (slashes become dots; partial basenames keep their leading underscore). For example, `translate(“.title”)` inside `users/index.html.erb` resolves to `users.index.title`, and `translate(“.label”)` inside `users/_form.html.erb` resolves to `users._form.label`. Raises `I18n::ArgumentError` if called outside a template render.

Examples:

Basic translation

<%= translate("messages.welcome") %>
# => "Welcome"

HTML-safe translation

# en.yml
#   greeting_html: "Hello, <strong>%{name}</strong>!"
<%= translate("greeting_html", name: "<script>") %>
# => "Hello, <strong>&lt;script&gt;</strong>!" (marked HTML-safe)

Missing translation

<%= translate("missing.key") %>
# => '<span class="translation_missing" title="...">missing.key</span>'

Relative key lookup

# In app/templates/users/index.html.erb:
<%= translate(".title") %>
# Looks up "users.index.title"

# In app/templates/users/_form.html.erb (a partial):
<%= translate(".label") %>
# Looks up "users._form.label"

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, Hanami::View::HTML::SafeString) —

    the translated string

Since:

  • x.x.x



69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
 
# File 'lib/hanami/helpers/i18n_helper.rb', line 69

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]
      _context.i18n.translate(key, **options)
    else
      begin
        _context.i18n.translate(key, **options, raise: true)
      rescue ::I18n::MissingTranslationData => exception
        return _missing_translation_markup(key, exception)
      end
    end

  html_safe ? result.to_s.html_safe : result
end

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

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

Examples:

<%= translate!("messages.welcome") %>

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, Hanami::View::HTML::SafeString) —

    the translated string

Raises:

  • (I18n::MissingTranslationData) —

    if the translation is missing

Since:

  • x.x.x



107
108
109
 
# File 'lib/hanami/helpers/i18n_helper.rb', line 107

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