=encoding utf8

=head1 NAME

Log::Report::Template::Textdomain - template translation with one domain

=head1 INHERITANCE

 Log::Report::Template::Textdomain
   is a Log::Report::Domain
   is a Log::Report::Minimal::Domain

=head1 SYNOPSIS

  my $templater = Log::Report::Template->new(...);
  my $domain    = $templater->addTextdomain(%options);

=head1 DESCRIPTION

Manage one translation domain for L<Log::Report::Template|Log::Report::Template>.

Extends L<"DESCRIPTION" in Log::Report::Domain|Log::Report::Domain/"DESCRIPTION">.

=head1 METHODS

Extends L<"METHODS" in Log::Report::Domain|Log::Report::Domain/"METHODS">.

=head2 Constructors

Extends L<"Constructors" in Log::Report::Domain|Log::Report::Domain/"Constructors">.

=over 4

=item $class-E<gt>B<new>(%options)

Inherited, see L<Log::Report::Domain/"Constructors">

 -Option              --Defined in                  --Default
  lang                                                undef
  lexicon                                             undef
  name                  Log::Report::Minimal::Domain  <required>
  only_in_directory                                   undef
  templater                                           <required>
  translation_function                                'loc'

=over 2

=item lang => LANGUAGES

[1.01] Initial language to translate to.  Usually, this language which change
for each user connection via L<translateTo()|Log::Report::Template::Textdomain/"Translating">.

=item lexicon => DIRECTORY

=item name => STRING

=item only_in_directory => DIRECTORY|ARRAY

The textdomain can only be used in the indicated directories: if found
anywhere else, it's an error.  When not specified, the function is
allowed everywhere.

=item templater => Log::Report::Template-object

=item translation_function => STRING

The name of the function as used in the template to call for translation.
See L<function()|Log::Report::Template::Textdomain/"Attributes">.  It must be unique over all text-domains used.

=back

=item $class-E<gt>B<upgrade>($domain, %options)

Upgrade a base class L<Log::Report::Domain|Log::Report::Domain>-object into an Template
domain.

This is a bit akward process, needed when one of the code packages
uses the same domain as the templating system uses.  The generic domain
configuration stays intact.

=back

=head2 Attributes

Extends L<"Attributes" in Log::Report::Domain|Log::Report::Domain/"Attributes">.

=over 4

=item $obj-E<gt>B<configure>(%options)

Inherited, see L<Log::Report::Domain/"Attributes">

=item $obj-E<gt>B<contextRules>()

Inherited, see L<Log::Report::Domain/"Attributes">

=item $obj-E<gt>B<expectedIn>($filename)

Return C<true> when the function name which relates to this domain is
allowed to be used for the indicated file.  The msgid extractor will warn
when there is no match.

=item $obj-E<gt>B<function>()

Returns the name of the function which is used for translations.

=item $obj-E<gt>B<isConfigured>()

Inherited, see L<Log::Report::Minimal::Domain/"Attributes">

=item $obj-E<gt>B<lang>()

The language we are going to translate to.  Change this with L<translateTo()|Log::Report::Template::Textdomain/"Translating">
for this domain, or better L<Log::Report::Template::translateTo()|Log::Report::Template/"Attributes">.

=item $obj-E<gt>B<lexicon>()

Directory where the translation tables are kept.

=item $obj-E<gt>B<name>()

Inherited, see L<Log::Report::Minimal::Domain/"Attributes">

=item $obj-E<gt>B<nativeLanguage>()

Inherited, see L<Log::Report::Domain/"Attributes">

=item $any-E<gt>B<readConfig>($filename)

Inherited, see L<Log::Report::Domain/"Attributes">

=item $obj-E<gt>B<templater>()

The L<Log::Report::Template|Log::Report::Template> object which is using this textdomain.

=item $obj-E<gt>B<translator>()

Inherited, see L<Log::Report::Domain/"Attributes">

=back

=head2 Translating

Extends L<"Translating" in Log::Report::Domain|Log::Report::Domain/"Translating">.

=over 4

=item $obj-E<gt>B<defaultContext>()

Inherited, see L<Log::Report::Domain/"Translating">

=item $obj-E<gt>B<interpolate>( $msgid, [$args] )

Inherited, see L<Log::Report::Minimal::Domain/"Translating">

=item $obj-E<gt>B<setContext>(STRING|HASH|ARRAY|PAIRS)

Inherited, see L<Log::Report::Domain/"Translating">

=item $obj-E<gt>B<translate>($message, $language)

Inherited, see L<Log::Report::Domain/"Translating">

=item $obj-E<gt>B<translateTo>($lang)

Set the language to translate to for C<$lang>, for this domain only.  This may
be useful when various text domains do not support the same destination languages.
But in general, you can best use L<Log::Report::Template::translateTo()|Log::Report::Template/"Attributes">.

=item $obj-E<gt>B<translationFunction>()

This method returns a CODE which is able to handle a call for
translation by Template Toolkit.

=item $obj-E<gt>B<updateContext>(STRING|HASH|ARRAY|PAIRS)

Inherited, see L<Log::Report::Domain/"Translating">

=back

=head1 DETAILS

Extends L<"DETAILS" in Log::Report::Domain|Log::Report::Domain/"DETAILS">.

=head1 DIAGNOSTICS

=over 4

=item Warning: Missing key '$key' in format '$format', file $use

Cast by C<configure()>

=item Warning: Missing key '$key' in format '$format', in $use //template

Cast by C<translationFunction()>

=item Fault: cannot open JSON file for context at $fn: $!

Cast by C<readConfig()>

=item Error: extension to domain '$name' already exists

Cast by C<upgrade()>

=item Error: message does not contain counting alternatives in '$msgid'

Cast by C<translationFunction()>

=item Error: no counting positional for '$msgid'

Cast by C<translationFunction()>

=item Error: no counting positional for '$msgid'

Cast by C<translationFunction()>

=item Error: superfluous positional parameters for '$msgid'

Cast by C<translationFunction()>

=item Error: superfluous positional parameters for '$msgid'

Cast by C<translationFunction()>

=item Error: the native_language '$locale' is not a valid locale

Cast by C<configure()>

=item Error: unsupported context file type for $fn

Cast by C<readConfig()>

=item Error: you need to configure context_rules before setContext

Cast by C<setContext()>

=back

=head1 SEE ALSO

This module is part of Log-Report-Template version 1.04,
built on November 04, 2025. Website: F<http://perl.overmeer.net/CPAN/>

=head1 LICENSE

For contributors see file ChangeLog.

This software is copyright (c) 2017-2025 by Mark Overmeer.

This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.

