.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Locale::TextDomain 3pm"
.TH Locale::TextDomain 3pm "2022-12-22" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Locale::TextDomain \- Perl Interface to Uniforum Message Translation
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use Locale::TextDomain (\*(Aqmy\-package\*(Aq, @locale_dirs);
\& 
\& use Locale::TextDomain qw (my\-package);
\& 
\& my $translated = _\|_"Hello World!\en";
\& 
\& my $alt = $_\|_{"Hello World!\en"};
\& 
\& my $alt2 = $_\|_\->{"Hello World!\en"};
\&
\& my @list = (N_\|_"Hello",
\&             N_\|_"World");
\& 
\& printf (_\|_n ("one file read", 
\&              "%d files read", 
\&              $num_files),
\&         $num_files);
\&
\& print _\|_nx ("one file read", "{num} files read", $num_files,
\&             num => $num_files);
\&
\& my $translated_context = _\|_p ("Verb, to view", "View");
\&
\& printf (_\|_np ("Files read from filesystems",
\&               "one file read", 
\&               "%d files read", 
\&               $num_files),
\&         $num_files);
\&
\& print _\|_npx ("Files read from filesystems",
\&              "one file read", 
\&              "{num} files read", 
\&              $num_files,
\&              num => $num_files);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The module \fBLocale::TextDomain\fR\|(3pm) provides a high-level interface
to Perl message translation.
.SS "Textdomains"
.IX Subsection "Textdomains"
When you request a translation for a given string, the system used
in libintl-perl follows a standard strategy to find a suitable message
catalog containing the translation: Unless you explicitly define
a name for the message catalog, libintl-perl will assume that your
catalog is called 'messages' (unless you have changed the default
value to something else via \fBLocale::Messages\fR\|(3pm), method \fBtextdomain()\fR).
.PP
You might think that his default strategy leaves room for optimization
and you are right.  It would be a lot smarter if multiple software
packages, all with their individual message catalogs, could be installed
on one system, and it should also be possible that third-party
components of your software (like Perl modules) can load their
message catalogs, too, without interfering with yours.
.PP
The solution is clear, you have to assign a unique name to your message
database, and you have to specify that name at run-time.  That unique
name is the so-called \fItextdomain\fR of your software package.  The name is
actually arbitrary but you should follow these best-practice guidelines
to ensure maximum interoperability:
.IP "File System Safety" 8
.IX Item "File System Safety"
In practice, textdomains get mapped into file names, and you should
therefore make sure that the textdomain you choose is a valid filename
on every system that will run your software.
.IP "Case-sensitivity" 8
.IX Item "Case-sensitivity"
Textdomains are always case-sensitive (i. e. 'Package' and '\s-1PACKAGE\s0'
are not the same).  However, since the message catalogs will be stored
on file systems, that may or may not distinguish case when looking
up file names, you should avoid potential conflicts here.
.IP "Textdomain Should Match \s-1CPAN\s0 Name" 8
.IX Item "Textdomain Should Match CPAN Name"
If your software is listed as a module on \s-1CPAN,\s0 you should simply 
choose the name on \s-1CPAN\s0 as your textdomain.  The textdomain for 
libintl-perl is hence 'libintl\-perl'.  But please replace all 
periods ('.') in your package name with an underscore because ...
.IP "Internet Domain Names as a Fallback" 8
.IX Item "Internet Domain Names as a Fallback"
\&... if your software is \fInot\fR a module listed on \s-1CPAN,\s0 as a last 
resort you should use the Java(tm) package scheme, i. e. choose
an internet domain that you are owner of (or ask the owner of an
internet domain) and concatenate your preferred textdomain with the
reversed internet domain.  Example: Your company runs the web-site
\&'www.foobar.org' and is the owner of the domain 'foobar.org'.  The
textdomain for your company's software 'barfoos' should hence be
\&'org.foobar.barfoos'.
.PP
If your software is likely to be installed in different versions on
the same system, it is probably a good idea to append some version
information to your textdomain.
.PP
Other systems are less strict with the naming scheme for textdomains
but the phenomena known as Perl is actually a plethora of small,
specialized modules and it is probably wisest to postulate some
namespace model in order to avoid chaos.
.SS "Binding textdomains to directories"
.IX Subsection "Binding textdomains to directories"
Once the system knows the \fItextdomain\fR of the message that you 
want to get translated into the user's language, it still has to
find the correct message catalog.  By default, libintl-perl will
look up the string in the translation database found in the 
directories \fI/usr/share/locale\fR and \fI/usr/local/share/locale\fR
(in that order).
.PP
It is neither guaranteed that these directories exist on the target
machine, nor can you be sure that the installation routine has write 
access to these locations.  You can therefore instruct libintl-perl 
to search other directories prior to the default directories.  Specifying 
a different search directory is called \fIbinding\fR a textdomain to a
directory.
.PP
Beginning with version 1.20, \fBLocale::TextDomain\fR extends the default 
strategy by a Perl-specific approach.  If File::ShareDir is installed, it 
will look in the subdirectories named \fIlocale\fR and \fILocaleData\fR (in that 
order) in the directory returned by \f(CW\*(C`File::ShareDir::dist_dir ($textdomain)\*(C'\fR
(if File::ShareDir is installed),
and check for a database containing the message for your textdomain there.
This allows you to install your database in the Perl-specific shared directory
using Module::Install's \f(CW\*(C`install_share\*(C'\fR directive or the Dist::Zilla
ShareDir plugin.
.PP
If File::ShareDir is not available, or if Locale::TextDomain fails to find
the translation files in the File::ShareDir directory, it will next look in
every directory found in the standard include path \f(CW@INC\fR, and check for a
database containing the message for your textdomain there. Example: If the
path \fI/usr/lib/perl/5.8.0/site_perl\fR is in your \f(CW@INC\fR, you can install your
translation files in \fI/usr/lib/perl/5.8.0/site_perl/LocaleData\fR, and they
will be found at run-time.
.SH "USAGE"
.IX Header "USAGE"
It is crucial to remember that you use \fBLocale::TextDomain\fR\|(3) as
specified in the section \*(L"\s-1SYNOPSIS\*(R"\s0, that means you have to 
\&\fBuse\fR it, not \fBrequire\fR it.  The module behaves quite differently 
compared to other modules.
.PP
The most significant difference is the meaning of the list passed
as an argument to the \fBuse()\fR function.  It actually works like this:
.PP
.Vb 1
\&    use Locale::TextDomain (TEXTDOMAIN, DIRECTORY, ...)
.Ve
.PP
The first argument (the first string passed to \fBuse()\fR) is the textdomain
of your package, optionally followed by a list of directories to search
\&\fIinstead\fR of the Perl-specific directories (see above: \fI/LocaleData\fR
appended to a \fIFile::ShareDir\fR directory and every path in \f(CW@INC\fR).
.PP
If you are the author of a package 'barfoos', you will probably put
the line
.PP
.Vb 1
\&    use Locale::TextDomain \*(Aqbarfoos\*(Aq;
.Ve
.PP
resp. for non-CPAN modules
.PP
.Vb 1
\&    use Locale::TextDomain \*(Aqorg.foobar.barfoos\*(Aq;
.Ve
.PP
in every module of your package that contains translatable strings. If
your module has been installed properly, including the message catalogs,
it will then be able to retrieve these translations at run-time.
.PP
If you have not installed the translation database in a directory
\&\fILocaleData\fR in the File::ShareDir directory or the standard include
path \f(CW@INC\fR (or in the system directories \fI/usr/share/locale\fR resp.
\&\fI/usr/local/share/locale\fR), you have to explicitly specify a search
path by giving the names of directories (as strings!) as additional
arguments to \fBuse()\fR:
.PP
.Vb 1
\&    use Locale::TextDomain qw (barfoos ./dir1 ./dir2);
.Ve
.PP
Alternatively you can call the function \fBbindtextdomain()\fR with suitable
arguments (see the entry for \fBbindtextdomain()\fR in 
\&\*(L"\s-1FUNCTIONS\*(R"\s0 in Locale::Messages).  If you do so, you should pass 
\&\f(CW\*(C`undef\*(C'\fR as an additional argument in order to avoid unnecessary
lookups:
.PP
.Vb 1
\&    use Locale::TextDomain (\*(Aqbarfoos\*(Aq, undef);
.Ve
.PP
You see that the arguments given to \fBuse()\fR have nothing to do with
what is imported into your namespace, but they are rather arguments
to \fBtextdomain()\fR, resp. \fBbindtextdomain()\fR.  Does that mean that 
\&\fBLocale::TextDomain\fR exports nothing into your namespace? Umh, not
exactly ... in fact it imports \fIall\fR functions listed below into
your namespace, and hence you should not define conflicting functions
(and variables) yourself.
.PP
So, why has Locale::TextDomain to be different from other modules?
If you have ever written software in C and prepared it for 
internationalization (i18n), you will probably have defined some
preprocessor macros like:
.PP
.Vb 2
\&    #define _(String) dgettext ("my\-textdomain", String)
\&    #define N_(String) String
.Ve
.PP
You only have to define that once in C, and the textdomain for your
package is automatically inserted into all gettext functions.  In 
Perl there is no such mechanism (at least it is not portable,
option \-P) and using the gettext functions could become quite
cumbersome without some extra fiddling:
.PP
.Vb 1
\&    print dgettext ("my\-textdomain", "Hello world!\en");
.Ve
.PP
This is no fun.  In C it would merely be a
.PP
.Vb 1
\&    printf (_("Hello world!\en"));
.Ve
.PP
Perl has to be more concise and shorter than C ... see the next
section for how you can use \fBLocale::TextDomain\fR to end up in Perl 
with a mere
.PP
.Vb 1
\&    print _\|_"Hello World!\en";
.Ve
.SH "EXPORTED FUNCTIONS"
.IX Header "EXPORTED FUNCTIONS"
All functions have quite funny names on purpose.  In fact the 
purpose for that is quite clear: They should be short, operator-like,
and they should not yell for conflicts with existing functions in
\&\fIyour\fR namespace.  You will understand it, when you internationalize
your first Perl program or module.  Preparing it is more like marking
strings as being translatable than inserting function calls.  Here
we go:
.IP "\fB_\|_ \s-1MSGID\s0\fR" 4
.IX Item "__ MSGID"
\&\fB\s-1NOTE:\s0\fR This is a \fIdouble\fR underscore!
.Sp
The basic and most-used function.  It is a short-cut for a call
to \fBgettext()\fR resp. \fBdgettext()\fR, and simply returns the translation for
\&\fB\s-1MSGID\s0\fR.  If your old code reads like this:
.Sp
.Vb 1
\&    print "permission denied";
.Ve
.Sp
You will now write:
.Sp
.Vb 1
\&    print _\|_"permission denied";
.Ve
.Sp
That's all, the string will be output in the user's preferred language,
provided that you have installed a translation for it.
.Sp
Of course you can also use parentheses:
.Sp
.Vb 1
\&    print _\|_("permission denied");
.Ve
.Sp
Or even:
.Sp
.Vb 1
\&    print (_\|_("permission denied"));
.Ve
.Sp
In my eyes, the first version without parentheses looks best.
.IP "\fB_\|_x \s-1MSGID, ID1\s0 => \s-1VAL1, ID2\s0 => \s-1VAL2, ...\s0\fR" 4
.IX Item "__x MSGID, ID1 => VAL1, ID2 => VAL2, ..."
One of the nicest features in Perl is its capability to interpolate
variables into strings:
.Sp
.Vb 1
\&    print "This is the $color $thing.\en";
.Ve
.Sp
This nice feature might con you into thinking that you could now
write
.Sp
.Vb 1
\&    print _\|_"This is the $color $thing.\en";
.Ve
.Sp
Alas, that would be nice, but it is not possible.  Remember that the
function _\|_() serves both as an operator for translating strings 
\&\fIand\fR as a mark for translatable strings.  If the above string would
get extracted from your Perl code, the un-interpolated form would
end up in the message catalog because when parsing your code it
is unpredictable what values the variables \f(CW$thing\fR and \f(CW$color\fR
will have at run-time (this fact is most probably one of the reasons
you have written your program for).
.Sp
However, at run-time, Perl will have interpolated the values already
\&\fIbefore\fR _\|_() (resp. the underlying \fBgettext()\fR function) has seen the
original string.  Consequently something like \*(L"This is the red car.\en\*(R"
will be looked up in the message catalog, it will not be found (because
only \*(L"This is the \f(CW$color\fR \f(CW$thing\fR.\en\*(R" is included in the database), 
and the original, untranslated string will be returned.
Honestly, because this is almost always an error, the \fBxgettext\fR\|(1)
program will bail out with a fatal error when it comes across that
string in your code.
.Sp
There are two workarounds for that:
.Sp
.Vb 1
\&    printf _\|_"This is the %s %s.\en", $color, $thing;
.Ve
.Sp
But that has several disadvantages: Your translator will only
see the isolated string, and without the surrounding code it
is almost impossible to interpret it correctly.  Of course, \s-1GNU\s0
emacs and other software capable of editing \s-1PO\s0 translation files
will allow you to examine the context in the source code, but it
is more likely that your translator will look for a less challenging
translation project when she frequently comes across such messages.
.Sp
And even if she does understand the underlying programming, what
if she has to reorder the color and the thing like in French:
.Sp
.Vb 2
\&    msgid "This is the red car.\en";
\&    msgstr "Cela est la voiture rouge.\en"
.Ve
.Sp
Zut alors! While it is possible to reorder the arguments to \fBprintf()\fR
and friends, it requires a syntax that is is nothing that you want to 
learn.
.Sp
So what? The Perl backend to \s-1GNU\s0 gettext has defined an alternative
format for interpolatable strings:
.Sp
.Vb 1
\&    "This is the {color} {thing}.\en";
.Ve
.Sp
Instead of Perl variables you use place-holders (legal Perl variables
are also legal place-holders) in curly braces, and then you call
.Sp
.Vb 3
\&    print _\|_x ("This is the {color} {thing}.\en", 
\&               thing => $thang,
\&               color => $color);
.Ve
.Sp
The function _\|\fB_x()\fR will take the additional hash and replace all
occurencies of the hash keys in curly braces with the corresponding
values.  Simple, readable, understandable to translators, what else
would you want?  And if the translator forgets, misspells or otherwise
messes up some \*(L"variables\*(R", the \fBmsgfmt\fR\|(1) program, that is used to
compile the textual translation file into its binary representation
will even choke on these errors and refuse to compile the translation.
.IP "\fB_\|_n \s-1MSGID, MSGID_PLURAL, COUNT\s0\fR" 4
.IX Item "__n MSGID, MSGID_PLURAL, COUNT"
Whew! That looks complicated ... It is best explained with an example.
We'll have another look at your vintage code:
.Sp
.Vb 5
\&    if ($files_deleted > 1) {
\&        print "All files have been deleted.\en";
\&    } else {
\&        print "One file has been deleted.\en";
\&    }
.Ve
.Sp
Your intent is clear, you wanted to avoid the cumbersome
\&\*(L"1 files deleted\*(R".  This is okay for English, but other languages
have more than one plural form.  For example in Russian it makes
a difference whether you want to say 1 file, 3 files or 6 files.
You will use three different forms of the noun 'file' in each
case.  [Note: Yep, very smart you are, the Russian word for 'file'
is in fact the English word, and it is an invariable noun, but if you
know that, you will also understand the rest despite this little
simplification ...].
.Sp
That is the reason for the existence of the function \fBngettext()\fR,
that _\|\fB_n()\fR is a short-cut for:
.Sp
.Vb 3
\&    print _\|_n"One file has been deleted.\en", 
\&             "All files have been deleted.\en",
\&             $files_deleted;
.Ve
.Sp
Alternatively:
.Sp
.Vb 3
\&    print _\|_n ("One file has been deleted.\en",
\&               "All files have been deleted.\en",
\&               $files_deleted);
.Ve
.Sp
The effect is always the same: libintl-perl will find out which
plural form to pick for your user's language, and the output string
will always look okay.
.IP "\fB_\|_nx \s-1MSGID, MSGID_PLURAL, COUNT, VAR1\s0 => \s-1VAL1, VAR2\s0 => \s-1VAL2, ...\s0\fR" 4
.IX Item "__nx MSGID, MSGID_PLURAL, COUNT, VAR1 => VAL1, VAR2 => VAL2, ..."
Bringing it all together:
.Sp
.Vb 4
\&    print _\|_nx ("One file has been deleted.\en",
\&                "{count} files have been deleted.\en",
\&                $num_files,
\&                count => $num_files);
.Ve
.Sp
The function _\|\fB_nx()\fR picks the correct plural form (also for English!)
\&\fIand\fR it is capable of interpolating variables into strings.
.Sp
Have a close look at the order of arguments: The first argument is the
string in the singular, the second one is the plural string. The third
one is an integer indicating the number of items.  This third argument
is \fIonly\fR used to pick the correct translation.  The optionally 
following arguments make up the hash used for interpolation.  In the
beginning it is often a little confusing that the variable holding the
number of items will usually be repeated somewhere in the interpolation
hash.
.IP "\fB_\|_xn \s-1MSGID, MSGID_PLURAL, COUNT, VAR1\s0 => \s-1VAL1, VAR2\s0 => \s-1VAL2, ...\s0\fR" 4
.IX Item "__xn MSGID, MSGID_PLURAL, COUNT, VAR1 => VAL1, VAR2 => VAL2, ..."
Does exactly the same thing as _\|\fB_nx()\fR.  In fact it is a common typo
promoted to a feature.
.IP "\fB_\|_p \s-1MSGCTXT, MSGID\s0\fR" 4
.IX Item "__p MSGCTXT, MSGID"
This is much like _\|_. The \*(L"p\*(R" stands for \*(L"particular\*(R", and the \s-1MSGCTXT\s0 
is used to provide context to the translator. This may be necessary
when your string is short, and could stand for multiple things. For example:
.Sp
.Vb 2
\&    print _\|_p"Verb, to view", "View";
\&    print _\|_p"Noun, a view", "View";
.Ve
.Sp
The above may be \*(L"View\*(R" entries in a menu, where View\->Source and File\->View 
are different forms of \*(L"View\*(R", and likely need to be translated differently.
.Sp
A typical usage are \s-1GUI\s0 programs.  Imagine a program with a main
menu and the notorious \*(L"Open\*(R" entry in the \*(L"File\*(R" menu.  Now imagine,
there is another menu entry Preferences\->Advanced\->Policy where you have 
a choice between the alternatives \*(L"Open\*(R" and \*(L"Closed\*(R".  In English, \*(L"Open\*(R"
is the adequate text at both places.  In other languages, it is very
likely that you need two different translations.  Therefore, you would
now write:
.Sp
.Vb 2
\&    _\|_p"File|", "Open";
\&    _\|_p"Preferences|Advanced|Policy", "Open";
.Ve
.Sp
In English, or if no translation can be found, the second argument
(\s-1MSGID\s0) is returned.
.Sp
This function was introduced in libintl-perl 1.17.
.IP "\fB_\|_px \s-1MSGCTXT, MSGID, VAR1\s0 => \s-1VAL1, VAR2\s0 => \s-1VAL2, ...\s0\fR" 4
.IX Item "__px MSGCTXT, MSGID, VAR1 => VAL1, VAR2 => VAL2, ..."
Like _\|\fB_p()\fR, but supports variable substitution in the string, like _\|\fB_x()\fR.
.Sp
.Vb 1
\&    print _\|_px("Verb, to view", "View {file}", file => $filename);
.Ve
.Sp
See _\|\fB_p()\fR and _\|\fB_x()\fR for more details.
.Sp
This function was introduced in libintl-perl 1.17.
.IP "\fB_\|_np \s-1MSGCTXT, MSGID, MSGID_PLURAL, COUNT\s0\fR" 4
.IX Item "__np MSGCTXT, MSGID, MSGID_PLURAL, COUNT"
This adds context to plural calls. It should not be needed very often,
if at all, due to the _\|\fB_nx()\fR function. The type of variable substitution
used in other gettext libraries (using sprintf-like sybols, like \f(CW%s\fR or \f(CW%1\fR)
sometimes required context. For a (bad) example of this:
.Sp
.Vb 5
\&    printf (_\|_np("[count] files have been deleted",
\&                "One file has been deleted.\en",
\&                "%s files have been deleted.\en",
\&                $num_files),
\&            $num_files);
.Ve
.Sp
\&\s-1NOTE:\s0 The above usage is discouraged. Just use the _\|\fB_nx()\fR call, which 
provides inline context via the key names.
.Sp
This function was introduced in libintl-perl 1.17.
.IP "\fB_\|_npx \s-1MSGCTXT, MSGID, MSGID_PLURAL, COUNT, VAR1\s0 => \s-1VAL1, VAR2\s0 => \s-1VAL2, ...\s0\fR" 4
.IX Item "__npx MSGCTXT, MSGID, MSGID_PLURAL, COUNT, VAR1 => VAL1, VAR2 => VAL2, ..."
This is provided for comleteness. It adds the variable interpolation
into the string to the previous method, _\|\fB_np()\fR.
.Sp
It's usage would be like so:
.Sp
.Vb 5
\&    print _\|_npx ("Files being permenantly removed",
\&                 "One file has been deleted.\en",
\&                 "{count} files have been deleted.\en",
\&                 $num_files,
\&                 count => $num_files);
.Ve
.Sp
I cannot think of any situations requiring this, but we can easily 
support it, so here it is.
.Sp
This function was introduced in libintl-perl 1.17.
.IP "\fBN_\|_(\s-1ARG1\s0)\fR" 4
.IX Item "N__(ARG1)"
A no-op function that simply echoes its arguments to the caller.  Take
the following piece of Perl:
.Sp
.Vb 5
\&    my @options = (
\&        "Open",
\&        "Save",
\&        "Save As",
\&    );
\&
\&    ...
\&
\&    my $option = $options[1];
.Ve
.Sp
Now say that you want to have this translatable.  You could sometimes
simply do:
.Sp
.Vb 5
\&    my @options = (
\&        _\|_"Open",
\&        _\|_"Save",
\&        _\|_"Save As",
\&    );
\&
\&    ...
\&
\&    my $option = $options[1];
.Ve
.Sp
But often times this will not be what you want, for example when you
also need the unmodified original string.  Sometimes it may not even
work, for example, when the preferred user language is not yet
determined at the time that the list is initialized.
.Sp
In these cases you would write:
.Sp
.Vb 5
\&    my @options = (
\&        N_\|_"Open",
\&        N_\|_"Save",
\&        N_\|_"Save As",
\&    );
\&
\&    ...
\&
\&    my $option = _\|_($options[1]);
\&    # or: my $option = dgettext (\*(Aqmy\-domain\*(Aq, $options[1]);
.Ve
.Sp
Now all the strings in \f(CW@options\fR will be left alone, since N_\|_()
returns its arguments (one ore more) unmodified.  Nevertheless, the
string extractor will be able to recognize the strings as being 
translatable.  And you can still get the translation later by passing
the variable instead of the string to one of the above translation
functions.
.IP "\fBN_\|_n (\s-1MSGID, MSGID_PLURAL, COUNT\s0)\fR" 4
.IX Item "N__n (MSGID, MSGID_PLURAL, COUNT)"
Does exactly the same as N_\|_().  You will use this form if you have 
to mark the strings as having plural forms.
.IP "\fBN_\|_p (\s-1MSGCTXT, MSGID\s0)\fR" 4
.IX Item "N__p (MSGCTXT, MSGID)"
Marks \fB\s-1MSGID\s0\fR as N_\|_() does, but in the context \fB\s-1MSGCTXT\s0\fR.
.IP "\fBN_\|_np (\s-1MSGCTXT, MSGID, MSGID_PLURAL, COUNT\s0)\fR" 4
.IX Item "N__np (MSGCTXT, MSGID, MSGID_PLURAL, COUNT)"
Marks \fB\s-1MSGID\s0\fR as N_\|\fB_n()\fR does, but in the context \fB\s-1MSGCTXT\s0\fR.
.SH "EXPORTED VARIABLES"
.IX Header "EXPORTED VARIABLES"
The module exports several variables into your namespace:
.IP "\fB\f(CB%_\fB\|_\fR" 4
.IX Item "%__"
A tied hash.  Its keys are your original messages, the values are
their translations:
.Sp
.Vb 1
\&    my $title = "<h1>$_\|_{\*(AqMy Homepage\*(Aq}</h1>";
.Ve
.Sp
This is much better for your translation team than
.Sp
.Vb 1
\&    my $title = _\|_"<h1>My Homepage</h1>";
.Ve
.Sp
In the second case the \s-1HTML\s0 code will make it into the translation
database and your translators have to be aware of \s-1HTML\s0 syntax when
translating strings.
.Sp
\&\fBWarning:\fR Do \fInot\fR use this hash outside of double-quoted strings!
The code in the tied hash object relies on the correct working of
the function \fBcaller()\fR (see \*(L"perldoc \-f caller\*(R"), and this function
will report incorrect results if the tied hash value is the argument
to a function from another package, for example:
.Sp
.Vb 1
\&  my $result = Other::Package::do_it ($_\|_{\*(AqSome string\*(Aq});
.Ve
.Sp
The tied hash code will see \*(L"Other::Package\*(R" as the calling package,
instead of your own package.  Consequently it will look up the message
in the wrong text domain.  There is no workaround for this bug.
Therefore:
.Sp
Never use the tied hash interpolated strings!
.IP "\fB\f(CB$_\fB\|_\fR" 4
.IX Item "$__"
A reference to \f(CW\*(C`%_\|_\*(C'\fR, in case you prefer:
.Sp
.Vb 1
\&     my $title = "<h1>$_\|_\->{\*(AqMy Homepage\*(Aq}</h1>";
.Ve
.SH "CLASS METHODS"
.IX Header "CLASS METHODS"
The following class methods are defined:
.IP "\fBoptions\fR" 4
.IX Item "options"
Returns a space-separated list of all '\-\-keyword' and all '\-\-flag' options
for \fB\fBxgettext\fB\|(1)\fR, when extracting strings from Perl source files localized
with \fBLocale::TextDomain\fR.
.Sp
The option should rather be called \fBxgettextDefaultOptions\fR.  With regard
to the typical use-case, a shorter name has been picked:
.Sp
.Vb 1
\&    xgettext \`perl \-MLocale::TextDomain \-e \*(Aqprint Locale::TextDomain\->options\*(Aq\`
.Ve
.Sp
See <https://www.gnu.org/software/gettext/manual/html_node/xgettext\-Invocation.html>
for more information about the xgettext options '\-\-keyword' and '\-\-flag'.
.Sp
If you want to disable the use of the xgettext default keywords, you
should pass an option '\-\-keyword=""' to xgettext before the options returned
by this method.
.Sp
If you doubt the usefulness of this method, check the output on the
command-line:
.Sp
.Vb 1
\&    perl \-MLocale::TextDomain \-e \*(Aqprint Locale::TextDomain\->options\*(Aq
.Ve
.Sp
Nothing that you want to type yourself.
.Sp
This method was added in libintl-perl 1.28.
.IP "\fBkeywords\fR" 4
.IX Item "keywords"
Returns a space-separated list of all '\-\-keyword' options for \fB\fBxgettext\fB\|(1)\fR 
so that all translatable strings are properly extracted.
.Sp
This method was added in libintl-perl 1.28.
.IP "\fBflags\fR" 4
.IX Item "flags"
Returns a space-separated list of all '\-\-flag' options for \fB\fBxgettext\fB\|(1)\fR 
so that extracted strings are properly flagged.
.Sp
This method was added in libintl-perl 1.28.
.SH "PERFORMANCE"
.IX Header "PERFORMANCE"
Message translation can be a time-consuming task.  Take this little
example:
.PP
.Vb 5
\&    1: use Locale::TextDomain (\*(Aqmy\-domain\*(Aq);
\&    2: use POSIX (:locale_h);
\&    3: 
\&    4: setlocale (LC_ALL, \*(Aq\*(Aq);
\&    5: print _\|_"Hello world!\en";
.Ve
.PP
This will usually be quite fast, but in pathological cases it may
run for several seconds.  A worst-case scenario would be a
Chinese user at a terminal that understands the codeset Big5\-HKSCS.
Your translator for Chinese has however chosen to encode the translations
in the codeset EUC-TW.
.PP
What will happen at run-time?  First, the library will search and load a
(maybe large) message catalog for your textdomain 'my\-domain'.  Then
it will look up the translation for \*(L"Hello world!\en\*(R", it will find that
it is encoded in EUC-TW.  Since that differs from the output codeset
Big5\-HKSCS, it will first load a conversion table containing several
ten-thousands of codepoints for EUC-TW, then it does the same with
the smaller, but still very large conversion table for Big5\-HKSCS,
it will convert the translation on the fly from EUC-TW into Big5\-HKSCS,
and finally it will return the converted translation.
.PP
A worst-case scenario but realistic.  And for these five lines of codes,
there is not much you can do to make it any faster.  You should understand,
however, \fIwhen\fR the different steps will take place, so that you can
arrange your code for it.
.PP
You have learned in the section \*(L"\s-1DESCRIPTION\*(R"\s0 that line 1 is 
responsible for locating your message database.  However, the
\&\fBuse()\fR will do nothing more than remembering your settings.  It will
not search any directories, it will not load any catalogs or 
conversion tables.
.PP
Somewhere in your code you will always have a call to 
\&\fBPOSIX::setlocale()\fR, and the performance of this call may be time-consuming,
depending on the architecture of your system.  On some systems, this
will consume very little time, on others it will only consume a
considerable amount of time for the first call, and on others it may
always be time-consuming.  Since you cannot know, how \fBsetlocale()\fR is
implemented on the target system, you should reduce the calls to
\&\fBsetlocale()\fR to a minimum.
.PP
Line 5 requests the translation for your string.  Only now, the library
will actually load the message catalog, and only now will it load
eventually needed conversion tables.  And from now on, all this information
will be cached in memory.  This strategy is used throughout libintl-perl,
and you may describe it as 'load\-on\-first\-access'.  Getting the next
translation will consume very little resources.
.PP
However, although the translation retrieval is somewhat obfuscated
by an operator-like function call, it is still a function call, and in
fact it even involves a chain of function calls.  Consequently, the
following example is probably bad practice:
.PP
.Vb 3
\&    foreach (1 .. 100_000) {
\&        print _\|_"Hello world!\en";
\&    }
.Ve
.PP
This example introduces a lot of overhead into your program.  Better
do this:
.PP
.Vb 4
\&    my $string = _\|_"Hello world!\en";
\&    foreach (1 .. 100_000) {
\&        print $string;
\&    }
.Ve
.PP
The translation will never change, there is no need to retrieve it
over and over again.  Although libintl-perl will of course cache
the translation read from the file system, you can still avoid the
overhead for the function calls.
.SH "AUTHOR"
.IX Header "AUTHOR"
Copyright (C) 2002\-2017 Guido Flohr <http://www.guido-flohr.net/>
(<mailto:guido.flohr@cantanea.com>), all rights reserved.  See the source
code for details!code for details!
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBLocale::Messages\fR\|(3pm), \fBLocale::gettext_pp\fR\|(3pm), \fBperl\fR\|(1),
\&\fBgettext\fR\|(1), \fBgettext\fR\|(3)