File Coverage

=head1 NAME

CGI::Lingua - Create a multilingual web page

=head1 VERSION

Version 0.87

=cut

=head1 SYNOPSIS

Your website tells CGI::Lingua which languages it can show.
CGI::Lingua looks at what the visitor's web browser asks for,
and tells your website which of its languages to use.

=head2 Pick a language for the page

    use CGI::Lingua;

    # The site has pages in English and French
    my $l = CGI::Lingua->new(supported => ['en', 'fr']);

    my $language = $l->language();    # 'English', 'French' or 'Unknown'
    if($language eq 'English') {
        print "<p>Hello</p>\n";
    } elsif($language eq 'French') {
        print "<p>Bonjour</p>\n";
    } else {
        # The visitor wants a language that the site does not have
        my $wanted = $l->requested_language();    # e.g. 'German'
        print "<p>Sorry, this page is not available in $wanted.</p>\n";
    }

=head2 Use the short code to choose a file or template

    my $l = CGI::Lingua->new(supported => ['en-gb', 'en-us', 'fr']);

    my $code    = $l->language_code_alpha2() // 'en';    # 'en' or 'fr'
    my $variant = $l->sublanguage_code_alpha2();         # 'gb', 'us' or undef
    my $template = defined($variant) ? "$code-$variant.tmpl" : "$code.tmpl";

=head2 Show different content for different countries

    my $l = CGI::Lingua->new(supported => ['en']);

    my $country = $l->country() // '';    # e.g. 'us', 'ca', 'gb'
    if($country eq 'us') {
        print "Call us on 1-800-555-0100\n";
    } elsif($country eq 'ca') {
        print "Call us on 1-888-555-0100\n";
    } else {
        print "Email us at help\@example.com\n";
    }

=head2 Make it faster with a cache

Finding the country of an IP address can be slow.
Give CGI::Lingua a L<CHI> cache so that the work is only done once
for each visitor.

    use CHI;
    use CGI::Lingua;

    my $cache = CHI->new(
        driver    => 'File',
        root_dir  => '/var/cache/myapp',
        namespace => 'CGI::Lingua',
    );
    my $l = CGI::Lingua->new(supported => ['en', 'fr'], cache => $cache);

=head2 Let the visitor choose with a "lang" parameter

If you pass a L<CGI::Info> object, a C<lang=fr> parameter in the URL
is used before the browser's settings.

    use CGI::Info;
    use CGI::Lingua;

    my $info = CGI::Info->new();
    my $l = CGI::Lingua->new(supported => ['en', 'fr', 'de'], info => $info);
    print $l->language();    # 'German' for https://example.com/page?lang=de

=head2 Set the HTML "lang" and "dir" attributes

    my $l = CGI::Lingua->new(supported => ['en', 'ar', 'he']);
    my $code = $l->language_code_alpha2() // 'en';
    printf qq{<html lang="%s" dir="%s">\n}, $code, $l->text_direction();
    # <html lang="ar" dir="rtl"> for an Arabic-speaking visitor

=head2 Choose the right plural form

    my $l = CGI::Lingua->new(supported => ['en', 'ru']);
    my %messages = (
        one  => '%d file',
        few  => '%d files (few)',
        many => '%d files (many)',
        other => '%d files',
    );
    my $n = 3;
    printf $messages{$l->plural_category($n)} . "\n", $n;

=head2 Load a translation file

    # Looks for /var/www/i18n/en-gb.json, then /var/www/i18n/en.json
    my $l = CGI::Lingua->new(supported => ['en-gb', 'en', 'fr']);
    if(my $file = $l->translation_file('/var/www/i18n')) {
        # read and use $file
    }

=head2 Guess the visitor's time zone and locale

    my $l = CGI::Lingua->new(supported => ['en']);
    my $tz = $l->time_zone() // 'UTC';     # e.g. 'America/New_York'
    if(my $locale = $l->locale()) {         # a Locale::Object::Country
        print 'Currency: ', $locale->currency()->code(), "\n";
    }

=head2 Do not guess from the IP address

    # Only use what the browser asks for; never look up the IP address
    my $l = CGI::Lingua->new(supported => ['en', 'fr'], dont_use_ip => 1);

=head1 DESCRIPTION

This section explains, in simple steps, how CGI::Lingua finds the answer.

=head2 Finding the language

When you first call a language method (for example L</language>),
CGI::Lingua looks for the visitor's language in this order:

=over 4

=item 1. The C<lang> parameter of the L<CGI::Info> object, if you gave one
to L</new> with C<info>.

