Log-Report-Template/lib/Log/Report/Template/Textdomain.pod
=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.