| 1 | package Zonemaster::Engine::Translator; | ||
| 2 | |||
| 3 | use v5.16.0; | ||
| 4 | use warnings; | ||
| 5 | |||
| 6 | use version; our $VERSION = version->declare("v1.0.8"); | ||
| 7 | |||
| 8 | use Carp qw[confess croak]; | ||
| 9 | use Locale::Messages qw[textdomain]; | ||
| 10 | use Locale::TextDomain qw[Zonemaster-Engine]; | ||
| 11 | use POSIX qw[setlocale LC_MESSAGES]; | ||
| 12 | use Readonly; | ||
| 13 | |||
| 14 | use Zonemaster::Engine::Test; | ||
| 15 | |||
| 16 | ### | ||
| 17 | ### Tag descriptions | ||
| 18 | ### | ||
| 19 | |||
| 20 | Readonly my %TAG_DESCRIPTIONS => ( | ||
| 21 | CANNOT_CONTINUE => sub { | ||
| 22 | __x # SYSTEM:CANNOT_CONTINUE | ||
| 23 | "Not enough data about {domain} was found to be able to run tests.", @_; | ||
| 24 | }, | ||
| 25 | DEPENDENCY_VERSION => sub { | ||
| 26 | __x # SYSTEM:DEPENDENCY_VERSION | ||
| 27 | "Using prerequisite module {name} version {version}.", @_; | ||
| 28 | }, | ||
| 29 | GLOBAL_VERSION => sub { | ||
| 30 | __x # SYSTEM:GLOBAL_VERSION | ||
| 31 | "Using version {version} of the Zonemaster engine.", @_; | ||
| 32 | }, | ||
| 33 | LOGGER_CALLBACK_ERROR => sub { | ||
| 34 | __x # SYSTEM:LOGGER_CALLBACK_ERROR | ||
| 35 | "Logger callback died with error: {exception}", @_; | ||
| 36 | }, | ||
| 37 | LOOKUP_ERROR => sub { | ||
| 38 | __x # SYSTEM:LOOKUP_ERROR | ||
| 39 | "DNS query to {ns} for {domain}/{type}/{class} failed with error: {message}", @_; | ||
| 40 | }, | ||
| 41 | MODULE_ERROR => sub { | ||
| 42 | __x # SYSTEM:MODULE_ERROR | ||
| 43 | "Fatal error in {module}: {msg}", @_; | ||
| 44 | }, | ||
| 45 | MODULE_VERSION => sub { | ||
| 46 | __x # SYSTEM:MODULE_VERSION | ||
| 47 | "Using module {module} version {version}.", @_; | ||
| 48 | }, | ||
| 49 | MODULE_END => sub { | ||
| 50 | __x # SYSTEM:MODULE_END | ||
| 51 | "Module {module} finished running.", @_; | ||
| 52 | }, | ||
| 53 | NO_NETWORK => sub { | ||
| 54 | __x # SYSTEM:NO_NETWORK | ||
| 55 | "Both IPv4 and IPv6 are disabled."; | ||
| 56 | }, | ||
| 57 | UNKNOWN_METHOD => sub { | ||
| 58 | __x # SYSTEM:UNKNOWN_METHOD | ||
| 59 | "Request to run unknown method {testcase} in module {module}.", @_; | ||
| 60 | }, | ||
| 61 | UNKNOWN_MODULE => sub { | ||
| 62 | __x # SYSTEM:UNKNOWN_MODULE | ||
| 63 | "Request to run {testcase} in unknown module {module}. Known modules: {module_list}.", @_; | ||
| 64 | }, | ||
| 65 | SKIP_IPV4_DISABLED => sub { | ||
| 66 | __x # SYSTEM:SKIP_IPV4_DISABLED | ||
| 67 | "IPv4 is disabled, not sending \"{rrtype}\" query to {ns}.", @_; | ||
| 68 | }, | ||
| 69 | SKIP_IPV6_DISABLED => sub { | ||
| 70 | __x # SYSTEM:SKIP_IPV6_DISABLED | ||
| 71 | "IPv6 is disabled, not sending \"{rrtype}\" query to {ns}.", @_; | ||
| 72 | }, | ||
| 73 | FAKE_DELEGATION_TO_SELF => sub { | ||
| 74 | __x # SYSTEM:FAKE_DELEGATION_TO_SELF | ||
| 75 | "Name server {ns} not adding fake delegation for domain {domain} to itself.", @_; | ||
| 76 | }, | ||
| 77 | FAKE_DELEGATION_IN_ZONE_NO_IP => sub { | ||
| 78 | __x # SYSTEM:FAKE_DELEGATION_IN_ZONE_NO_IP | ||
| 79 | "The fake delegation of domain {domain} includes an in-zone name server {nsname} " | ||
| 80 | . "without mandatory glue (without IP address).", | ||
| 81 | @_; | ||
| 82 | }, | ||
| 83 | FAKE_DELEGATION_NO_IP => sub { | ||
| 84 | __x # SYSTEM:FAKE_DELEGATION_NO_IP | ||
| 85 | "The fake delegation of domain {domain} includes a name server {nsname} " | ||
| 86 | . "that cannot be resolved to any IP address.", | ||
| 87 | @_; | ||
| 88 | }, | ||
| 89 | PACKET_BIG => sub { | ||
| 90 | __x # SYSTEM:PACKET_BIG | ||
| 91 | "Big packet size ({size}) (try with \"{command}\").", @_; | ||
| 92 | }, | ||
| 93 | ); | ||
| 94 | |||
| 95 | ### | ||
| 96 | ### Construction | ||
| 97 | ### | ||
| 98 | |||
| 99 | my $instance; | ||
| 100 | |||
| 101 | sub new { | ||
| 102 | my ( $class, %attrs ) = @_; | ||
| 103 | |||
| 104 | $class->initialize( %attrs ); | ||
| 105 | |||
| 106 | return $class->instance; | ||
| 107 | } | ||
| 108 | |||
| 109 | sub instance { | ||
| 110 | my ( $class ) = @_; | ||
| 111 | |||
| 112 | if ( !defined $instance ) { | ||
| 113 | $class->initialize(); | ||
| 114 | } | ||
| 115 | |||
| 116 | return $instance; | ||
| 117 | } | ||
| 118 | |||
| 119 | sub initialize { | ||
| 120 | my ( $class, %attrs ) = @_; | ||
| 121 | |||
| 122 | if ( defined $instance ) { | ||
| 123 | confess "already initialized"; | ||
| 124 | } | ||
| 125 | |||
| 126 | my $locale; | ||
| 127 | if ( exists $attrs{locale} ) { | ||
| 128 | $locale = delete $attrs{locale}; | ||
| 129 | |||
| 130 | if ( !defined $locale || ref $locale ne '' ) { | ||
| 131 | confess "argument 'locale' must not be a defined scalar"; | ||
| 132 | } | ||
| 133 | } | ||
| 134 | |||
| 135 | my $obj = { | ||
| 136 | _locale => $locale // _init_locale(), | ||
| 137 | _all_tag_descriptions => $class->_build_all_tag_descriptions(), | ||
| 138 | _last_language => _build_last_language(), | ||
| 139 | }; | ||
| 140 | |||
| 141 | $instance = bless $obj, $class; | ||
| 142 | |||
| 143 | return; | ||
| 144 | } | ||
| 145 | |||
| 146 | ### | ||
| 147 | ### Builder Methods | ||
| 148 | ### | ||
| 149 | |||
| 150 | # Get the program's underlying LC_MESSAGES and make sure it can be effectively | ||
| 151 | # updated down the line. | ||
| 152 | # | ||
| 153 | # If the underlying LC_MESSAGES is invalid, it attempts to second guess Perl's | ||
| 154 | # fallback locale. | ||
| 155 | # | ||
| 156 | # Side effects: | ||
| 157 | # * Updates the program's underlying LC_MESSAGES to the returned value. | ||
| 158 | # * Unsets LC_ALL. | ||
| 159 | sub _init_locale { | ||
| 160 | my $locale = setlocale( LC_MESSAGES, "" ); | ||
| 161 | |||
| 162 | delete $ENV{LC_ALL}; | ||
| 163 | |||
| 164 | if ( !defined $locale ) { | ||
| 165 | my $language = $ENV{LANGUAGE} // ""; | ||
| 166 | for my $value ( split /:/, $language ) { | ||
| 167 | if ( $value ne "" && $value !~ /[.]/ ) { | ||
| 168 | $value .= ".UTF-8"; | ||
| 169 | } | ||
| 170 | $locale = setlocale( LC_MESSAGES, $value ); | ||
| 171 | if ( defined $locale ) { | ||
| 172 | last; | ||
| 173 | } | ||
| 174 | } | ||
| 175 | $locale //= "C"; | ||
| 176 | } | ||
| 177 | |||
| 178 | return $locale; | ||
| 179 | } | ||
| 180 | |||
| 181 | sub _load_data { | ||
| 182 | my $self = shift; | ||
| 183 | |||
| 184 | my $old_locale = $self->locale; | ||
| 185 | |||
| 186 | $self->locale( 'C' ); | ||
| 187 | |||
| 188 | my %data; | ||
| 189 | for my $mod ( keys %{ $self->all_tag_descriptions } ) { | ||
| 190 | for my $tag ( keys %{ $self->all_tag_descriptions->{$mod} } ) { | ||
| 191 | $data{$mod}{$tag} = $self->_translate_tag( $mod, $tag, {} ); | ||
| 192 | } | ||
| 193 | } | ||
| 194 | |||
| 195 | $self->locale( $old_locale ); | ||
| 196 | |||
| 197 | return \%data; | ||
| 198 | } | ||
| 199 | |||
| 200 | sub _build_all_tag_descriptions { | ||
| 201 | my ( $class ) = @_; | ||
| 202 | |||
| 203 | my %all_tag_descriptions; | ||
| 204 | |||
| 205 | $all_tag_descriptions{System} = \%TAG_DESCRIPTIONS; | ||
| 206 | foreach my $mod ( Zonemaster::Engine::Test->modules ) { | ||
| 207 | my $module = 'Zonemaster::Engine::Test::' . $mod; | ||
| 208 | $all_tag_descriptions{ $mod } = $module->tag_descriptions; | ||
| 209 | } | ||
| 210 | |||
| 211 | return \%all_tag_descriptions; | ||
| 212 | } | ||
| 213 | |||
| 214 | sub _build_last_language { | ||
| 215 | return $ENV{LANGUAGE} // ''; | ||
| 216 | } | ||
| 217 | |||
| 218 | ### | ||
| 219 | ### Instance methods | ||
| 220 | ### | ||
| 221 | |||
| 222 | sub data { | ||
| 223 | my ( $self ) = @_; | ||
| 224 | |||
| 225 | if ( !exists $self->{_data} ) { | ||
| 226 | $self->{_data} = $self->_load_data; | ||
| 227 | } | ||
| 228 | |||
| 229 | return $self->{_data}; | ||
| 230 | } | ||
| 231 | |||
| 232 | sub all_tag_descriptions { | ||
| 233 | my ( $self ) = @_; | ||
| 234 | |||
| 235 | return $self->{_all_tag_descriptions}; | ||
| 236 | } | ||
| 237 | |||
| 238 | sub locale { | ||
| 239 | my ( $self, @args ) = @_; | ||
| 240 | |||
| 241 | if ( @args ) { | ||
| 242 | my $new_locale = shift @args; | ||
| 243 | |||
| 244 | # On some systems gettext takes its locale from setlocale(). | ||
| 245 | if ( !defined setlocale( LC_MESSAGES, $new_locale ) ) { | ||
| 246 | return; | ||
| 247 | } | ||
| 248 | |||
| 249 | $self->_last_language( $ENV{LANGUAGE} // '' ); | ||
| 250 | |||
| 251 | # On some systems gettext takes its locale from %ENV. | ||
| 252 | $ENV{LC_MESSAGES} = $new_locale; | ||
| 253 | |||
| 254 | # On some systems gettext refuses to switch over to another locale unless | ||
| 255 | # the textdomain is reset. | ||
| 256 | textdomain( 'Zonemaster-Engine' ); | ||
| 257 | |||
| 258 | if ( !defined $new_locale || ref $new_locale ne '' ) { | ||
| 259 | croak "locale must be a defined scalar"; | ||
| 260 | } | ||
| 261 | |||
| 262 | $self->{_locale} = $new_locale; | ||
| 263 | } ## end if ( @args ) | ||
| 264 | |||
| 265 | return $self->{_locale}; | ||
| 266 | }; | ||
| 267 | |||
| 268 | sub to_string { | ||
| 269 | my ( $self, $entry ) = @_; | ||
| 270 | |||
| 271 | return sprintf( "%7.2f %-9s %s", $entry->timestamp, $entry->level, $self->translate_tag( $entry ) ); | ||
| 272 | } | ||
| 273 | |||
| 274 | sub translate_tag { | ||
| 275 | my ( $self, $entry ) = @_; | ||
| 276 | |||
| 277 | return $self->_translate_tag( $entry->module, $entry->tag, $entry->printable_args ) // $entry->string; | ||
| 278 | } | ||
| 279 | |||
| 280 | |||
| 281 | sub test_case_description { | ||
| 282 | my ( $self, $test_name ) = @_; | ||
| 283 | |||
| 284 | my $module = $test_name; | ||
| 285 | $module =~ s/\d+$//; | ||
| 286 | |||
| 287 | return $self->_translate_tag( $module, uc $test_name, {} ) // $test_name; | ||
| 288 | } | ||
| 289 | |||
| 290 | sub _last_language { | ||
| 291 | my $self = shift; | ||
| 292 | |||
| 293 | if ( @_ ) { | ||
| 294 | my $last_language = shift; | ||
| 295 | if ( !defined $last_language || ref $last_language ne '' ) { | ||
| 296 | croak "_last_language must be a defined scalar"; | ||
| 297 | } | ||
| 298 | $self->{_last_language} = $last_language; | ||
| 299 | } | ||
| 300 | |||
| 301 | return $self->{_last_language}; | ||
| 302 | } | ||
| 303 | |||
| 304 | sub _translate_tag { | ||
| 305 | my ( $self, $module, $tag, $args ) = @_; | ||
| 306 | |||
| 307 | if ( $ENV{LANGUAGE} // '' ne $self->_last_language ) { | ||
| 308 | $self->locale( $self->locale ); | ||
| 309 | } | ||
| 310 | |||
| 311 | my $code = $self->all_tag_descriptions->{$module}{$tag}; | ||
| 312 | |||
| 313 | if ( $code ) { | ||
| 314 | return $code->( %{$args} ); | ||
| 315 | } | ||
| 316 | else { | ||
| 317 | return undef; | ||
| 318 | } | ||
| 319 | } | ||
| 320 | |||
| 321 | 1; | ||
| 322 | |||
| 323 | =head1 NAME | ||
| 324 | |||
| 325 | Zonemaster::Engine::Translator - translation support for Zonemaster | ||
| 326 | |||
| 327 | =head1 SYNOPSIS | ||
| 328 | |||
| 329 | Zonemaster::Engine::Translator->initialize( locale => 'sv_SE.UTF-8' ); | ||
| 330 | |||
| 331 | my $trans = Zonemaster::Engine::Translator->instance; | ||
| 332 | say $trans->to_string($entry); | ||
| 333 | |||
| 334 | This is a singleton class. | ||
| 335 | |||
| 336 | The instance of this class requires exclusive control over C<$ENV{LC_MESSAGES}> | ||
| 337 | and the program's underlying LC_MESSAGES. | ||
| 338 | At times it resets gettext's textdomain. | ||
| 339 | On construction it unsets C<$ENV{LC_ALL}> and from then on it must remain unset. | ||
| 340 | |||
| 341 | On systems that support C<$ENV{LANGUAGE}>, this variable overrides the locale() | ||
| 342 | attribute unless the locale() attribute is set to C<"C">. | ||
| 343 | |||
| 344 | =head1 ATTRIBUTES | ||
| 345 | |||
| 346 | =over | ||
| 347 | |||
| 348 | =item locale | ||
| 349 | |||
| 350 | The locale used for localized messages. | ||
| 351 | |||
| 352 | say $translator->locale(); | ||
| 353 | if ( !$translator->locale( 'sv_SE.UTF-8' ) ) { | ||
| 354 | say "failed to update locale"; | ||
| 355 | } | ||
| 356 | |||
| 357 | The value of this attribute is mirrored in C<$ENV{LC_MESSAGES}>. | ||
| 358 | |||
| 359 | When writing to this attribute, a request is made to update the program's | ||
| 360 | underlying LC_MESSAGES. | ||
| 361 | If this request fails, the attribute value remains unchanged and an empty list | ||
| 362 | is returned. | ||
| 363 | |||
| 364 | As a side effect when successfully updating this attribute gettext's textdomain | ||
| 365 | is reset. | ||
| 366 | |||
| 367 | =item data | ||
| 368 | |||
| 369 | A reference to a hash with translation data. This is unlikely to be useful to | ||
| 370 | end-users. | ||
| 371 | |||
| 372 | =item all_tag_descriptions | ||
| 373 | |||
| 374 | =back | ||
| 375 | |||
| 376 | =head1 METHODS | ||
| 377 | |||
| 378 | =over | ||
| 379 | |||
| 380 | =item initialize(%args) | ||
| 381 | |||
| 382 | Provide initial values for the single instance of this class. | ||
| 383 | |||
| 384 | Zonemaster::Engine::Translator->initialize( locale => 'sv_SE.UTF-8' ); | ||
| 385 | |||
| 386 | This method must be called at most once and before the first call to instance(). | ||
| 387 | |||
| 388 | =item instance() | ||
| 389 | |||
| 390 | Returns the single instance of this class. | ||
| 391 | |||
| 392 | my $translator = Zonemaster::Engine::Translator->instance; | ||
| 393 | |||
| 394 | If initialize() has not been called prior to the first call to instance(), it | ||
| 395 | is the same as if initialize() had been called without arguments. | ||
| 396 | |||
| 397 | =item new(%args) | ||
| 398 | |||
| 399 | Use of this method is deprecated. | ||
| 400 | |||
| 401 | =over | ||
| 402 | |||
| 403 | =item locale | ||
| 404 | |||
| 405 | If no initial value is provided to the constructor, one is determined by calling | ||
| 406 | setlocale( LC_MESSAGES, "" ). | ||
| 407 | |||
| 408 | =back | ||
| 409 | |||
| 410 | =item to_string($entry) | ||
| 411 | |||
| 412 | Takes a L<Zonemaster::Engine::Logger::Entry> object as its argument and returns a translated string with the timestamp, level, message and arguments in the | ||
| 413 | entry. | ||
| 414 | |||
| 415 | =item translate_tag($entry) | ||
| 416 | |||
| 417 | Takes a L<Zonemaster::Engine::Logger::Entry> object as its argument and returns a translation of its tag and arguments. | ||
| 418 | |||
| 419 | =item test_case_description($testcase) | ||
| 420 | |||
| 421 | Takes a string (test case ID) and returns the translated test case description. | ||
| 422 | |||
| 423 | =item BUILD | ||
| 424 | |||
| 425 | Internal method that's only mentioned here to placate L<Pod::Coverage>. | ||
| 426 | |||
| 427 | =back | ||
| 428 | |||
| 429 | =cut |