=item 2. The C<HTTP_ACCEPT_LANGUAGE> environment variable.
The web server sets this from the browser's C<Accept-Language> header,
for example C<fr-CA,fr;q=0.9,en;q=0.8>.
Languages with a higher C<q> value are tried first.
A language with C<q=0> means "not acceptable" (RFC 7231) and is never chosen.
Some browsers still send the old tag C<en-uk>; it is treated as C<en-gb>
(the code for the United Kingdom is C<gb>), with a warning.

=item 3. The C<LANG> environment variable.
This is used when you run the program on the command line,
for example C<LANG=fr_FR.UTF-8>.

=item 4. The visitor's country (see below).
CGI::Lingua uses the official language of that country.
This step is skipped when you give C<dont_use_ip> to L</new>.

=back

It then compares the answer with your C<supported> list.
If a visitor asks for C<en-us> and you only support C<en-gb>,
CGI::Lingua still chooses English, because the base language is the same.
If nothing matches, L</language> returns the string C<'Unknown'>.

=head2 Finding the country

L</country> tries these sources in order, and stops at the first answer:

=over 4

=item 1. C<GEOIP_COUNTRY_CODE> (set by Apache's mod_geoip).

=item 2. C<HTTP_CF_IPCOUNTRY> (set by Cloudflare).

=item 3. A local database: L<IP::Country>, then L<Geo::IP>, then L<Geo::IPfree>,
if they are installed.

=item 4. The geoplugin.net web service.

=item 5. A Whois look-up (L<Net::Whois::IP>, then L<Net::Whois::IANA>).

=back

Steps 3 to 5 use the visitor's IP address from C<REMOTE_ADDR>.
Private addresses (such as C<192.168.1.1>) and loopback addresses
(such as C<127.0.0.1>) have no country, so the answer is C<undef>.

=head2 Remembering answers

Each object remembers its answers, so a second call to the same method is fast.
If you give a C<cache> to L</new>, answers are also stored in the cache when the
object is destroyed. The next object created for the same IP address, the same
requested language and the same C<supported> list starts with those answers.

=head1 SUBROUTINES/METHODS

=head2 new

Creates a CGI::Lingua object.

You must tell it which languages your website supports, with C<supported>.
Each language is a short code, such as C<'en'> (English),
C<'fr'> (French) or C<'en-gb'> (British English).

You can give the arguments as a list, as a hash reference,
as a single array reference (the supported list), or as a single string
(one supported language):

    CGI::Lingua->new(supported => ['en', 'fr']);
    CGI::Lingua->new({ supported => ['en', 'fr'] });
    CGI::Lingua->new(['en', 'fr']);
    CGI::Lingua->new('en');

The arguments are:

=over 4

=item * C<supported> (required)

The languages your website supports: one short code (a string of 2 to 5
characters) or a reference to an array of language tags.
C<supported_languages> is another name for the same argument.

Each entry in the array must look like a language tag: two or three letters,
optionally followed by subtags, such as C<'en'>, C<'en-gb'>, C<'en_gb'>,
C<'es-419'> or C<'zh-Hant'>. Other entries (C<undef>, references, C<''>, or
words such as C<'english'>) could never match, so they are dropped with the
warning C<"Ignoring '...' in the supported list: not a language code">.
An empty list is allowed; L</language> then always returns C<'Unknown'>.

=item * C<cache> (optional)

An object with C<get()>, C<set()> and C<remove()> methods, such as a L<CHI> object.
CGI::Lingua stores its answers here so that later requests are faster.
If a call to the cache dies (for example a full disc, an unreachable server,
or a L<CHI> object created with C<< on_get_error =E<gt> 'die' >>), CGI::Lingua
warns C<"Cache get failed: ..."> (or C<set> / C<remove>) and carries on as if
the value was not cached. Any method that uses the cache can give this warning.

Everything read back from the cache is checked before it is used, because a
cache can be shared with, or written by, other programs. A value that does not
have the shape CGI::Lingua stores (for example C<< gb<script> >> as a country, or
a hash where a language name should be) is removed and warned about with
C<"Discarding malformed cache entry for ...">, and the answer is worked out
again.

=item * C<config_file> (optional)

The path to a configuration file. It is read by L<Object::Configure>.
Values in this file B<replace> the arguments that you give to C<new()>
(see L</COMMON PITFALLS>).

=item * C<logger> (optional)

Where to send messages. This can be an object with C<warn()>, C<info()> and
C<error()> methods, or any value that L<Object::Configure> accepts
(for example an array reference, which collects the messages).
It is always changed into a L<Log::Abstraction> object.
Without a logger, warnings go to L<Carp>.

=item * C<info> (optional)

A L<CGI::Info> object (or any object with a C<lang()> method).
A C<lang> parameter in the request is then used before the browser's
settings. The parameter comes from the visitor, so it is checked like the
C<Accept-Language> header (see L</ENCODING>); a value that fails is ignored with
the warning C<"lang parameter contains invalid characters; ignoring">.

=item * C<dont_use_ip> (optional, default false)

When true, CGI::Lingua never guesses the language from the visitor's
IP address.

=item * C<syslog> (optional)

Passed on to the logging configuration.

=item * C<debug> (optional, default false)

When true, L<I18N::AcceptLanguage> prints debug information.

=back

If you call C<new()> on an existing object, you get a copy of that object.
The arguments you give replace the values in the copy.
The copy also keeps any answers that the original has already worked out
(see L</COMMON PITFALLS>).

=head3 API SPECIFICATION

=head4 Input

    {
        supported           => { type => 'string|arrayref', optional => 0 },
        supported_languages => { type => 'string|arrayref', optional => 1 },
        cache               => { type => 'object', can => ['get', 'set'], optional => 1 },
        config_file         => { type => 'string', optional => 1 },
        logger              => { type => 'object|arrayref|hashref|string', optional => 1 },
        info                => { type => 'object', can => 'lang', optional => 1 },
        dont_use_ip         => { type => 'boolean', optional => 1 },
        syslog              => { type => 'boolean|hashref', optional => 1 },
        debug               => { type => 'boolean', optional => 1 },
    }

You must give C<supported> or its other name C<supported_languages>.
A string must be 2 to 5 characters long.

=head4 Output

    {
        type => 'object',
        isa  => 'CGI::Lingua',
    }

=head3 EXAMPLE

    # The most common form: a list of supported codes
    my $l = CGI::Lingua->new(supported => ['en', 'fr', 'de']);

    # One supported language
    my $l = CGI::Lingua->new(supported => 'en');

    # With a cache, a logger and a CGI::Info object
    use CHI;
    use CGI::Info;
    my $l = CGI::Lingua->new({
        supported => ['en', 'fr'],
        cache     => CHI->new(driver => 'File', root_dir => '/var/cache/myapp'),
        logger    => \my @messages,
        info      => CGI::Info->new(),
    });

=head3 MESSAGES

C<new()> dies (with L<Carp/croak>) with one of these messages:

    "You must give a list of supported languages"
        - supported is missing, undef, 0 or the empty string
    "List of supported languages must be an array ref"
        - supported is a reference, but not to an array
    "Supported languages must be the short code"
        - supported is a string shorter than 2 or longer than 5 characters
    "Logger must be a blessed object with warn/info/error methods"
        - logger is an object that is missing one of these methods
    "CGI::Lingua use ->new() not ::new() to instantiate"
        - new() was called as a function, with arguments
    "info must be an object with a lang() method"
        - info is not an object, or has neither lang() nor AUTOLOAD

It warns, and carries on, with:

    "Ignoring '...' in the supported list: not a language code"
        - an entry of the supported list is not a language tag
    "Cache get failed: ..."
        - the cache died while looking up saved answers
    "Discarding malformed cache entry for ..."
        - the saved answers were not in the shape CGI::Lingua writes

=head3 PSEUDOCODE

    1. Read the arguments with Params::Get
    2. If called on an object, return a copy with the new arguments on top
    3. If logger is an object, check that it has warn, info and error
    4. Merge in config_file and environment settings with Object::Configure
    5. Check supported (required; string of 2-5 characters, or an arrayref)
    6. If there is a cache and REMOTE_ADDR is set, try to load saved answers
       from the cache (JSON); if found, return them as an object
    7. Otherwise return a new object with no answers yet

=cut

=head2 language

Returns the name of the language to show to the visitor, in English,
for example C<'English'>, C<'French'> or C<'Japanese'>.
The language is always one of the languages in your C<supported> list.

Variants are handled sensibly.
If a visitor asks for American English (C<en-us>)
and your site only has British English (C<en-gb>),
C<language()> returns C<'English'>.

If none of the languages that the visitor wants is in your C<supported> list,
C<language()> returns the string C<'Unknown'>.
It never returns C<undef>.

=head3 API SPECIFICATION

=head4 Input

    {}

=head4 Output

    {
        type => 'string',
        min  => 1,
    }

=head3 EXAMPLE

    local $ENV{HTTP_ACCEPT_LANGUAGE} = 'fr,en;q=0.9';
    my $l = CGI::Lingua->new(supported => ['en', 'fr']);
    print $l->language();   # "French"

    local $ENV{HTTP_ACCEPT_LANGUAGE} = 'de';
    my $l = CGI::Lingua->new(supported => ['en', 'fr']);
    print $l->language();   # "Unknown"

=head3 MESSAGES

The first call to L</language> (or any other language method) warns, and
ignores the value, when one of its inputs is not acceptable:

    "lang parameter contains invalid characters; ignoring"
    "HTTP_ACCEPT_LANGUAGE contains invalid characters; ignoring"
    "LANG contains invalid characters; ignoring"

It also warns when it changes the deprecated tag C<en-uk> into C<en-gb>:

    "Resetting country code to GB for ..."

=cut

=head2 preferred_language

Another name for L</language>. It takes no arguments and returns the same value.

=head3 API SPECIFICATION

=head4 Input

    {}

=head4 Output

    {
        type => 'string',
        min  => 1,
    }

=cut

=head2 name

Another name for L</language>, so that a CGI::Lingua object can be used where a
L<Locale::Object::Language> object is expected.

=head3 API SPECIFICATION

=head4 Input

    {}

=head4 Output

    {
        type => 'string',
        min  => 1,
    }

=cut

=head2 sublanguage

Returns the name of the variant (usually a country) of the chosen language,
for example C<'United Kingdom'> when the chosen language is C<en-gb>.

Returns C<undef> when there is no variant, for example when the chosen
language is just C<en>, or when no language was found.

=head3 API SPECIFICATION

=head4 Input

    {}

=head4 Output

    {
        type     => 'string',
        min      => 1,
        optional => 1,
    }

=head3 EXAMPLE

    local $ENV{HTTP_ACCEPT_LANGUAGE} = 'en-gb';
    my $l = CGI::Lingua->new(supported => ['en-gb']);
    print $l->sublanguage();   # "United Kingdom"

=cut

=head2 language_code_alpha2

Returns the two-letter code (ISO 639-1) of the chosen language,
for example C<'en'> when the chosen language is C<en-gb>.

Returns C<undef> when none of the languages that the visitor wants is in your
C<supported> list (that is, when L</language> returns C<'Unknown'>).

=head3 API SPECIFICATION

=head4 Input

    {}

=head4 Output

    {
        type     => 'string',
        min      => 2,
        max      => 2,
        optional => 1,
    }

=head3 EXAMPLE

    local $ENV{HTTP_ACCEPT_LANGUAGE} = 'en-gb';
    my $l = CGI::Lingua->new(supported => ['en-gb']);
    print $l->language_code_alpha2();   # "en"

=cut

=head2 code_alpha2

Another name for L</language_code_alpha2>, kept so that old programs still work.

=head3 API SPECIFICATION

=head4 Input

    {}

=head4 Output

    {
        type     => 'string',
        min      => 2,
        max      => 2,
        optional => 1,
    }

=cut

=head2 sublanguage_code_alpha2

Returns the two-letter code of the variant of the chosen language,
in lower case, for example C<'gb'> when the chosen language is C<en-gb>.

Returns C<undef> when there is no variant.

=head3 API SPECIFICATION

=head4 Input

    {}

=head4 Output

    {
        type     => 'string',
        min      => 2,
        max      => 2,
        optional => 1,
    }

=head3 EXAMPLE

    local $ENV{HTTP_ACCEPT_LANGUAGE} = 'en-gb';
    my $l = CGI::Lingua->new(supported => ['en-gb']);
    print $l->sublanguage_code_alpha2();   # "gb"

=cut

=head2 requested_language

Returns, in English, the language that the visitor asked for,
B<whether or not your site supports it>.
Use it to tell the visitor that their language is not available.

If the visitor asked for a variant, it is shown in brackets,
for example C<'English (United Kingdom)'>. A variant that is not a known
country code is shown as it was sent, for example C<'English (Unknown: zz)'>.

Returns C<'Unknown'> when the visitor's language cannot be found at all.
It never returns C<undef>.

=head3 API SPECIFICATION

=head4 Input

    {}

=head4 Output

    {
        type => 'string',
        min  => 1,
    }

=head3 EXAMPLE

    local $ENV{HTTP_ACCEPT_LANGUAGE} = 'en-gb';
    my $l = CGI::Lingua->new(supported => ['en']);
    print $l->language();             # "English"
    print $l->requested_language();   # "English (United Kingdom)"

    local $ENV{HTTP_ACCEPT_LANGUAGE} = 'de';
    my $l = CGI::Lingua->new(supported => ['en']);
    print $l->language();             # "Unknown"
    print $l->requested_language();   # "German"

=cut