File Coverage

=head1 NAME

App::Access2CSV::I18N - Message catalog and translated error messages for App::Access2CSV

=head1 VERSION

Version 0.001.0

=head1 SYNOPSIS

        use App::Access2CSV::I18N;

        # 1. Get a message as text
        my $text = App::Access2CSV::I18N->i18n('missing_database');
        # "Missing database filename"

        # 2. Fill in values (the message has %s and %d placeholders)
        print App::Access2CSV::I18N->i18n('progress', { params => [1, 3, 'Customers'] }), "\n";
        # "[1/3] Customers"

        # 3. Let the count choose between singular and plural
        print App::Access2CSV::I18N->i18n('summary', { params => [$n, 0], count => $n }), "\n";
        # $n == 1: "Processed 1 table, 0 failed"
        # $n == 4: "Processed 4 tables, 0 failed"

        # 4. Add a translation.  Keys you do not translate stay in English.
        $App::Access2CSV::I18N::MESSAGES{de}{missing_database} =
                'Name der Datenbankdatei fehlt';
        $ENV{LANG} = 'de_DE.UTF-8';

        # 5. Use it as a base class, to get i18n() and the error helpers
        package My::Tool;
        use parent 'App::Access2CSV::I18N';

        sub check {
                my ($self, $file) = @_;
                $self->_croak_i18n('database_not_file', { params => [$file] }) unless -f $file;
                return $self;
        }

=head1 DESCRIPTION

Every message that App::Access2CSV prints, logs or throws is looked up
here, by a short name called a I<key> (for example C<output_exists>).
This keeps all the text in one place, so the program can be translated.

The text for each key is a I<template>.  A template is usually a
C<sprintf> format: C<%s> is replaced by a text value and C<%d> by a whole
number, in order.  A template can also have different forms:

=over 4

=item * B<Plural forms>, chosen by a count: C<one> for one item,
C<other> for any other number.  Some languages use more forms
(C<zero>, C<two>, C<few>, C<many>).

=item * B<Context forms>, chosen by a word you give, such as C<male> or
C<female>.  A context form can itself contain plural forms.

=back

The templates live in the hash C<%App::Access2CSV::I18N::MESSAGES>:

        %MESSAGES = (
                en => {
                        missing_database => 'Missing database filename',
                        summary => {
                                one   => 'Processed %d table, %d failed',
                                other => 'Processed %d tables, %d failed',
                        },
                        ...
                },
        );

Only English (C<en>) is included.

=head2 Which language is used

=over 4

=item 1. The C<language> field of the object, if you call C<i18n> on an
object that has one (for example
C<< App::Access2CSV::Exporter->new(language => 'en') >>).

=item 2. Otherwise the first of these environment variables that is set
and is not C<C> or C<POSIX>: C<LANGUAGE>, C<LC_ALL>, C<LC_MESSAGES>,
C<LANG>.  Only the language part is used: C<de_DE.UTF-8> means C<de>.
Upper or lower case does not matter.  C<LANGUAGE> can hold a list such as
C<fr:de>; only the first entry is used.  An empty value, or an empty
first entry (C<:de>), counts as "not set", so the next variable is tried.

=item 3. If there is no catalog for that language, English is used.

=back

Inside a language, a key that has no translation falls back to the
English text, one key at a time.

=head2 Helpers for subclasses

Subclasses get two protected methods.  They can be called only from this
class and its subclasses:

=over 4

=item * C<< $self->_croak_i18n($key, \%args) >> - throws an exception
(with L<Carp/croak>) with the translated message.  It never returns.

=item * C<< $self->_carp_i18n($key, \%args) >> - warns (with
L<Carp/carp>) with the translated message, with control characters
escaped.  It returns C<$self>.

=item * C<< $self->_printable($text) >> - returns C<$text> with control
characters (C0 except tab, DEL, C1, and text-direction controls) shown
as escapes such as C<\x1B>, so that text from an untrusted database is
safe to print or log.

=back

=head1 ENCODING

=over 4

=item * B<The English catalog> is plain ASCII.

=item * B<Values in params> are copied into the message as they are.
Byte strings (such as UTF-8 file names from the command line) stay byte
strings, so non-ASCII text and emoji come out unchanged when printed.

=item * B<Translations with non-ASCII text> (for example German C<ue>
written as one letter, or Japanese) must be Perl character strings: write
them in a source file with C<use utf8;>.  Do not mix them with UTF-8
I<byte> strings in C<params>, or the bytes will be encoded a second time.
When you print such messages, give the output handle an encoding, for
example C<binmode(STDERR, ':encoding(UTF-8)')>, or Perl warns
"Wide character in print".

=back

=head1 COMMON PITFALLS

=over 4

=item * B<Percent signs.>  A template with no C<params> is returned
exactly as written, so C<100%> is safe.  But when you give C<params>, the
template goes through C<sprintf>, so a literal percent sign must be
written C<%%>.

=item * B<Number of values.>  Give exactly as many C<params> as the
template has placeholders.  Too few gives a Perl "Missing argument"
warning; C<undef> in C<params> gives a "Use of uninitialized value"
warning.

=item * B<No count means plural.>  If you do not give C<count>, the
C<other> form is used, even if the number in C<params> is 1.

=item * B<Replacing a key replaces all of its forms.>
C<%MESSAGES> is not merged in depth.  If you set
C<< $MESSAGES{en}{summary} = 'Done' >>, the C<one> and C<other> forms of
C<summary> are gone.  If a translation gives a plural hash, it should have
an C<other> form: when no form fits, the English text for that key is
used instead.

