Locale::KeyedText 1.73.0 review

Locale::KeyedText is a Perl module that refers to user messages in programs by keys. It also describes the same-number versions of

License: Perl Artistic License File size: 34K Developer: Darren R. Duncan

0

Locale::KeyedText is a Perl module that refers to user messages in programs by keys.

It also describes the same-number versions of Locale::KeyedText::Message ("Message") and Locale::KeyedText::Translator ("Translator").

Note that the "Locale::KeyedText" package serves only as the name-sake representative for this whole file, which can be referenced as a unit by documentation or 'use' statements or Perl archive indexes. Aside from 'use' statements, you should never refer directly to "Locale::KeyedText" in your code; instead refer to other above-named packages in this file.

SYNOPSIS

use Locale::KeyedText;

main();

sub main {
# Create a translator.
my $translator = Locale::KeyedText::Translator->new({
'set_names' => ['MyLib::Lang::', 'MyApp::Lang::'],
# set package prefixes for localized app components
'member_names' => ['Eng', 'Fr', 'De', 'Esp'],
# set list of available languages in order of preference
});

# This will print 'Enter 2 Numbers' in the first of the four
# languages that has a matching template available.
print $translator->translate_message(
Locale::KeyedText::Message->new({
'msg_key' => 'MYAPP_PROMPT' }) );

# Read two numbers from the user.
my ($first, $second) = ;

# Print a statement giving the operands and their sum.
MyLib->add_two( $first, $second, $translator );
}

package MyLib; # module

sub add_two {
my (undef, $first, $second, $translator) = @_;
my $sum = $first + $second;

# This will print ' plus equals ' in
# the first possible language. For example, if the user
# inputs '3' and '4', it the output will be '3 plus 4 equals 7'.
print $translator->translate_message(
Locale::KeyedText::Message->new({ 'msg_key' => 'MYLIB_RESULT',
'msg_vars' => { 'FIRST' => $first, 'SECOND' => $second,
'RESULT' => $sum } }) );
}

Many times during a program's operation, the program (or a package it uses) will need to display a message to the user, or generate a message to be shown to the user. Sometimes this is an error message of some kind, but it could also be a prompt or response message for interactive systems.

If the program or any of its components are intended for widespread use then it needs to account for a variance of needs between its different users, such as their preferred language of communication, or their privileges regarding access to information details, or their technical skills. For example, a native French or Chinese speaker often prefers to communicate in those languages. Or, when viewing an error message, the application's developer should see more details than joe public would.

Alternately, sometimes a program will raise a condition or error that, while resembling a message that would be shown to a user, is in fact meant to be interpreted by the machine itself and not any human user. In some situations, a shared program component may raise such a condition, and one application may handle it internally, while another one displays it to the user instead.

Locale::KeyedText provides a simple but effective mechanism for applications and packages that empowers single binaries to support N locales or user types simultaneously, and that allows any end users to add support for new languages easily and without a recompile (such as by simply copying files), often even while the program is executing.

Locale::KeyedText gives your application the maximum amount of control as to what the user sees; it never outputs anything by itself to the user, but rather returns its results for calling code to output as it sees fit. It also does not make direct use of environment variables, which can aid in portability.

Practically speaking, Locale::KeyedText doesn't actually do a lot internally; it exists mainly to document a certain localization methodology in an easily accessable manner, such that would not be possible if its functionality was subsumed into a larger package that would otherwise use it. Hereafter, if any other package or application says that it uses Locale::KeyedText, that is a terse way of saying that it subscribes to the localization methodology that is described here, and hence provides these benefits to developers and users alike.

For some practical examples of Locale::KeyedText in use, see the /examples directory of this distribution. Or, see my dependent CPAN packages whose problem domain is databases and/or SQL.

Requirements:
Perl