NAME

Database::BI::I18N - Choose the language of messages, and give them in it

VERSION

0.023.1

SYNOPSIS

use Database::BI::I18N;

# Per request (Database::BI does this in an around_dispatch hook):
local $Database::BI::I18N::LANGUAGE =
    Database::BI::I18N::choose(accept => 'en-US,en;q=0.9');   # 'en-us'

# In a module:
my $template = Database::BI::I18N::text(__PACKAGE__, \%MESSAGES, 'error_x');

DESCRIPTION

Every module keeps its messages, in British English, in its own %MESSAGES. A translation is a module Database::BI::I18N::<code> whose %MESSAGES maps each package to the messages that read differently in that language; anything it leaves out is given in British English. Database::BI::I18N::en_us is American English.

The language comes from CGI::Lingua: from the request's Accept-Language while a request is answered, and for the command-line scripts from the locale (LC_ALL, LC_MESSAGES, LANG), which each sets when it starts. English (United States) is en-us; every other English is en. Anything else - code calling a module directly, a test - gets British English.

FUNCTIONS

languages

my @codes = Database::BI::I18N::languages();   # ('en', 'en-us')

API SPECIFICATION

INPUT

None.

OUTPUT

The language codes messages can be given in, British English first.

choose

my $code = Database::BI::I18N::choose(accept => $header, default => 'en');

API SPECIFICATION

INPUT

accept:  string, optional; an Accept-Language value
default: string, optional; returned when accept names nothing supported
         (used only when it is one of languages(), else 'en')

OUTPUT

One of languages(): en-us when the header's best supported choice is English with the United States region, en for other English.

lingua_choice

my $code = Database::BI::I18N::lingua_choice($accept, ['en', 'en-us', 'fr']);

API SPECIFICATION

INPUT

$accept:    string; an Accept-Language value
\@supported: arrayref of language codes, each optionally with a region

OUTPUT

What CGI::Lingua picks from the list: a two-letter code, or code-region (lower case) when the header names a region the list holds. undef when it picks nothing, or the header is empty.

language

my $code = Database::BI::I18N::language();

API SPECIFICATION

INPUT

None. Reads $Database::BI::I18N::LANGUAGE.

OUTPUT

The code messages are given in now: the request's language (or the one a script set), else en. The environment is not read: code that calls a module directly gets British English whatever the locale.

from_locale

local $Database::BI::I18N::LANGUAGE = Database::BI::I18N::from_locale();

API SPECIFICATION

INPUT

None. CGI::Lingua (0.88 and later) reads LC_ALL, then LC_MESSAGES, then LANG, as POSIX does; LC_ALL=C names no language whatever LANG says. HTTP_ACCEPT_LANGUAGE is ignored here, even when set.

OUTPUT

One of languages(): the language the locale names, through CGI::Lingua (en_US.UTF-8 is en-us; en_GB.UTF-8, C, POSIX and an unset locale are en). The scripts set $LANGUAGE from it when they start.

text

my $template = Database::BI::I18N::text($package, \%messages, $key);

API SPECIFICATION

INPUT

$package:  string; the package whose message it is
\%messages: hashref; that package's %MESSAGES (British English)
$key:      string; the message key

OUTPUT

The message template (a sprintf format) in the current language: the translation's text for that package and key, else $messages->{$key}. undef when neither has the key.

AUTHOR

Nigel Horne <njh@nigelhorne.com>

LICENCE AND COPYRIGHT

Copyright 2026 Nigel Horne.

Usage is subject to the GPL2 licence terms.