/ 
OpenInteract-1.99_06
River stage zero No dependents
/ 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:

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.

SEE ALSO

Locale::Maketext

Locale::Maketext::Lexicon

gettext: http://www.gnu.org/software/gettext/

OpenInteract2::I18N

OpenInteract2::Manual::I18N

OpenInteract2::Setup::ReadLocalizedMessages

COPYRIGHT

Copyright (c) 2003-2005 Chris Winters. All rights reserved.

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>