| 1 | package Mojolicious::Plugin::Buffer::I18N; | ||||||||||||||||||||||||||||||||
| 2 | |||||||||||||||||||||||||||||||||
| 3 | 39 | ▶ | use strict; | ||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||
| 4 | 39 | ▶ | use warnings; | ||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||
| 5 | 39 | ▶ | use autodie qw(:all); | ||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||
| 6 | |||||||||||||||||||||||||||||||||
| 7 | 39 | ▶ | use Carp qw(croak); | ||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||
| 8 | 39 | ▶ | use Exporter qw(import); | ||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||
| 9 | 39 | ▶ | use Params::Get qw(get_params); | ||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||
| 10 | 39 | ▶ | use Params::Validate::Strict qw(validate_strict); | ||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||
| 11 | 39 | ▶ | use Readonly; | ||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||
| 12 | 39 | ▶ | use Scalar::Util qw(blessed looks_like_number); | ||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||
| 13 | 39 | ▶ | use Sub::Private { mode => 'enforce' }; | ||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||
| 14 | |||||||||||||||||||||||||||||||||
| 15 | 39 | ▶ | use version; our $VERSION = version->declare('0.002.0'); | ||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||
| 16 | |||||||||||||||||||||||||||||||||
| 17 | # Classes that want the i18n() method import it rather than inheriting it, so | ||||||||||||||||||||||||||||||||
| 18 | # the plugin keeps Mojolicious::Plugin as its only base class | ||||||||||||||||||||||||||||||||
| 19 | 39 | our @EXPORT_OK = qw(i18n); | |||||||||||||||||||||||||||||||
| 20 | |||||||||||||||||||||||||||||||||
| 21 | # A placeholder is %{name}, or %{name:FORMAT} where FORMAT is a single | ||||||||||||||||||||||||||||||||
| 22 | # sprintf conversion such as %d or %.1f. The conversion letters are limited | ||||||||||||||||||||||||||||||||
| 23 | # so a translated string cannot smuggle in a vector flag or a %n. | ||||||||||||||||||||||||||||||||
| 24 | 39 | Readonly::Scalar my $PLACEHOLDER => qr/(%\{(\w+)(?::(%[-+ 0#]*\d*(?:\.\d+)?[sdufeEgGxXob]))?\})/; | |||||||||||||||||||||||||||||||
| 25 | |||||||||||||||||||||||||||||||||
| 26 | # How deeply variant hashes (gender inside plural, or the reverse) may nest | ||||||||||||||||||||||||||||||||
| 27 | # before the lookup gives up; it stops a self-referencing catalog looping | ||||||||||||||||||||||||||||||||
| 28 | 39 | Readonly::Scalar my $MAX_VARIANT_DEPTH => 4; | |||||||||||||||||||||||||||||||
| 29 | |||||||||||||||||||||||||||||||||
| 30 | # Input schema for i18n(), shared by the code and the POD | ||||||||||||||||||||||||||||||||
| 31 | 39 | Readonly::Hash my %I18N_SCHEMA => ( | |||||||||||||||||||||||||||||||
| 32 | key => {type => 'string', min => 1}, | ||||||||||||||||||||||||||||||||
| 33 | args => {type => 'hashref', optional => 1}, | ||||||||||||||||||||||||||||||||
| 34 | ); | ||||||||||||||||||||||||||||||||
| 35 | |||||||||||||||||||||||||||||||||
| 36 | # The English catalog. Every user-facing string, error and log line in the | ||||||||||||||||||||||||||||||||
| 37 | # distribution lives here so that it can be translated or reworded with the | ||||||||||||||||||||||||||||||||
| 38 | # messages option instead of by editing code. | ||||||||||||||||||||||||||||||||
| 39 | 39 | Readonly::Hash my %MESSAGES => ( | |||||||||||||||||||||||||||||||
| 40 | # Programming errors in a caller of i18n() itself | ||||||||||||||||||||||||||||||||
| 41 | i18n_key_missing => 'Mojolicious::Plugin::Buffer::I18N: a message key is required', | ||||||||||||||||||||||||||||||||
| 42 | |||||||||||||||||||||||||||||||||
| 43 | # Plugin registration | ||||||||||||||||||||||||||||||||
| 44 | options_not_hash => 'Mojolicious::Plugin::Buffer: options must be a hash reference', | ||||||||||||||||||||||||||||||||
| 45 | unknown_option => q{Mojolicious::Plugin::Buffer: unknown option '%{option}'}, | ||||||||||||||||||||||||||||||||
| 46 | option_invalid => 'Mojolicious::Plugin::Buffer: %{option} has an invalid value', | ||||||||||||||||||||||||||||||||
| 47 | option_flag => 'Mojolicious::Plugin::Buffer: %{option} must be a true or false value', | ||||||||||||||||||||||||||||||||
| 48 | option_optimise_content => 'Mojolicious::Plugin::Buffer: optimise_content must be 0, 1 or 2', | ||||||||||||||||||||||||||||||||
| 49 | option_last_modified => 'Mojolicious::Plugin::Buffer: last_modified must be 0, 1, an epoch, a date string or a code reference', | ||||||||||||||||||||||||||||||||
| 50 | option_min_compress_size => 'Mojolicious::Plugin::Buffer: min_compress_size must be a non-negative integer', | ||||||||||||||||||||||||||||||||
| 51 | option_min_compress_saving => 'Mojolicious::Plugin::Buffer: min_compress_saving must be a non-negative integer', | ||||||||||||||||||||||||||||||||
| 52 | option_encodings => 'Mojolicious::Plugin::Buffer: encodings must be an array reference', | ||||||||||||||||||||||||||||||||
| 53 | option_compressible_types => 'Mojolicious::Plugin::Buffer: compressible_types must be an array reference', | ||||||||||||||||||||||||||||||||
| 54 | option_excluded_types => 'Mojolicious::Plugin::Buffer: excluded_types must be an array reference', | ||||||||||||||||||||||||||||||||
| 55 | option_vary_by => 'Mojolicious::Plugin::Buffer: vary_by must be an array reference of header names', | ||||||||||||||||||||||||||||||||
| 56 | option_cache_key => 'Mojolicious::Plugin::Buffer: cache_key must be a string or a code reference', | ||||||||||||||||||||||||||||||||
| 57 | option_cache => 'Mojolicious::Plugin::Buffer: cache must be an object understanding get(), set() and remove()', | ||||||||||||||||||||||||||||||||
| 58 | option_cache_duration => 'Mojolicious::Plugin::Buffer: cache_duration must be a duration', | ||||||||||||||||||||||||||||||||
| 59 | option_template_mtime_cache => 'Mojolicious::Plugin::Buffer: template_mtime_cache must be an object understanding get() and set()', | ||||||||||||||||||||||||||||||||
| 60 | option_template_mtime_cache_duration => 'Mojolicious::Plugin::Buffer: template_mtime_cache_duration must be a duration', | ||||||||||||||||||||||||||||||||
| 61 | option_cache_lock_timeout => 'Mojolicious::Plugin::Buffer: cache_lock_timeout must be a positive number of seconds', | ||||||||||||||||||||||||||||||||
| 62 | option_cache_lock => 'Mojolicious::Plugin::Buffer: cache_lock must be an object with acquire() and release() methods', | ||||||||||||||||||||||||||||||||
| 63 | option_cache_lock_dir => 'Mojolicious::Plugin::Buffer: cache_lock_dir must be a directory path', | ||||||||||||||||||||||||||||||||
| 64 | option_messages => 'Mojolicious::Plugin::Buffer: messages must be a hash reference', | ||||||||||||||||||||||||||||||||
| 65 | lock_options_combined => 'Mojolicious::Plugin::Buffer: cache_lock and cache_lock_dir cannot be combined', | ||||||||||||||||||||||||||||||||
| 66 | unknown_encoding => q{Mojolicious::Plugin::Buffer: unknown encoding '%{encoding}'}, | ||||||||||||||||||||||||||||||||
| 67 | |||||||||||||||||||||||||||||||||
| 68 | # Sent to a client while another request builds the page | ||||||||||||||||||||||||||||||||
| 69 | retry_later => "The page is being generated, please try again.\n", | ||||||||||||||||||||||||||||||||
| 70 | |||||||||||||||||||||||||||||||||
| 71 | # File lock backend | ||||||||||||||||||||||||||||||||
| 72 | lock_dir_create_failed => q{Mojolicious::Plugin::Buffer: cannot create cache_lock_dir '%{dir}': %{error}}, | ||||||||||||||||||||||||||||||||
| 73 | lock_dir_not_writable => q{Mojolicious::Plugin::Buffer: cache_lock_dir '%{dir}' is not a writable directory}, | ||||||||||||||||||||||||||||||||
| 74 | lock_key_undefined => 'cache key is not defined', | ||||||||||||||||||||||||||||||||
| 75 | lock_open_failed => 'cannot open %{path}: %{error}', | ||||||||||||||||||||||||||||||||
| 76 | lock_failed => 'cannot lock %{path}: %{error}', | ||||||||||||||||||||||||||||||||
| 77 | unlock_failed => 'cannot unlock %{path}: %{error}', | ||||||||||||||||||||||||||||||||
| 78 | |||||||||||||||||||||||||||||||||
| 79 | # Redis lock backend | ||||||||||||||||||||||||||||||||
| 80 | redis_client_invalid => 'Mojolicious::Plugin::Buffer: cache_lock redis must be an object with an eval() method or a code reference returning one', | ||||||||||||||||||||||||||||||||
| 81 | redis_namespace_invalid => 'Mojolicious::Plugin::Buffer: cache_lock namespace must be a non-empty string', | ||||||||||||||||||||||||||||||||
| 82 | redis_ttl_invalid => 'Mojolicious::Plugin::Buffer: cache_lock ttl must be a positive number of seconds', | ||||||||||||||||||||||||||||||||
| 83 | redis_no_client => 'Redis client factory returned no client', | ||||||||||||||||||||||||||||||||
| 84 | redis_no_result => 'Redis lock command returned no result', | ||||||||||||||||||||||||||||||||
| 85 | redis_lock_failed => 'Redis lock failed: %{error}', | ||||||||||||||||||||||||||||||||
| 86 | redis_unlock_failed => 'Redis unlock failed: %{error}', | ||||||||||||||||||||||||||||||||
| 87 | redis_invalid_guard => 'invalid lock guard', | ||||||||||||||||||||||||||||||||
| 88 | |||||||||||||||||||||||||||||||||
| 89 | # Log lines written while serving requests | ||||||||||||||||||||||||||||||||
| 90 | log_no_packer => 'Buffer: HTML::Packer is not installed, optimising white space only', | ||||||||||||||||||||||||||||||||
| 91 | log_declaration_failed => 'Buffer: %{method} failed: %{error}', | ||||||||||||||||||||||||||||||||
| 92 | log_release_failed => 'Buffer: could not release waiting requests: %{error}', | ||||||||||||||||||||||||||||||||
| 93 | log_optimised => { | ||||||||||||||||||||||||||||||||
| 94 | one => 'Buffer: optimised HTML from %{from} to %{to} byte', | ||||||||||||||||||||||||||||||||
| 95 | other => 'Buffer: optimised HTML from %{from} to %{to} bytes', | ||||||||||||||||||||||||||||||||
| 96 | }, | ||||||||||||||||||||||||||||||||
| 97 | log_compressed => { | ||||||||||||||||||||||||||||||||
| 98 | one => 'Buffer: compressed with %{encoding} from %{from} to %{to} byte', | ||||||||||||||||||||||||||||||||
| 99 | other => 'Buffer: compressed with %{encoding} from %{from} to %{to} bytes', | ||||||||||||||||||||||||||||||||
| 100 | }, | ||||||||||||||||||||||||||||||||
| 101 | log_compress_failed => 'Buffer: %{encoding} compression failed: %{error}', | ||||||||||||||||||||||||||||||||
| 102 | log_packer_failed => 'Buffer: HTML::Packer failed: %{error}', | ||||||||||||||||||||||||||||||||
| 103 | log_not_modified => 'Buffer: not modified, sending 304', | ||||||||||||||||||||||||||||||||
| 104 | log_not_modified_etag => 'Buffer: not modified, sending 304 (ETag %{etag})', | ||||||||||||||||||||||||||||||||
| 105 | log_cache_hit => 'Buffer: cache hit for %{key}', | ||||||||||||||||||||||||||||||||
| 106 | log_cache_get_failed => 'Buffer: cache get failed: %{error}', | ||||||||||||||||||||||||||||||||
| 107 | log_cache_set_failed => 'Buffer: cache set failed: %{error}', | ||||||||||||||||||||||||||||||||
| 108 | log_cached => 'Buffer: cached the response for %{key}', | ||||||||||||||||||||||||||||||||
| 109 | log_stale_entry => 'Buffer: discarding a cache entry older than the application or its templates', | ||||||||||||||||||||||||||||||||
| 110 | log_lock_failed => 'Buffer: shared cache lock failed: %{error}', | ||||||||||||||||||||||||||||||||
| 111 | log_unlock_failed => 'Buffer: shared cache unlock failed: %{error}', | ||||||||||||||||||||||||||||||||
| 112 | unknown_error => 'unknown error', | ||||||||||||||||||||||||||||||||
| 113 | log_building => 'Buffer: this request will build the cache entry for %{key}', | ||||||||||||||||||||||||||||||||
| 114 | log_waiting => 'Buffer: waiting for the cache entry for %{key}', | ||||||||||||||||||||||||||||||||
| 115 | log_waiting_worker => 'Buffer: waiting for another worker to build the cache entry for %{key}', | ||||||||||||||||||||||||||||||||
| 116 | log_gave_up => 'Buffer: gave up waiting for another request to finish', | ||||||||||||||||||||||||||||||||
| 117 | log_gave_up_worker => 'Buffer: gave up waiting for another worker', | ||||||||||||||||||||||||||||||||
| 118 | log_filled_elsewhere => 'Buffer: another worker filled the cache entry', | ||||||||||||||||||||||||||||||||
| 119 | log_not_cached_elsewhere => 'Buffer: the other worker did not cache a response', | ||||||||||||||||||||||||||||||||
| 120 | log_finish_waiter_failed => 'Buffer: could not finish a waiting request: %{error}', | ||||||||||||||||||||||||||||||||
| 121 | log_flight_expired => 'Buffer: an in-flight response did not finish in time', | ||||||||||||||||||||||||||||||||
| 122 | log_serving_waiter => 'Buffer: serving a waiting request from the finished response', | ||||||||||||||||||||||||||||||||
| 123 | log_uncacheable_flight => 'Buffer: the in-flight response could not be cached', | ||||||||||||||||||||||||||||||||
| 124 | log_mtime_get_failed => 'Buffer: template mtime cache get failed: %{error}', | ||||||||||||||||||||||||||||||||
| 125 | log_mtime_set_failed => 'Buffer: template mtime cache set failed: %{error}', | ||||||||||||||||||||||||||||||||
| 126 | log_mtime_not_stored => 'Buffer: template mtime cache did not store the scan', | ||||||||||||||||||||||||||||||||
| 127 | ); | ||||||||||||||||||||||||||||||||
| 128 | |||||||||||||||||||||||||||||||||
| 129 | =encoding utf8 | ||||||||||||||||||||||||||||||||
| 130 | |||||||||||||||||||||||||||||||||
| 131 | =head1 NAME | ||||||||||||||||||||||||||||||||
| 132 | |||||||||||||||||||||||||||||||||
| 133 | Mojolicious::Plugin::Buffer::I18N - message catalog for Mojolicious::Plugin::Buffer | ||||||||||||||||||||||||||||||||
| 134 | |||||||||||||||||||||||||||||||||
| 135 | =head1 VERSION | ||||||||||||||||||||||||||||||||
| 136 | |||||||||||||||||||||||||||||||||
| 137 | Version 0.002.0 | ||||||||||||||||||||||||||||||||
| 138 | |||||||||||||||||||||||||||||||||
| 139 | =head1 SYNOPSIS | ||||||||||||||||||||||||||||||||
| 140 | |||||||||||||||||||||||||||||||||
| 141 | Translate the text that visitors see when the server is busy (an | ||||||||||||||||||||||||||||||||
| 142 | application using L<Mojolicious::Plugin::Buffer>): | ||||||||||||||||||||||||||||||||
| 143 | |||||||||||||||||||||||||||||||||
| 144 | plugin 'Buffer' => { | ||||||||||||||||||||||||||||||||
| 145 | messages => { | ||||||||||||||||||||||||||||||||
| 146 | retry_later => "Die Seite wird erstellt, bitte versuchen Sie es erneut.\n", | ||||||||||||||||||||||||||||||||
| 147 | }, | ||||||||||||||||||||||||||||||||
| 148 | }; | ||||||||||||||||||||||||||||||||
| 149 | |||||||||||||||||||||||||||||||||
| 150 | Reword a log line, keeping its plural forms. Give I<every> form, because an | ||||||||||||||||||||||||||||||||
| 151 | override replaces the whole message: | ||||||||||||||||||||||||||||||||
| 152 | |||||||||||||||||||||||||||||||||
| 153 | plugin 'Buffer' => { | ||||||||||||||||||||||||||||||||
| 154 | messages => { | ||||||||||||||||||||||||||||||||
| 155 | log_compressed => { | ||||||||||||||||||||||||||||||||
| 156 | one => 'packed %{from} -> %{to} byte (%{encoding})', | ||||||||||||||||||||||||||||||||
| 157 | other => 'packed %{from} -> %{to} bytes (%{encoding})', | ||||||||||||||||||||||||||||||||
| 158 | }, | ||||||||||||||||||||||||||||||||
| 159 | }, | ||||||||||||||||||||||||||||||||
| 160 | }; | ||||||||||||||||||||||||||||||||
| 161 | |||||||||||||||||||||||||||||||||
| 162 | Use a code reference for a language whose plural rules need more than | ||||||||||||||||||||||||||||||||
| 163 | C<zero>, C<one> and C<other>, such as Polish: | ||||||||||||||||||||||||||||||||
| 164 | |||||||||||||||||||||||||||||||||
| 165 | plugin 'Buffer' => { | ||||||||||||||||||||||||||||||||
| 166 | messages => { | ||||||||||||||||||||||||||||||||
| 167 | log_optimised => sub { | ||||||||||||||||||||||||||||||||
| 168 | my $args = shift; | ||||||||||||||||||||||||||||||||
| 169 | my $n = $args->{count}; | ||||||||||||||||||||||||||||||||
| 170 | my $word = $n == 1 ? 'bajt' | ||||||||||||||||||||||||||||||||
| 171 | : ($n % 10 >= 2 && $n % 10 <= 4 && ($n % 100 < 10 || $n % 100 >= 20)) ? 'bajty' | ||||||||||||||||||||||||||||||||
| 172 | : 'bajtow'; | ||||||||||||||||||||||||||||||||
| 173 | return "Buffer: HTML z %{from} do %{to} $word"; | ||||||||||||||||||||||||||||||||
| 174 | }, | ||||||||||||||||||||||||||||||||
| 175 | }, | ||||||||||||||||||||||||||||||||
| 176 | }; | ||||||||||||||||||||||||||||||||
| 177 | |||||||||||||||||||||||||||||||||
| 178 | Use the catalog in your own class. The method reads the overrides from the | ||||||||||||||||||||||||||||||||
| 179 | C<messages> key of the object: | ||||||||||||||||||||||||||||||||
| 180 | |||||||||||||||||||||||||||||||||
| 181 | package My::Thing; | ||||||||||||||||||||||||||||||||
| 182 | use Mojolicious::Plugin::Buffer::I18N qw(i18n); | ||||||||||||||||||||||||||||||||
| 183 | |||||||||||||||||||||||||||||||||
| 184 | sub new { my ($class, %args) = @_; return bless {messages => $args{messages}}, $class } | ||||||||||||||||||||||||||||||||
| 185 | |||||||||||||||||||||||||||||||||
| 186 | my $thing = My::Thing->new(messages => {unknown_option => q{No such option: %{option}}}); | ||||||||||||||||||||||||||||||||
| 187 | print $thing->i18n('unknown_option', {option => 'wibble'}); | ||||||||||||||||||||||||||||||||
| 188 | # No such option: wibble | ||||||||||||||||||||||||||||||||
| 189 | |||||||||||||||||||||||||||||||||
| 190 | List every key, for example to start a translation: | ||||||||||||||||||||||||||||||||
| 191 | |||||||||||||||||||||||||||||||||
| 192 | my $catalog = Mojolicious::Plugin::Buffer::I18N->catalog; | ||||||||||||||||||||||||||||||||
| 193 | print "$_\n" for sort keys %$catalog; | ||||||||||||||||||||||||||||||||
| 194 | |||||||||||||||||||||||||||||||||
| 195 | =head1 DESCRIPTION | ||||||||||||||||||||||||||||||||
| 196 | |||||||||||||||||||||||||||||||||
| 197 | Every error, warning, log line and client-facing string produced by | ||||||||||||||||||||||||||||||||
| 198 | L<Mojolicious::Plugin::Buffer> and its lock backends is looked up here by a | ||||||||||||||||||||||||||||||||
| 199 | I<message key>, so none of them is written into the program logic. An | ||||||||||||||||||||||||||||||||
| 200 | application can replace any of them with the C<messages> option of the | ||||||||||||||||||||||||||||||||
| 201 | plugin, or the C<messages> attribute of a lock backend. | ||||||||||||||||||||||||||||||||
| 202 | |||||||||||||||||||||||||||||||||
| 203 | =head2 How it works, in plain words | ||||||||||||||||||||||||||||||||
| 204 | |||||||||||||||||||||||||||||||||
| 205 | =over 4 | ||||||||||||||||||||||||||||||||
| 206 | |||||||||||||||||||||||||||||||||
| 207 | =item 1. The program asks for a message by its key, for example | ||||||||||||||||||||||||||||||||
| 208 | C<unknown_option>, and passes some values, for example | ||||||||||||||||||||||||||||||||
| 209 | C<< {option =E<gt> 'wibble'} >>. | ||||||||||||||||||||||||||||||||
| 210 | |||||||||||||||||||||||||||||||||
| 211 | =item 2. The object's own C<messages> hash is checked first. If it has the | ||||||||||||||||||||||||||||||||
| 212 | key, that text is used. If not, the built-in English text is used. | ||||||||||||||||||||||||||||||||
| 213 | |||||||||||||||||||||||||||||||||
| 214 | =item 3. If the text has several forms (for plural or gender), the right | ||||||||||||||||||||||||||||||||
| 215 | form is chosen from the C<count> and C<gender> values. | ||||||||||||||||||||||||||||||||
| 216 | |||||||||||||||||||||||||||||||||
| 217 | =item 4. Each placeholder, such as C<%{option}>, is replaced by its value. | ||||||||||||||||||||||||||||||||
| 218 | |||||||||||||||||||||||||||||||||
| 219 | =item 5. If anything goes wrong (an unknown key, a missing form, a code | ||||||||||||||||||||||||||||||||
| 220 | reference that dies), the key itself is returned. So you always see | ||||||||||||||||||||||||||||||||
| 221 | I<something>, never an empty message. | ||||||||||||||||||||||||||||||||
| 222 | |||||||||||||||||||||||||||||||||
| 223 | =back | ||||||||||||||||||||||||||||||||
| 224 | |||||||||||||||||||||||||||||||||
| 225 | =head2 Words used in this document | ||||||||||||||||||||||||||||||||
| 226 | |||||||||||||||||||||||||||||||||
| 227 | =over 4 | ||||||||||||||||||||||||||||||||
| 228 | |||||||||||||||||||||||||||||||||
| 229 | =item key | ||||||||||||||||||||||||||||||||
| 230 | |||||||||||||||||||||||||||||||||
| 231 | The name of a message, for example C<retry_later>. Keys are ASCII words. | ||||||||||||||||||||||||||||||||
| 232 | |||||||||||||||||||||||||||||||||
| 233 | =item template | ||||||||||||||||||||||||||||||||
| 234 | |||||||||||||||||||||||||||||||||
| 235 | The text stored for a key, before placeholders are filled in. | ||||||||||||||||||||||||||||||||
| 236 | |||||||||||||||||||||||||||||||||
| 237 | =item placeholder | ||||||||||||||||||||||||||||||||
| 238 | |||||||||||||||||||||||||||||||||
| 239 | A marker in a template, written C<%{name}>, that is replaced by a value. | ||||||||||||||||||||||||||||||||
| 240 | |||||||||||||||||||||||||||||||||
| 241 | =item variant | ||||||||||||||||||||||||||||||||
| 242 | |||||||||||||||||||||||||||||||||
| 243 | One form of a message that has several forms, such as the singular form | ||||||||||||||||||||||||||||||||
| 244 | C<one> and the plural form C<other>. | ||||||||||||||||||||||||||||||||
| 245 | |||||||||||||||||||||||||||||||||
| 246 | =back | ||||||||||||||||||||||||||||||||
| 247 | |||||||||||||||||||||||||||||||||
| 248 | =head2 Templates | ||||||||||||||||||||||||||||||||
| 249 | |||||||||||||||||||||||||||||||||
| 250 | A template is one of these three things: | ||||||||||||||||||||||||||||||||
| 251 | |||||||||||||||||||||||||||||||||
| 252 | =over 4 | ||||||||||||||||||||||||||||||||
| 253 | |||||||||||||||||||||||||||||||||
| 254 | =item a string | ||||||||||||||||||||||||||||||||
| 255 | |||||||||||||||||||||||||||||||||
| 256 | Placeholders are written C<%{name}>, or C<%{name:FORMAT}> where C<FORMAT> is | ||||||||||||||||||||||||||||||||
| 257 | a single C<sprintf> conversion such as C<%d>, C<%5.1f> or C<%x>. A | ||||||||||||||||||||||||||||||||
| 258 | placeholder whose argument was not supplied is left in the text unchanged, | ||||||||||||||||||||||||||||||||
| 259 | so a missing argument is visible rather than silently blank. An argument | ||||||||||||||||||||||||||||||||
| 260 | that is present but undefined becomes the empty string. | ||||||||||||||||||||||||||||||||
| 261 | |||||||||||||||||||||||||||||||||
| 262 | =item a hash of variants | ||||||||||||||||||||||||||||||||
| 263 | |||||||||||||||||||||||||||||||||
| 264 | Used for plurals and grammatical gender. The rules are tried in this | ||||||||||||||||||||||||||||||||
| 265 | order: | ||||||||||||||||||||||||||||||||
| 266 | |||||||||||||||||||||||||||||||||
| 267 | =over 4 | ||||||||||||||||||||||||||||||||
| 268 | |||||||||||||||||||||||||||||||||
| 269 | =item 1. If the C<gender> argument is a key of the hash, that variant is | ||||||||||||||||||||||||||||||||
| 270 | used. | ||||||||||||||||||||||||||||||||
| 271 | |||||||||||||||||||||||||||||||||
| 272 | =item 2. Otherwise, if C<count> is a number: C<zero> is used for 0 and | ||||||||||||||||||||||||||||||||
| 273 | C<one> for 1, when those keys exist. | ||||||||||||||||||||||||||||||||
| 274 | |||||||||||||||||||||||||||||||||
| 275 | =item 3. Otherwise C<other> is used. | ||||||||||||||||||||||||||||||||
| 276 | |||||||||||||||||||||||||||||||||
| 277 | =back | ||||||||||||||||||||||||||||||||
| 278 | |||||||||||||||||||||||||||||||||
| 279 | Variants may be nested, for example gender variants whose values are plural | ||||||||||||||||||||||||||||||||
| 280 | variants. Nesting stops after 4 levels. | ||||||||||||||||||||||||||||||||
| 281 | |||||||||||||||||||||||||||||||||
| 282 | =item a code reference | ||||||||||||||||||||||||||||||||
| 283 | |||||||||||||||||||||||||||||||||
| 284 | Called with the argument hash. It returns a string or a hash of variants. | ||||||||||||||||||||||||||||||||
| 285 | Use it for languages whose plural rules cannot be written with C<zero>, | ||||||||||||||||||||||||||||||||
| 286 | C<one> and C<other>. If it dies, the message key is used instead. | ||||||||||||||||||||||||||||||||
| 287 | |||||||||||||||||||||||||||||||||
| 288 | =back | ||||||||||||||||||||||||||||||||
| 289 | |||||||||||||||||||||||||||||||||
| 290 | =head1 METHODS | ||||||||||||||||||||||||||||||||
| 291 | |||||||||||||||||||||||||||||||||
| 292 | =head2 i18n | ||||||||||||||||||||||||||||||||
| 293 | |||||||||||||||||||||||||||||||||
| 294 | my $text = $self->i18n($key, \%args); | ||||||||||||||||||||||||||||||||
| 295 | |||||||||||||||||||||||||||||||||
| 296 | =head3 Purpose | ||||||||||||||||||||||||||||||||
| 297 | |||||||||||||||||||||||||||||||||
| 298 | Turn a message key and its arguments into text. It is exported on request | ||||||||||||||||||||||||||||||||
| 299 | and called as a method, so overrides held by the calling object take | ||||||||||||||||||||||||||||||||
| 300 | precedence over the English catalog. | ||||||||||||||||||||||||||||||||
| 301 | |||||||||||||||||||||||||||||||||
| 302 | =head3 Arguments | ||||||||||||||||||||||||||||||||
| 303 | |||||||||||||||||||||||||||||||||
| 304 | =over 4 | ||||||||||||||||||||||||||||||||
| 305 | |||||||||||||||||||||||||||||||||
| 306 | =item C<$key> (positional, required) | ||||||||||||||||||||||||||||||||
| 307 | |||||||||||||||||||||||||||||||||
| 308 | The message key, a non-empty string such as C<'unknown_option'>. | ||||||||||||||||||||||||||||||||
| 309 | |||||||||||||||||||||||||||||||||
| 310 | =item C<$args> (positional, optional) | ||||||||||||||||||||||||||||||||
| 311 | |||||||||||||||||||||||||||||||||
| 312 | A hash reference of values for the placeholders, plus the optional | ||||||||||||||||||||||||||||||||
| 313 | selectors C<count> and C<gender>. | ||||||||||||||||||||||||||||||||
| 314 | |||||||||||||||||||||||||||||||||
| 315 | =back | ||||||||||||||||||||||||||||||||
| 316 | |||||||||||||||||||||||||||||||||
| 317 | =head3 Returns | ||||||||||||||||||||||||||||||||
| 318 | |||||||||||||||||||||||||||||||||
| 319 | The text of the message. For an unknown key the key itself is returned, so | ||||||||||||||||||||||||||||||||
| 320 | a missing translation never hides that something happened. | ||||||||||||||||||||||||||||||||
| 321 | |||||||||||||||||||||||||||||||||
| 322 | =head3 Side effects | ||||||||||||||||||||||||||||||||
| 323 | |||||||||||||||||||||||||||||||||
| 324 | None. If the invocant is a blessed hash with a C<messages> hash, its entries | ||||||||||||||||||||||||||||||||
| 325 | are consulted first; nothing is written. | ||||||||||||||||||||||||||||||||
| 326 | |||||||||||||||||||||||||||||||||
| 327 | =head3 Example | ||||||||||||||||||||||||||||||||
| 328 | |||||||||||||||||||||||||||||||||
| 329 | use Mojolicious::Plugin::Buffer::I18N qw(i18n); | ||||||||||||||||||||||||||||||||
| 330 | |||||||||||||||||||||||||||||||||
| 331 | # Class method: the English catalog | ||||||||||||||||||||||||||||||||
| 332 | print __PACKAGE__->i18n('unknown_encoding', {encoding => 'lzma'}); | ||||||||||||||||||||||||||||||||
| 333 | # Mojolicious::Plugin::Buffer: unknown encoding 'lzma' | ||||||||||||||||||||||||||||||||
| 334 | |||||||||||||||||||||||||||||||||
| 335 | # Plural selection with a sprintf conversion | ||||||||||||||||||||||||||||||||
| 336 | my $self = bless {messages => { | ||||||||||||||||||||||||||||||||
| 337 | items => { | ||||||||||||||||||||||||||||||||
| 338 | one => '%{count} item weighs %{kg:%.1f} kg', | ||||||||||||||||||||||||||||||||
| 339 | other => '%{count} items weigh %{kg:%.1f} kg', | ||||||||||||||||||||||||||||||||
| 340 | }, | ||||||||||||||||||||||||||||||||
| 341 | }}, __PACKAGE__; | ||||||||||||||||||||||||||||||||
| 342 | print $self->i18n('items', {count => 3, kg => 2.25}); | ||||||||||||||||||||||||||||||||
| 343 | # 3 items weigh 2.2 kg | ||||||||||||||||||||||||||||||||
| 344 | |||||||||||||||||||||||||||||||||
| 345 | =head3 API SPECIFICATION | ||||||||||||||||||||||||||||||||
| 346 | |||||||||||||||||||||||||||||||||
| 347 | =head4 Input | ||||||||||||||||||||||||||||||||
| 348 | |||||||||||||||||||||||||||||||||
| 349 | # Params::Get::get_params([qw(key args)], @_) then | ||||||||||||||||||||||||||||||||
| 350 | # Params::Validate::Strict::validate_strict | ||||||||||||||||||||||||||||||||
| 351 | { | ||||||||||||||||||||||||||||||||
| 352 | key => { type => 'string', min => 1 }, | ||||||||||||||||||||||||||||||||
| 353 | args => { type => 'hashref', optional => 1 }, | ||||||||||||||||||||||||||||||||
| 354 | } | ||||||||||||||||||||||||||||||||
| 355 | |||||||||||||||||||||||||||||||||
| 356 | =head4 Output | ||||||||||||||||||||||||||||||||
| 357 | |||||||||||||||||||||||||||||||||
| 358 | # Return::Set schema | ||||||||||||||||||||||||||||||||
| 359 | { type => 'string' } | ||||||||||||||||||||||||||||||||
| 360 | |||||||||||||||||||||||||||||||||
| 361 | =head3 MESSAGES | ||||||||||||||||||||||||||||||||
| 362 | |||||||||||||||||||||||||||||||||
| 363 | Key / Message Meaning Resolution | ||||||||||||||||||||||||||||||||
| 364 | ---------------------------------------- ------------------------------ ---------------------------- | ||||||||||||||||||||||||||||||||
| 365 | i18n_key_missing No key was passed Pass a message key | ||||||||||||||||||||||||||||||||
| 366 | "a message key is required" | ||||||||||||||||||||||||||||||||
| 367 | validate_strict: Parameter 'key' ... The key was empty or not a Pass a non-empty string key | ||||||||||||||||||||||||||||||||
| 368 | string | ||||||||||||||||||||||||||||||||
| 369 | validate_strict: Parameter 'args' ... The arguments were not a hash Pass a hash reference | ||||||||||||||||||||||||||||||||
| 370 | |||||||||||||||||||||||||||||||||
| 371 | All three croak. The last two come from L<Params::Validate::Strict> and are | ||||||||||||||||||||||||||||||||
| 372 | not translated, because they report a programming error in the caller | ||||||||||||||||||||||||||||||||
| 373 | rather than a condition a user can act on. | ||||||||||||||||||||||||||||||||
| 374 | |||||||||||||||||||||||||||||||||
| 375 | =head3 PSEUDOCODE | ||||||||||||||||||||||||||||||||
| 376 | |||||||||||||||||||||||||||||||||
| 377 | croak if there is no key | ||||||||||||||||||||||||||||||||
| 378 | validate key and args | ||||||||||||||||||||||||||||||||
| 379 | look the key up in the invocant's overrides, then in the catalog | ||||||||||||||||||||||||||||||||
| 380 | if it is not found, return the key | ||||||||||||||||||||||||||||||||
| 381 | while the template is a code reference or a hash of variants, | ||||||||||||||||||||||||||||||||
| 382 | and the nesting limit has not been reached: | ||||||||||||||||||||||||||||||||
| 383 | call the code reference, or pick the variant for gender/count | ||||||||||||||||||||||||||||||||
| 384 | if the result is not a plain string, return the key | ||||||||||||||||||||||||||||||||
| 385 | replace every %{name} or %{name:FORMAT} whose argument exists | ||||||||||||||||||||||||||||||||
| 386 | return the text | ||||||||||||||||||||||||||||||||
| 387 | |||||||||||||||||||||||||||||||||
| 388 | =cut | ||||||||||||||||||||||||||||||||
| 389 | |||||||||||||||||||||||||||||||||
| 390 | 201 | ▶ | sub i18n { | ||||||||||||||||||||||||||||||
|
Subroutine
i18n: called CC=7 SCAR=19.5
Pod
documented
| |||||||||||||||||||||||||||||||||
| 391 | 201 | my ($self, $key, $args) = @_; | |||||||||||||||||||||||||||||||
| 392 | |||||||||||||||||||||||||||||||||
| 393 | # The commonest misuse gets its own message; the schema covers the rest | ||||||||||||||||||||||||||||||||
| 394 | 201 | ▶ | croak(__PACKAGE__->i18n('i18n_key_missing')) unless defined($key); | ||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||
| 395 | |||||||||||||||||||||||||||||||||
| 396 | # Positional (key, args) become a hash so the schema can name them | ||||||||||||||||||||||||||||||||
| 397 | 199 | my $params = validate_strict( | |||||||||||||||||||||||||||||||
| 398 | schema => \%I18N_SCHEMA, | ||||||||||||||||||||||||||||||||
| 399 | input => get_params([qw(key args)], $key, $args), | ||||||||||||||||||||||||||||||||
| 400 | ); | ||||||||||||||||||||||||||||||||
| 401 | 195 | ▶ | ($key, $args) = ($params->{key}, $params->{args} // {}); | ||||||||||||||||||||||||||||||
|
Condition100%2/2
$params->{"args"} // {}
MC/DC100%1/1
$params->{"args"} // {}
$params->{"args"}
Truth table100%2/2
A
A= $params->{"args"}
| |||||||||||||||||||||||||||||||||
| 402 | |||||||||||||||||||||||||||||||||
| 403 | # The invocant's overrides win over the English catalog | ||||||||||||||||||||||||||||||||
| 404 | 195 | ▶ | my $overrides = (blessed($self) && ref($self->{messages}) eq 'HASH') ? $self->{messages} : {}; | ||||||||||||||||||||||||||||||
|
Branch: 1 branch
Condition100%3/3
builtin::blessed($self) and ref $self->{"messages"} eq "HASH"
MC/DC100%2/2
builtin::blessed($self) and ref $self->{"messages"} eq "HASH"
builtin::blessed($self)
ref $self->{"messages"} eq "HASH"
Truth table100%3/3
A and B
A= builtin::blessed($self)B= ref $self->{"messages"} eq "HASH"
| |||||||||||||||||||||||||||||||||
| 405 | 195 | ▶ | my $template = exists($overrides->{$key}) ? $overrides->{$key} : $MESSAGES{$key}; | ||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||
| 406 | |||||||||||||||||||||||||||||||||
| 407 | 195 | my $text = _select_variant($template, $args); | |||||||||||||||||||||||||||||||
| 408 | |||||||||||||||||||||||||||||||||
| 409 | # An unknown key, or a template that resolved to nothing usable, is | ||||||||||||||||||||||||||||||||
| 410 | # reported by name so the event is never lost | ||||||||||||||||||||||||||||||||
| 411 | 195 | ▶ | return defined($text) ? _interpolate($text, $args) : $key; | ||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||
| 412 | } | ||||||||||||||||||||||||||||||||
| 413 | |||||||||||||||||||||||||||||||||
| 414 | =head2 catalog | ||||||||||||||||||||||||||||||||
| 415 | |||||||||||||||||||||||||||||||||
| 416 | my $messages = Mojolicious::Plugin::Buffer::I18N->catalog; | ||||||||||||||||||||||||||||||||
| 417 | |||||||||||||||||||||||||||||||||
| 418 | =head3 Purpose | ||||||||||||||||||||||||||||||||
| 419 | |||||||||||||||||||||||||||||||||
| 420 | Return a copy of the English catalog, for translators who want every key | ||||||||||||||||||||||||||||||||
| 421 | and for tests that check a key exists. | ||||||||||||||||||||||||||||||||
| 422 | |||||||||||||||||||||||||||||||||
| 423 | =head3 Arguments | ||||||||||||||||||||||||||||||||
| 424 | |||||||||||||||||||||||||||||||||
| 425 | None. | ||||||||||||||||||||||||||||||||
| 426 | |||||||||||||||||||||||||||||||||
| 427 | =head3 Returns | ||||||||||||||||||||||||||||||||
| 428 | |||||||||||||||||||||||||||||||||
| 429 | A hash reference mapping each message key to its template. It is a shallow | ||||||||||||||||||||||||||||||||
| 430 | copy: changing it does not change the catalog. | ||||||||||||||||||||||||||||||||
| 431 | |||||||||||||||||||||||||||||||||
| 432 | =head3 Side effects | ||||||||||||||||||||||||||||||||
| 433 | |||||||||||||||||||||||||||||||||
| 434 | None. | ||||||||||||||||||||||||||||||||
| 435 | |||||||||||||||||||||||||||||||||
| 436 | =head3 Example | ||||||||||||||||||||||||||||||||
| 437 | |||||||||||||||||||||||||||||||||
| 438 | my $catalog = Mojolicious::Plugin::Buffer::I18N->catalog; | ||||||||||||||||||||||||||||||||
| 439 | print "$_\n" for sort keys %$catalog; | ||||||||||||||||||||||||||||||||
| 440 | |||||||||||||||||||||||||||||||||
| 441 | =head3 API SPECIFICATION | ||||||||||||||||||||||||||||||||
| 442 | |||||||||||||||||||||||||||||||||
| 443 | =head4 Input | ||||||||||||||||||||||||||||||||
| 444 | |||||||||||||||||||||||||||||||||
| 445 | # No arguments besides the invocant | ||||||||||||||||||||||||||||||||
| 446 | {} | ||||||||||||||||||||||||||||||||
| 447 | |||||||||||||||||||||||||||||||||
| 448 | =head4 Output | ||||||||||||||||||||||||||||||||
| 449 | |||||||||||||||||||||||||||||||||
| 450 | # Return::Set schema | ||||||||||||||||||||||||||||||||
| 451 | { type => 'hashref', min => 1 } | ||||||||||||||||||||||||||||||||
| 452 | |||||||||||||||||||||||||||||||||
| 453 | =head3 MESSAGES | ||||||||||||||||||||||||||||||||
| 454 | |||||||||||||||||||||||||||||||||
| 455 | None. | ||||||||||||||||||||||||||||||||
| 456 | |||||||||||||||||||||||||||||||||
| 457 | =cut | ||||||||||||||||||||||||||||||||
| 458 | |||||||||||||||||||||||||||||||||
| 459 | 86 | ▶ | sub catalog { | ||||||||||||||||||||||||||||||
|
Subroutine
catalog: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||||||||||||||
| 460 | 86 | return {%MESSAGES}; | |||||||||||||||||||||||||||||||
| 461 | } | ||||||||||||||||||||||||||||||||
| 462 | |||||||||||||||||||||||||||||||||
| 463 | # Purpose: Resolve a template to a plain string by following code | ||||||||||||||||||||||||||||||||
| 464 | # references and gender/plural variant hashes. | ||||||||||||||||||||||||||||||||
| 465 | # Entry criteria: $template is a string, hashref, coderef or undef; $args | ||||||||||||||||||||||||||||||||
| 466 | # is a hashref. | ||||||||||||||||||||||||||||||||
| 467 | # Exit status: The selected string, or undef when nothing usable was | ||||||||||||||||||||||||||||||||
| 468 | # found (unknown key, missing variant, dying coderef, or | ||||||||||||||||||||||||||||||||
| 469 | # nesting deeper than $MAX_VARIANT_DEPTH). | ||||||||||||||||||||||||||||||||
| 470 | # Side effects: Calls translator-supplied code references. | ||||||||||||||||||||||||||||||||
| 471 | 195 | ▶ | sub _select_variant :Private { | ||||||||||||||||||||||||||||||
|
Subroutine
_select_variant: called CC=6 SCAR=17.9
| |||||||||||||||||||||||||||||||||
| 472 | 195 | my ($template, $args) = @_; | |||||||||||||||||||||||||||||||
| 473 | |||||||||||||||||||||||||||||||||
| 474 | 195 | my $depth = 0; | |||||||||||||||||||||||||||||||
| 475 | 195 | ▶ | while (ref($template) && ($depth++ < $MAX_VARIANT_DEPTH)) { | ||||||||||||||||||||||||||||||
|
Branch: 1 branch
Condition100%3/3
ref $template and $depth++ < $MAX_VARIANT_DEPTH
MC/DC100%2/2
ref $template and $depth++ < $MAX_VARIANT_DEPTH
ref $template
$depth++ < $MAX_VARIANT_DEPTH
Truth table100%3/3
A and B
A= ref $templateB= $depth++ < $MAX_VARIANT_DEPTH
| |||||||||||||||||||||||||||||||||
| 476 | 52 | ▶ | if (ref($template) eq 'CODE') { | ||||||||||||||||||||||||||||||
|
Branch: 2 branches
| |||||||||||||||||||||||||||||||||
| 477 | # A broken translation must not take the caller down with it | ||||||||||||||||||||||||||||||||
| 478 | 10 | $template = eval { $template->($args) }; | |||||||||||||||||||||||||||||||
| 479 | } elsif (ref($template) eq 'HASH') { | ||||||||||||||||||||||||||||||||
| 480 | 40 | $template = $template->{_variant_key($template, $args)}; | |||||||||||||||||||||||||||||||
| 481 | } else { | ||||||||||||||||||||||||||||||||
| 482 | 2 | $template = undef; | |||||||||||||||||||||||||||||||
| 483 | } | ||||||||||||||||||||||||||||||||
| 484 | } | ||||||||||||||||||||||||||||||||
| 485 | |||||||||||||||||||||||||||||||||
| 486 | 195 | ▶ | return ref($template) ? undef : $template; | ||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||
| 487 | 39 | ▶ | } | ||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||
| 488 | |||||||||||||||||||||||||||||||||
| 489 | # Purpose: Choose which variant of a hash applies to these arguments. | ||||||||||||||||||||||||||||||||
| 490 | # Entry criteria: $variants is a hashref; $args is a hashref. | ||||||||||||||||||||||||||||||||
| 491 | # Exit status: A key of $variants, or 'other' as the fallback. | ||||||||||||||||||||||||||||||||
| 492 | # Side effects: None. | ||||||||||||||||||||||||||||||||
| 493 | 40 | ▶ | sub _variant_key :Private { | ||||||||||||||||||||||||||||||
|
Subroutine
_variant_key: called CC=9 SCAR=22.0
| |||||||||||||||||||||||||||||||||
| 494 | 40 | my ($variants, $args) = @_; | |||||||||||||||||||||||||||||||
| 495 | |||||||||||||||||||||||||||||||||
| 496 | 40 | my ($gender, $count) = @{$args}{qw(gender count)}; | |||||||||||||||||||||||||||||||
| 497 | 40 | my $key = 'other'; | |||||||||||||||||||||||||||||||
| 498 | |||||||||||||||||||||||||||||||||
| 499 | # Gender is checked first so a gendered message can hold plural variants | ||||||||||||||||||||||||||||||||
| 500 | 40 | ▶ | if (defined($gender) && exists($variants->{$gender})) { | ||||||||||||||||||||||||||||||
|
Branch: 2 branches
Condition100%3/3
defined $gender and exists $variants->{$gender}
MC/DC100%2/2
defined $gender and exists $variants->{$gender}
defined $gender
exists $variants->{$gender}
Truth table100%3/3
A and B
A= defined $genderB= exists $variants->{$gender}
| |||||||||||||||||||||||||||||||||
| 501 | 4 | $key = $gender; | |||||||||||||||||||||||||||||||
| 502 | ▶ | } elsif (defined($count) && looks_like_number($count)) { | |||||||||||||||||||||||||||||||
|
Condition100%3/3
defined $count and &looks_like_number($count)
MC/DC100%2/2
defined $count and &looks_like_number($count)
defined $count
&looks_like_number($count)
Truth table100%3/3
A and B
A= defined $countB= &looks_like_number($count)
| |||||||||||||||||||||||||||||||||
| 503 | 24 | ▶ | $key = 'zero' if ($count == 0) && exists($variants->{zero}); | ||||||||||||||||||||||||||||||
|
Branch: 1 branch
Condition100%3/3
$count == 0 and exists $variants->{"zero"}
MC/DC100%2/2
$count == 0 and exists $variants->{"zero"}
$count == 0
exists $variants->{"zero"}
Truth table100%3/3
A and B
A= $count == 0B= exists $variants->{"zero"}
| |||||||||||||||||||||||||||||||||
| 504 | 24 | ▶ | $key = 'one' if ($count == 1) && exists($variants->{one}); | ||||||||||||||||||||||||||||||
|
Branch: 1 branch
Condition100%3/3
$count == 1 and exists $variants->{"one"}
MC/DC100%2/2
$count == 1 and exists $variants->{"one"}
$count == 1
exists $variants->{"one"}
Truth table100%3/3
A and B
A= $count == 1B= exists $variants->{"one"}
| |||||||||||||||||||||||||||||||||
| 505 | } | ||||||||||||||||||||||||||||||||
| 506 | |||||||||||||||||||||||||||||||||
| 507 | 40 | return $key; | |||||||||||||||||||||||||||||||
| 508 | 39 | ▶ | } | ||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||
| 509 | |||||||||||||||||||||||||||||||||
| 510 | # Purpose: Fill %{name} and %{name:FORMAT} placeholders. | ||||||||||||||||||||||||||||||||
| 511 | # Entry criteria: $text is a defined string; $args is a hashref. | ||||||||||||||||||||||||||||||||
| 512 | # Exit status: The text with every supplied placeholder replaced. | ||||||||||||||||||||||||||||||||
| 513 | # Placeholders with no argument are left as they are. | ||||||||||||||||||||||||||||||||
| 514 | # Side effects: None; numeric-format warnings are silenced because a | ||||||||||||||||||||||||||||||||
| 515 | # translated message must never produce a warning itself. | ||||||||||||||||||||||||||||||||
| 516 | 185 | ▶ | sub _interpolate :Private { | ||||||||||||||||||||||||||||||
|
Subroutine
_interpolate: called CC=4 SCAR=13.9
| |||||||||||||||||||||||||||||||||
| 517 | 185 | my ($text, $args) = @_; | |||||||||||||||||||||||||||||||
| 518 | |||||||||||||||||||||||||||||||||
| 519 | 39 | ▶ | no warnings qw(numeric redundant missing); | ||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||
| 520 | 185 | $text =~ s{$PLACEHOLDER}{ | |||||||||||||||||||||||||||||||
| 521 | !exists($args->{$2}) ? $1 | ||||||||||||||||||||||||||||||||
| 522 | : !defined($args->{$2}) ? '' | ||||||||||||||||||||||||||||||||
| 523 | : defined($3) ? sprintf($3, $args->{$2}) | ||||||||||||||||||||||||||||||||
| 524 | 108 | ▶ | : $args->{$2} | ||||||||||||||||||||||||||||||
|
Branch: 3 branches
| |||||||||||||||||||||||||||||||||
| 525 | }ge; | ||||||||||||||||||||||||||||||||
| 526 | |||||||||||||||||||||||||||||||||
| 527 | 185 | return $text; | |||||||||||||||||||||||||||||||
| 528 | 39 | ▶ | } | ||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||
| 529 | |||||||||||||||||||||||||||||||||
| 530 | 39 | 1; | |||||||||||||||||||||||||||||||
| 531 | |||||||||||||||||||||||||||||||||
| 532 | =head1 COMMON PITFALLS | ||||||||||||||||||||||||||||||||
| 533 | |||||||||||||||||||||||||||||||||
| 534 | =over 4 | ||||||||||||||||||||||||||||||||
| 535 | |||||||||||||||||||||||||||||||||
| 536 | =item * B<An override replaces the whole message; it is not merged.> If the | ||||||||||||||||||||||||||||||||
| 537 | built-in message has C<one> and C<other> forms and you override it with a | ||||||||||||||||||||||||||||||||
| 538 | plain string, both forms are replaced by that one string. If you override | ||||||||||||||||||||||||||||||||
| 539 | it with C<< {other =E<gt> '...'} >> only, there is no C<one> form any more. | ||||||||||||||||||||||||||||||||
| 540 | Give every form you need. | ||||||||||||||||||||||||||||||||
| 541 | |||||||||||||||||||||||||||||||||
| 542 | =item * B<undef is not "use the default".> C<< messages =E<gt> | ||||||||||||||||||||||||||||||||
| 543 | {retry_later =E<gt> undef} >> makes the message the bare key, so visitors | ||||||||||||||||||||||||||||||||
| 544 | see the word C<retry_later>. To go back to the built-in text, I<delete> the | ||||||||||||||||||||||||||||||||
| 545 | key from the hash instead. | ||||||||||||||||||||||||||||||||
| 546 | |||||||||||||||||||||||||||||||||
| 547 | =item * B<A missing argument stays visible.> C<i18n('unknown_option')> | ||||||||||||||||||||||||||||||||
| 548 | without C<option> returns C<... unknown option '%{option}'>. This is on | ||||||||||||||||||||||||||||||||
| 549 | purpose, so that a mistake shows. An argument that I<exists> but is undef | ||||||||||||||||||||||||||||||||
| 550 | becomes the empty string. | ||||||||||||||||||||||||||||||||
| 551 | |||||||||||||||||||||||||||||||||
| 552 | =item * B<There is no escape for a literal C<%{name}>.> If a translated | ||||||||||||||||||||||||||||||||
| 553 | text must show C<%{word}> itself, do not pass an argument called C<word>. | ||||||||||||||||||||||||||||||||
| 554 | A plain C<%> that is not followed by C<{> is always left alone. | ||||||||||||||||||||||||||||||||
| 555 | |||||||||||||||||||||||||||||||||
| 556 | =item * B<Gender is checked before count.> With both C<gender> and C<count> | ||||||||||||||||||||||||||||||||
| 557 | given, a matching gender variant wins. Put the plural forms I<inside> the | ||||||||||||||||||||||||||||||||
| 558 | gender variant if you need both. | ||||||||||||||||||||||||||||||||
| 559 | |||||||||||||||||||||||||||||||||
| 560 | =item * B<A code reference that dies is silent.> The key is returned | ||||||||||||||||||||||||||||||||
| 561 | instead, and no warning is given. Test your code references. | ||||||||||||||||||||||||||||||||
| 562 | |||||||||||||||||||||||||||||||||
| 563 | =item * B<A format is one conversion only.> C<%{n:%d}> works. C<%{n:%d%%}> | ||||||||||||||||||||||||||||||||
| 564 | does not match the placeholder rule and is left in the text unchanged. The | ||||||||||||||||||||||||||||||||
| 565 | conversions C<%n> and vector flags are refused on purpose. | ||||||||||||||||||||||||||||||||
| 566 | |||||||||||||||||||||||||||||||||
| 567 | =item * B<Messages are chosen once per application.> The plugin does not | ||||||||||||||||||||||||||||||||
| 568 | read C<Accept-Language>. See L</LIMITATIONS>. | ||||||||||||||||||||||||||||||||
| 569 | |||||||||||||||||||||||||||||||||
| 570 | =back | ||||||||||||||||||||||||||||||||
| 571 | |||||||||||||||||||||||||||||||||
| 572 | =head1 ENCODING | ||||||||||||||||||||||||||||||||
| 573 | |||||||||||||||||||||||||||||||||
| 574 | =over 4 | ||||||||||||||||||||||||||||||||
| 575 | |||||||||||||||||||||||||||||||||
| 576 | =item Templates and arguments | ||||||||||||||||||||||||||||||||
| 577 | |||||||||||||||||||||||||||||||||
| 578 | Both may hold any Perl characters: accented letters, any other script, and | ||||||||||||||||||||||||||||||||
| 579 | emoji. Use C<use utf8;> in a source file that contains such characters | ||||||||||||||||||||||||||||||||
| 580 | literally, or write them as escapes like C<"\x{1F600}">. A C<%{name:%5s}> | ||||||||||||||||||||||||||||||||
| 581 | width counts characters, not bytes. | ||||||||||||||||||||||||||||||||
| 582 | |||||||||||||||||||||||||||||||||
| 583 | =item The returned text | ||||||||||||||||||||||||||||||||
| 584 | |||||||||||||||||||||||||||||||||
| 585 | The result is a Perl character string. It is not encoded. When you print | ||||||||||||||||||||||||||||||||
| 586 | it, use a handle with an encoding layer, such as | ||||||||||||||||||||||||||||||||
| 587 | C<binmode(STDOUT, ':encoding(UTF-8)')>, or Perl warns "Wide character". | ||||||||||||||||||||||||||||||||
| 588 | L<Mojo::Log> encodes every line to UTF-8 by itself, so log lines are safe. | ||||||||||||||||||||||||||||||||
| 589 | The plugin encodes the C<retry_later> text to UTF-8 and sends it with | ||||||||||||||||||||||||||||||||
| 590 | C<charset=UTF-8>. | ||||||||||||||||||||||||||||||||
| 591 | |||||||||||||||||||||||||||||||||
| 592 | =item Keys | ||||||||||||||||||||||||||||||||
| 593 | |||||||||||||||||||||||||||||||||
| 594 | Keys are matched exactly. All built-in keys are ASCII; use ASCII for your | ||||||||||||||||||||||||||||||||
| 595 | own keys too. | ||||||||||||||||||||||||||||||||
| 596 | |||||||||||||||||||||||||||||||||
| 597 | =item Messages from Params::Validate::Strict | ||||||||||||||||||||||||||||||||
| 598 | |||||||||||||||||||||||||||||||||
| 599 | These are English and are passed through unchanged. | ||||||||||||||||||||||||||||||||
| 600 | |||||||||||||||||||||||||||||||||
| 601 | =back | ||||||||||||||||||||||||||||||||
| 602 | |||||||||||||||||||||||||||||||||
| 603 | =head1 LIMITATIONS | ||||||||||||||||||||||||||||||||
| 604 | |||||||||||||||||||||||||||||||||
| 605 | =over 4 | ||||||||||||||||||||||||||||||||
| 606 | |||||||||||||||||||||||||||||||||
| 607 | =item * Messages are chosen once per application, not per request. The | ||||||||||||||||||||||||||||||||
| 608 | plugin does not negotiate C<Accept-Language>, so the C<retry_later> text sent | ||||||||||||||||||||||||||||||||
| 609 | with a C<503> is the same for every client. A per-language reply needs a | ||||||||||||||||||||||||||||||||
| 610 | custom C<messages> code reference that reads a value the application set. | ||||||||||||||||||||||||||||||||
| 611 | |||||||||||||||||||||||||||||||||
| 612 | =item * Plural selection only knows C<zero>, C<one> and C<other>. Languages | ||||||||||||||||||||||||||||||||
| 613 | with more categories (Polish, Arabic, Welsh, ...) need a code reference | ||||||||||||||||||||||||||||||||
| 614 | template. | ||||||||||||||||||||||||||||||||
| 615 | |||||||||||||||||||||||||||||||||
| 616 | =item * Messages produced by L<Params::Validate::Strict> for programming | ||||||||||||||||||||||||||||||||
| 617 | errors (a missing or malformed message key) are passed through in English. | ||||||||||||||||||||||||||||||||
| 618 | |||||||||||||||||||||||||||||||||
| 619 | =back | ||||||||||||||||||||||||||||||||
| 620 | |||||||||||||||||||||||||||||||||
| 621 | =head1 SEE ALSO | ||||||||||||||||||||||||||||||||
| 622 | |||||||||||||||||||||||||||||||||
| 623 | L<Mojolicious::Plugin::Buffer> | ||||||||||||||||||||||||||||||||
| 624 | |||||||||||||||||||||||||||||||||
| 625 | =head1 AUTHOR | ||||||||||||||||||||||||||||||||
| 626 | |||||||||||||||||||||||||||||||||
| 627 | Nigel Horne, C<< <njh at bandsman.co.uk> >> | ||||||||||||||||||||||||||||||||
| 628 | |||||||||||||||||||||||||||||||||
| 629 | =head1 FORMAL SPECIFICATION | ||||||||||||||||||||||||||||||||
| 630 | |||||||||||||||||||||||||||||||||
| 631 | This section describes the catalog in the Z notation, for readers who want | ||||||||||||||||||||||||||||||||
| 632 | an exact model. You do not need it to use the module. C<defaults> is the | ||||||||||||||||||||||||||||||||
| 633 | built-in English catalog and C<overrides> is the C<messages> hash of the | ||||||||||||||||||||||||||||||||
| 634 | object the method is called on. | ||||||||||||||||||||||||||||||||
| 635 | |||||||||||||||||||||||||||||||||
| 636 | [KEY, TEXT, NAME, VALUE] | ||||||||||||||||||||||||||||||||
| 637 | |||||||||||||||||||||||||||||||||
| 638 | Args == NAME ⇸ VALUE | ||||||||||||||||||||||||||||||||
| 639 | Template ::= str⟨⟨TEXT⟩⟩ | variants⟨⟨NAME ⇸ Template⟩⟩ | code⟨⟨Args → Template⟩⟩ | ||||||||||||||||||||||||||||||||
| 640 | |||||||||||||||||||||||||||||||||
| 641 | ┌─ Catalog ─────────────────────────────────── | ||||||||||||||||||||||||||||||||
| 642 | │ defaults : KEY ⇸ Template | ||||||||||||||||||||||||||||||||
| 643 | │ overrides : KEY ⇸ Template | ||||||||||||||||||||||||||||||||
| 644 | └───────────────────────────────────────────── | ||||||||||||||||||||||||||||||||
| 645 | |||||||||||||||||||||||||||||||||
| 646 | select : Template × Args × ℕ ⇸ TEXT ∪ {⊥} | ||||||||||||||||||||||||||||||||
| 647 | |||||||||||||||||||||||||||||||||
| 648 | select(t, a, d) = ⊥ if d ≥ 4 ∧ t ∉ ran str | ||||||||||||||||||||||||||||||||
| 649 | select(str s, a, d) = s | ||||||||||||||||||||||||||||||||
| 650 | select(code f, a, d) = select(f(a), a, d + 1) if f(a) does not die | ||||||||||||||||||||||||||||||||
| 651 | = ⊥ otherwise | ||||||||||||||||||||||||||||||||
| 652 | select(variants v, a, d) = select(v(pick(v, a)), a, d + 1) | ||||||||||||||||||||||||||||||||
| 653 | if pick(v, a) ∈ dom v | ||||||||||||||||||||||||||||||||
| 654 | = ⊥ otherwise | ||||||||||||||||||||||||||||||||
| 655 | |||||||||||||||||||||||||||||||||
| 656 | pick(v, a) = gender a if gender a ∈ dom v | ||||||||||||||||||||||||||||||||
| 657 | = zero if count a = 0 ∧ zero ∈ dom v | ||||||||||||||||||||||||||||||||
| 658 | = one if count a = 1 ∧ one ∈ dom v | ||||||||||||||||||||||||||||||||
| 659 | = other otherwise | ||||||||||||||||||||||||||||||||
| 660 | |||||||||||||||||||||||||||||||||
| 661 | =head2 i18n | ||||||||||||||||||||||||||||||||
| 662 | |||||||||||||||||||||||||||||||||
| 663 | C<interpolate> replaces each placeholder C<%{n}> or C<%{n:F}> for which | ||||||||||||||||||||||||||||||||
| 664 | C<n ∈ dom args?>, and leaves every other placeholder unchanged. | ||||||||||||||||||||||||||||||||
| 665 | |||||||||||||||||||||||||||||||||
| 666 | ┌─ I18n ────────────────────────────────────── | ||||||||||||||||||||||||||||||||
| 667 | │ ΞCatalog | ||||||||||||||||||||||||||||||||
| 668 | │ key? : KEY ; args? : Args ; text! : TEXT | ||||||||||||||||||||||||||||||||
| 669 | ├───────────────────────────────────────────── | ||||||||||||||||||||||||||||||||
| 670 | │ key? ≠ ∅ | ||||||||||||||||||||||||||||||||
| 671 | │ let m == defaults ⊕ overrides • | ||||||||||||||||||||||||||||||||
| 672 | │ key? ∈ dom m ∧ select(m key?, args?, 0) ≠ ⊥ | ||||||||||||||||||||||||||||||||
| 673 | │ ⇒ text! = interpolate(select(m key?, args?, 0), args?) | ||||||||||||||||||||||||||||||||
| 674 | │ key? ∉ dom m ∨ select(m key?, args?, 0) = ⊥ | ||||||||||||||||||||||||||||||||
| 675 | │ ⇒ text! = key? | ||||||||||||||||||||||||||||||||
| 676 | └───────────────────────────────────────────── | ||||||||||||||||||||||||||||||||
| 677 | -- key? undefined or empty, or args? not a hash: croak | ||||||||||||||||||||||||||||||||
| 678 | |||||||||||||||||||||||||||||||||
| 679 | =head2 catalog | ||||||||||||||||||||||||||||||||
| 680 | |||||||||||||||||||||||||||||||||
| 681 | ┌─ Catalog_Copy ────────────────────────────── | ||||||||||||||||||||||||||||||||
| 682 | │ ΞCatalog | ||||||||||||||||||||||||||||||||
| 683 | │ result! : KEY ⇸ Template | ||||||||||||||||||||||||||||||||
| 684 | ├───────────────────────────────────────────── | ||||||||||||||||||||||||||||||||
| 685 | │ result! = defaults | ||||||||||||||||||||||||||||||||
| 686 | └───────────────────────────────────────────── | ||||||||||||||||||||||||||||||||
| 687 | |||||||||||||||||||||||||||||||||
| 688 | =head1 STATE DIAGRAM | ||||||||||||||||||||||||||||||||
| 689 | |||||||||||||||||||||||||||||||||
| 690 | This module keeps no state between calls: the catalog never changes while | ||||||||||||||||||||||||||||||||
| 691 | the program runs, and the overrides belong to the calling object. So | ||||||||||||||||||||||||||||||||
| 692 | instead of states, this diagram shows the path one call to L</i18n> takes. | ||||||||||||||||||||||||||||||||
| 693 | Each box is a step; the text on an arrow is the condition for taking it. | ||||||||||||||||||||||||||||||||
| 694 | |||||||||||||||||||||||||||||||||
| 695 | i18n(key, args) | ||||||||||||||||||||||||||||||||
| 696 | | | ||||||||||||||||||||||||||||||||
| 697 | v | ||||||||||||||||||||||||||||||||
| 698 | +--------------------+ key undef or empty, | ||||||||||||||||||||||||||||||||
| 699 | | 1. CHECK ARGUMENTS | or args not a hash | ||||||||||||||||||||||||||||||||
| 700 | | | ----------------------> croak | ||||||||||||||||||||||||||||||||
| 701 | +--------------------+ | ||||||||||||||||||||||||||||||||
| 702 | | ok | ||||||||||||||||||||||||||||||||
| 703 | v | ||||||||||||||||||||||||||||||||
| 704 | +--------------------+ key in neither hash | ||||||||||||||||||||||||||||||||
| 705 | | 2. LOOK UP THE KEY | ----------------------> return the key | ||||||||||||||||||||||||||||||||
| 706 | | overrides first, | (e.g. "retry_later") | ||||||||||||||||||||||||||||||||
| 707 | | then the defaults | | ||||||||||||||||||||||||||||||||
| 708 | +--------------------+ | ||||||||||||||||||||||||||||||||
| 709 | | found | ||||||||||||||||||||||||||||||||
| 710 | v | ||||||||||||||||||||||||||||||||
| 711 | +--------------------+ undef template, dying | ||||||||||||||||||||||||||||||||
| 712 | | 3. RESOLVE | code ref, no variant | ||||||||||||||||||||||||||||||||
| 713 | | code ref: call it | fits, or 4 levels deep | ||||||||||||||||||||||||||||||||
| 714 | | hash: pick variant | ----------------------> return the key | ||||||||||||||||||||||||||||||||
| 715 | | repeat until plain | | ||||||||||||||||||||||||||||||||
| 716 | +--------------------+ | ||||||||||||||||||||||||||||||||
| 717 | | plain string | ||||||||||||||||||||||||||||||||
| 718 | v | ||||||||||||||||||||||||||||||||
| 719 | +--------------------+ | ||||||||||||||||||||||||||||||||
| 720 | | 4. FILL IN | This step cannot fail. A placeholder | ||||||||||||||||||||||||||||||||
| 721 | | %{name} and | with no argument is left as it is. | ||||||||||||||||||||||||||||||||
| 722 | | %{name:FORMAT} | | ||||||||||||||||||||||||||||||||
| 723 | +--------------------+ | ||||||||||||||||||||||||||||||||
| 724 | | | ||||||||||||||||||||||||||||||||
| 725 | v | ||||||||||||||||||||||||||||||||
| 726 | return the text | ||||||||||||||||||||||||||||||||
| 727 | |||||||||||||||||||||||||||||||||
| 728 | =head1 LICENSE AND COPYRIGHT | ||||||||||||||||||||||||||||||||
| 729 | |||||||||||||||||||||||||||||||||
| 730 | Copyright 2026 Nigel Horne. | ||||||||||||||||||||||||||||||||
| 731 | |||||||||||||||||||||||||||||||||
| 732 | This program is free software; you can redistribute it and/or modify it | ||||||||||||||||||||||||||||||||
| 733 | under the terms of the GNU General Public License as published by the Free | ||||||||||||||||||||||||||||||||
| 734 | Software Foundation; either version 2 of the License, or (at your option) | ||||||||||||||||||||||||||||||||
| 735 | any later version. | ||||||||||||||||||||||||||||||||
| 736 | |||||||||||||||||||||||||||||||||
| 737 | =cut | ||||||||||||||||||||||||||||||||