NAME
Astro::App::Satpass2::Locale - Handle locale-dependant data.
SYNOPSIS
use Astro::App::Satpass2::Locale qw{ __localize };
# The best localization
say scalar __localize( 'foo', 'bar', 'default text' );
# All localizations, in decreasing order of goodness
for ( __localize( 'foo', 'bar', 'default text' ) ) {
say;
}DESCRIPTION
This Perl module implements the locale system for Astro::App::Satpass2.
The locale data can be thought of as a two-level hash, with the first level corresponding to the section of a Microsoft-style configuration file and the second level to the items in the section.
The locale data are stored in .pm files, which return the required hash when they are loaded. These are named after the locale, in the form lc_CC.pm or lc.pm, where the lc is the language code (lower case) and the CC is a country code (upper case).
The files are considered in the following order:
- The user's lc_CC.pm
- The global lc_CC.pm
- The user's lc.pm
- The global lc.pm
- The user's C.pm
- The global C.pm.
The global files are installed as Perl modules, named Astro::App::Satpass2::Locale::whatever, and are loaded via require(). The user's files are stored in the locale/ directory of the user's configuration, and are loaded via do().
SUBROUTINES
This class supports the following exportable public subroutines:
__localize
# The best localization
say scalar __localize( 'foo', 'bar', 'default text' );
# All localizations, in decreasing order of goodness
for ( __localize( 'foo', 'bar', 'default text' ) ) {
say;
}This subroutine is the interface used to localize values. The last (rightmost) argument is the default, to be returned if no localization can be found. All leading (leftmost) arguments that are defined and are not references are keys (or indices) used to traverse the locale data structure. Any remaining arguments are either hash references (which represent last-chance locale definitions) or ignored.
If called in scalar context, the best available localization is returned. If 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( foo => 'bar', {
C => {
foo => {
bar => 'Gronk!',
},
},
fr => {
foo => {
bar => 'Gronkez!',
},
},
}, 'Greeble' );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.
SEE ALSO
Astro::App::Satpass2::FormatValue
SUPPORT
Support is by the author. Please file bug reports at http://rt.cpan.org, or in electronic mail to the author.
AUTHOR
Thomas R. Wyant, III wyant at cpan dot org
COPYRIGHT AND LICENSE
Copyright (C) 2014 by Thomas R. Wyant, III
This program is free software; you can redistribute it and/or modify it under the same terms as Perl 5.10.0. For more details, see the full text of the licenses in the directory LICENSES.
This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.