OpenInteract2 Documentation: OpenInteract2::I18N::Initializer

NAME

OpenInteract2::I18N::Initializer - Read in localization messages and generate maketext classes

SYNOPSIS

 my $init = OpenInteract2::I18N::Initializer->new;
 $init->add_message_files( @some_message_files );
 my $gen_classes = $init->run;
 print "I generated the following classes: ", join( @{ $gen_classes } ), "\n";

DESCRIPTION

This class is generally only used by the OI2 startup procedure, which scans all packages for message files and adds them to this initializer, then runs it. The purpose of this class is to generate subclasses for use with Locale::Maketext. Those classes are fairly simple and generally only contain a package variable %Lexicon which L::M uses to work its magic.

The message files may be in one of three formats:

.msg - Custom key/value pair format with interpolated variables indicated by [_1] , [_2], etc. as supported by Locale::Maketext. End-of-line continuations ('\') are also supported -- see OpenInteract2::Manual::I18N for formatting details.
.po - Plaintext format used by gettext. This format is documented elsewhere (see SEE ALSO) and parsed by Locale::Maketext::Lexicon.
.mo - Compiled gettext files. This format is documented elsewhere (see SEE ALSO) and parsed by Locale::Maketext::Lexicon.

Message files can also be mixed and matched, even within a package. So if you've got one translator who likes to use gettext tools you can include them alongside people who are fine with the OI2 message format.

CLASS METHODS

new()

Return a new object. Any parameters are ignored.

is_valid_message_file( $filename )

If $filename is a valid message file this returns the language from the filename, otherwise it returns false.

The language must be the last distinct set of characters before the file extension. (Distinct in the '\b' regex sense.) The following are ok:

  myapp-en.msg
  myotherapp-en_MX.po
  messages_en-HK.mo

The following are not:

 english-messages.msg
 messages-en-part2.po
 messagesen.mo

Currently we assume the base language identifier is two characters (e.g., 'en', 'jp', 'ru') and the extension (e.g., 'US', 'CA', 'MX') can by any number of characters. This may be wildly naive and may change.

OBJECT METHODS

add_message_files( @fully_qualified_files )

Adds all files in @fully_qualified_files to its internal list of files to process. It does not process these files until run().

If any file in @fully_qualified_files does not have a valid language we throw an exception.

locate_global_message_files()

Finds all message files (that is, files ending in '.msg') in the global message directory as reported by the OpenInteract2::Context and adds them to the initializer. Normally only called by OpenInteract2::Setup::ReadLocalizedMessages.

Returns: arrayref of fully-qualified files added

run()

Reads messages from all files added via add_message_files() and generates language-specific subclasses for all messages found. Once the subclasses are created the system does not know from where the messages come since all messages are flattened into a per-language data structure. So the following:

 file: msg-en.msg
 keys:
   foo.title
   foo.intro
   foo.label.main

 file: other_msg-en.mo
 keys:
   baz.title
   baz.intro
   baz.conclusion

 file: another_msg-en.po
   bar.title
   bar.intro
   bar.error.notfound

would be flattened into:

 lang: en
   foo.title
   foo.intro
   foo.label.main
   baz.title
   baz.intro
   baz.conclusion
   bar.title
   bar.intro
   bar.error.notfound

The method throws an exception on any of the following conditions:

Cannot open or read from one of the message files.
If you have any gettext files (mo/po extension) and do not have Locale::Maketext::Lexicon.
Cannot process the template used to generate the class.
Cannot evaluate the generated class.

Note that a duplicate key (that is, a key defined in multiple message files) will not generate an exception. Instead it will generate a logging message with an 'warn' level.

See more about the format used for the custom message files in OpenInteract2::Manual::I18N.

Returns: arrayref of the names of the classes generated.

COPYRIGHT

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHORS

Chris Winters <chris@cwinters.com>

Generated from the OpenInteract 1.99_06 source.