__localize

 # The best localization
 say scalar __localize(
     text    => [ 'foo', 'bar' ],
     default => 'default text',
 );
 
 # All localizations, in decreasing order of goodness
 for ( __localize(
     text    => [ 'foo', 'bar' ],
     default => 'default text',
 ) ) {
     say;
 }

This subroutine is the interface used to localize values.

The arguments are name/value pairs, with the following names being the only ones supported.

text

This argument is required, and passes the text to be localized. This can be either a scalar, or a reference to an array of keys (or indices) used to traverse the locale data structure.

default

This argument specifies the default value to be returned if no localization is available. If it is not specified, "undef" is returned if no localization is available.

locale

This argument specifies either a hash reference that is consulted for locale information if all other available locales provide no localization, or a reference to an array of such hashes. The default is "[]".

argument

This argument specifies the value of the second argument passed to a code reference which is being used for localization. See Astro::App::Satpass2::Locale::C for an example of how this can be used.

All other keys are unsupported in the sense that the author makes no representation what will happen if you specify them, and makes no commitment that whatever you observe to happen will not change without notice.

If this subroutine is called in scalar context, the best available localization is returned. If it is called in list context, all available localizations will be returned, with the best first and the worst (which will be the default) last.

To extend the above example, assuming neither the system-wide or locale-specific locale information defines the keys "{fu}{bar}",

 say scalar __localize(
     text    => [ foo => 'bar' ],
     default => 'Greeble',
     locale  => {
         C => {
             foo => {
                 bar => 'Gronk!',
             },
         },
         fr => {
             foo => {
                 bar => 'Gronkez!',
             },
         },
     },
 );

will print 'Gronkez!' in a French locale, and 'Gronk!' in any other locale (since the 'C' locale is always consulted). If 'Greeble' is printed, it indicates that the locale system is buggy.

__message

 say __message( 'Fee fi foe foo!' ); # Fee fi foe foo
 say __message( 'A', 'B', 'C' );     # A B C
 say __message( 'Hello [% arg.0 %]!', 'sailor' );
                                     # Hello sailor!

This subroutine is a wrapper for "__localize()" designed to make message localization easier.

The first argument is localized by looking it up under the "{'+message'}" key in the localization data. If no localization is found, the first argument is its own localization. In other words, if the first argument is $message, its localization is "__localize( '+message', $message, $message )".

If the localization contains "Template-Toolkit" interpolations (specifically, '[%') it and the arguments are fed to that system, with the arguments being available to the template as variable "arg". The result is returned.

If the localization of the first argument does not contain any "Template-Toolkit" interpolations, it is simply joined to the arguments, with single space characters in between, and the result of the join is returned.

__preferred

 say __preferred()

This subroutine returns the user's preferred locale in scalar mode, or all acceptable locales in descending order of preference in list mode.