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.