=item * B<Unknown context.>  A C<context> that the template does not have
is ignored; the plural forms (or the plain text) are used instead.

=item * B<Unknown keys are fatal.>  A key that is not in the English
catalog is a programming error: C<i18n> calls C<confess>, which stops the
program and prints a stack trace.

=item * B<undef arguments.>  C<undef> for C<args>, or for a field inside
the hashref form, is treated as "not given".  C<undef> as the key is
reported as a missing key.

=item * B<Load with use, not require.>  The protection of C<_croak_i18n>
and C<_carp_i18n> is set up at compile time.  After a run-time
C<require> it is missing, and Perl prints "Too late to run CHECK block".

=back

=head1 METHODS

=head2 i18n

=head3 Purpose

Turn a message key into text in the user's language.  Choose the right
context and plural form, then fill in the values.

=head3 Arguments

You can call C<i18n> on the class or on an object.  There are two ways
to give the arguments:

        $obj->i18n($key, \%args);
        $obj->i18n({ key => $key, args => \%args });

=over 4

=item C<key> (string, required)

The message key, for example C<'output_exists'>.

=item C<args> (hash reference, optional)

=over 4

=item C<params> - an array reference of the values for the placeholders,
in order.

=item C<count> - a whole number, 0 or more, that chooses the plural form.

=item C<context> - a word that chooses a context form, for example
C<'female'>.

=back

=back

=head3 Returns

The message as a string, without a newline at the end.

=head3 Side Effects

None.  It only reads C<%MESSAGES> and C<%ENV>.  Your C<$@>, C<$!> and
C<$_> are left as they were.

=head3 Usage

        my $text = $self->i18n('summary', { params => [3, 0], count => 3 });

=head3 EXAMPLE

        # "Output file already exists: out/Orders.csv (use --overwrite to replace it)"
        my $msg = App::Access2CSV::I18N->i18n('output_exists', { params => ['out/Orders.csv'] });

        # A message with context and plural forms
        $App::Access2CSV::I18N::MESSAGES{en}{greeting} = {
                female => { one => 'She sent %d letter', other => 'She sent %d letters' },
                other  => 'They sent %d letters',
        };
        print App::Access2CSV::I18N->i18n('greeting',
                { params => [2], count => 2, context => 'female' }), "\n";
        # "She sent 2 letters"

=head3 API SPECIFICATION

=head4 Input

        {
                key => {
                        type     => 'string',
                        min      => 1,
                        optional => 0,
                },
                args => {
                        type     => 'hashref',
                        optional => 1,
                        schema   => {
                                params  => { type => 'arrayref', optional => 1 },
                                count   => { type => 'integer', optional => 1, min => 0 },
                                context => { type => 'string', optional => 1 },
                        },
                },
        }

Valid and invalid values (tested in F<t/domain.t>):

        key      valid:   a key in the English catalog
                 invalid: "" (1 character is the minimum), undef, a
                          reference, an unknown key (fatal: "Unknown message
                          key"), a known key with extra characters
        count    valid:   whole numbers from 0 up (0 is the minimum; 2**53
                          works); undef means "no count"
                 invalid: -1 and below, fractions (1.5), words
                 edges:   English and German: 1 is singular, 0 and 2 plural.
                          French: 0 and 1 singular.  Japanese, Korean,
                          Chinese: always the "other" form
        params   any number of values, including none; each value is
                 copied into the text exactly, whether it is a Perl
                 character string or UTF-8 bytes (non-ASCII letters,
                 emoji, joined emoji, combining marks, right-to-left text)
        context  any string; one the template does not have (including "")
                 is ignored; a reference is invalid
        language (from the environment) the first 2 or 3 letters, in any
                 case; 1 letter, non-ASCII letters, C and POSIX all mean
                 "no language"

=head4 Output

        {
                type => 'string',
        }

=head3 MESSAGES

        +-----------------------------+-------------------------------+---------------------------------+
        | Message                     | Meaning                       | What to do                      |
        +-----------------------------+-------------------------------+---------------------------------+
        | Unknown message key: KEY    | KEY is not in the English     | Programming error: add KEY to   |
        |  (fatal, with stack trace)  | catalog                       | $MESSAGES{en}                   |
        | Required parameter 'key' is | No key was given              | Give a key                      |
        |  missing (fatal)            |                               |                                 |
        | Unknown parameter 'X'       | args has a field that is not  | Use only params, count and      |
        |  (fatal)                    | params, count or context      | context                         |
        | Parameter 'count' (X) must  | count is negative or not a    | Give a whole number, 0 or more  |
        |  be ... (fatal)             | whole number                  |                                 |
        | Parameter 'params' must be  | params is not an array        | Give an array reference         |
        |  an arrayref (fatal)        | reference                     |                                 |
        +-----------------------------+-------------------------------+---------------------------------+

=head3 PSEUDOCODE

        check key and args
        lang := the object's language, or the language from the environment,
                or English if there is no catalog for it
        for try in (lang, then en if lang is not en):   # at most 2 tries, no recursion
                entry := catalog[try][key], or else catalog[en][key]
                if entry has forms and one matches args.context:
                        entry := that form
                if entry still has forms:
                        entry := the form for plural_category(try, count),
                                 or else the "other" form
                stop if entry is now a plain string
        if no try gave a plain string: confess (the catalog is broken)
        if there are params: return sprintf(entry, params)
        else: return entry unchanged

=cut