Class: CMDx::I18nProxy

Inherits:
Object
  • Object
show all
Defined in:
lib/cmdx/i18n_proxy.rb

Overview

Translation façade used internally for coercion, validator, and output error messages. Delegates to ‘I18n.translate` when the `i18n` gem is available; otherwise loads CMDx’s bundled YAML locale file and performs percent-interpolation on the string itself. Results are memoized.

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.locale_paths ⇒ Array<String>

Returns directories searched (in order) for bundled locale YAMLs.

Returns:

  • (Array<String>) —

    directories searched (in order) for bundled locale YAMLs



13
14
15
 
# File 'lib/cmdx/i18n_proxy.rb', line 13

def locale_paths
  @locale_paths ||= [File.expand_path("../locales", __dir__)]
end

.register(path) ⇒ Array<String>

Register an additional directory containing locale YAML files. Later registrations take precedence over earlier ones (the most recently registered path’s values win during deep merge). Resets the memoized proxy so subsequent lookups see the new path.

Parameters:

  • path (String) —

    absolute path to a directory of ‘<locale>.yml` files

Returns:

  • (Array<String>) —

    the updated locale paths



41
42
43
44
45
 
# File 'lib/cmdx/i18n_proxy.rb', line 41

def register(path)
  locale_paths.push(path) unless locale_paths.include?(path)
  @proxy = nil
  locale_paths
end

.t(key, **options) ⇒ String, Object

Returns the translated string (or the raw default value).

Parameters:

  • key (String, Symbol) —

    dot-separated translation key

  • options (Hash{Symbol => Object}) —

    forwarded to ‘I18n.translate` or bundled interpolation

Options Hash (**options):

  • :default (Object) —

    fallback when the bundled YAML lookup misses

  • extra (Hash{Symbol => Object}) —

    keys interpolated via ‘String#%` for bundled translations

Returns:

  • (String, Object) —

    the translated string (or the raw default value)



30
31
32
 
# File 'lib/cmdx/i18n_proxy.rb', line 30

def t(key, **options)
  translate(key, **options)
end

.tr(reason) ⇒ String

Resolves a reason string through translation, falling back to either the literal reason (when present) or the ‘cmdx.reasons.unspecified` default (when nil).

Parameters:

  • reason (String, Symbol, nil) —

    reason text or translation key

Returns:

  • (String) —

    translated message, literal reason, or default



53
54
55
 
# File 'lib/cmdx/i18n_proxy.rb', line 53

def tr(reason)
  translate(reason || "cmdx.reasons.unspecified", default: reason)
end

.translate(key, **options) ⇒ String, Object

Returns the translated string (or the raw default value).

Parameters:

  • key (String, Symbol) —

    dot-separated translation key

  • options (Hash{Symbol => Object}) —

    forwarded to ‘I18n.translate` or bundled interpolation

Options Hash (**options):

  • :default (Object) —

    fallback when the bundled YAML lookup misses

  • extra (Hash{Symbol => Object}) —

    keys interpolated via ‘String#%` for bundled translations

Returns:

  • (String, Object) —

    the translated string (or the raw default value)



22
23
24
25
 
# File 'lib/cmdx/i18n_proxy.rb', line 22

def translate(key, **options)
  @proxy ||= new
  @proxy.translate(key, **options)
end

Instance Method Details

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

Returns the translated/interpolated message.

Parameters:

  • key (String, Symbol) —

    dot-separated translation key

  • options (Hash{Symbol => Object}) —

    interpolation values

Options Hash (**options):

  • :default (Object) —

    fallback when the bundled YAML lookup misses

  • extra (Hash{Symbol => Object}) —

    keys interpolated via ‘String#%` for bundled translations

Returns:

  • (String, Object) —

    the translated/interpolated message



64
65
66
67
68
69
70
71
72
73
74
75
76
77
 
# File 'lib/cmdx/i18n_proxy.rb', line 64

def translate(key, **options)
  return ::I18n.translate(key, **options) if defined?(::I18n) && ::I18n.respond_to?(:translate)

  message = translation_default(key) || options[:default]

  case message
  when String
    message % options
  when NilClass
    "Translation missing: #{key}"
  else
    message
  end
end