NAME

Locale::MakePhrase::BackingStore::Directory - Retrieve translations from files located in a specified directory.

DESCRTIPION

This backing store is capable of loading language rules, from files located in the specified directory. All files ending with the extension .mpt will try to be loaded.

Files need to be named according to language/dialect. For example:

  en.mpt
  en_au.mpt
  cn.mpt

Thus, the filename is used to defined the language component of the language rule object.

The files must be formatted as shown in the en.mpt-example and cn.mpt-example files (which can be located in the same directories that these modules are are installed in). The important points to note are that the file is broken into groups containing:

key

expression

priority

translation

Where expression & priority are optional. However, if you specify the priority and/or expression, make sure the translation key is the last entry in the group - this is necessary, as we dont know when the the block is finished.

API

The following methods are implemented:

$self new([...])

We support loading text/translations (from the translation files) which may be encoded using any character encoding. Since we need to know something about the files we are trying to load, we expect this object to be constructed with the following options:

directory

The full path to the directory containing the translation files. eg:

  /usr/local/myapp/translations

Default: none; you must specify a directory

extension

You can specify a different file extension to use, rather than using .mpt.

Default: use .mpt as the extension

encoding

We can load translations from any enocding supported by the Encode module. Upon load, this module will convert the translations from the specified encoding, into the interal encoding of UTF-8.

Default: load UTF-8 text translations.

reload

This module will dynamically reload its known translations, if the files get updated. You can set this option to avoid reloading the file if it changes.

Default: reload language files if changed

\@rule_objs get_rules($context,$key,\@languages)

Retrieve the translations (that have been previously loaded), using the selected languages. This implementation will reload the appropiate language file if it changes (unless it has been told not to).

NOTES

file extension

If you find that the filename extension .mpt is unsuitable, you can change it by setting the variable:

$Locale::MakePhrase::BackingStore::Directory::language_file_extension

to the extension that you prefer, or simply set it in your constructor.

line-ending

We automatically handle the Unix/MS-DOS line-ending difference.

multi-line

Strings can be spanned over multiple lines, if the end of the line is backslash-escaped.