Log::R...:Domain(3pm)

💖 Log::Report::Domain — the manual, but make it slay 💖

okay bestie, gather round, because this is the page for Log::Report::Domain, from the User Contributed Perl Documentation collection. she administers one text-domain. that's the whole vibe. let's go 🦋

---

✨ NAME ✨

Log::Report::Domain — administer one text-domain. yes queen, one whole domain, all to herself 💅

---

🌸 INHERITANCE 🌸

Log::Report::Domain
  is a Log::Report::Minimal::Domain

Log::Report::Domain is extended by
  Log::Report::Template::Textdomain

so she is a Minimal::Domain, and log-report-template's textdomain is the one extending her. family tree, but make it fashion 👑

---

🌈 SYNOPSIS 🌈

# internal usage
use Log::Report::Domain;
my $domain = Log::Report::Domain->new(name => $name);

# find a ::Domain object
use Log::Report 'my-domain';
my $domain = textdomain 'my-domain'; # find domain config
my $domain = textdomain;             # config of this package

# explicit domain configuration
package My::Package;
use Log::Report 'my-domain';         # set textdomain for package

textdomain $name, %configure;        # set config, once per program
(textdomain $name)->configure(%configure); # same
textdomain->configure(%configure);   # same if current package in $name

# implicit domain configuration
package My::Package;
use Log::Report 'my-domain', %configure;

# external file for configuration (perl or json format)
use Log::Report 'my-domain', config => $filename;

use Log::Report 'my-domain';
textdomain->configure(config => $filename);

---

💜 DESCRIPTION 💜

Log::Report can handle multiple sets of packages used by your program, all at the same time. iconic multitasking honestly. in the common case your program is made of more than one imported software distribution, and each of those contains a bunch of packages. so, to keep the Log::Report configuration for each distribution separate, you should explicitly assign each package to a set, to a namespace. in translation lingo, this is a domain or text domain. and the default domain is named default. periodt.

for Log::Report, those package sets get selected with the text-domain value in the use statement:

use Log::Report 'my-domain';

there is so much you can configure per (text)domain. it's not only about translations — it's also, for instance, text formatting configuration (String::Print options, heyyyy). all the administration for that configuration lives in this package, and she's handling it 🫶

this class extends Log::Report::Minimal::Domain, which you'd use when your program doesn't want any of the overhead that comes with the powerful Log::Report features. in that case your program invokes Log::Report::Optional instead. low overhead, high vibes.

extends "DESCRIPTION" in Log::Report::Minimal::Domain.

---

🎀 METHODS 🎀

extends "METHODS" in Log::Report::Minimal::Domain.

🧚 Constructors

extends "Constructors" in Log::Report::Minimal::Domain.

$class->new(%options)

create a brand new Domain object ✨

-Option--Defined in                  --Default
 name    Log::Report::Minimal::Domain  <required>

• name => STRING — the name, and it is <required>, so no skipping it bestie.

💅 Attributes

extends "Attributes" in Log::Report::Minimal::Domain.

$obj->configure(%options)

the import is automatically called when the package is compiled. for all but one package in your distribution, it will only contain the name of the DOMAIN. for one package, it will contain configuration information. these %options are used for all packages which use the same DOMAIN. see the chapter "Configuring" below. improves base, see "Attributes" in Log::Report::Minimal::Domain.

-Option         --Defined in                  --Default
 config                                         undef
 context_rules                                  undef
 formatter        Log::Report::Minimal::Domain  PRINTI
 native_language                                'en_US'
 translator                                     created internally
 where            Log::Report::Minimal::Domain  <required>

• config => $file — read the settings from the $file. the parameters found in the file get used as defaults for the parameters above. this parameter is especially useful for the context_rules, which need to be shared between the running application and xgettext-perl. see readConfig().
• context_rules => %rules|OBJECT — when %rules are provided, the translator will use the msgctxt fields as provided by PO-files (gettext). this parameter initializes a Log::Report::Translator::Context helper object 💖
• formatter => CODE|%config|'PRINTI'
• native_language => CODESET — this is the language you used to write the translatable and the non-translatable messages in. in case no translation is needed, you still want the system error messages in the same language as the report. and of course, each textdomain can define its own. do your thing, bestie 🌸
• translator => Log::Report::Translator|%config — set the object which will do the translations for this domain.
• where => ARRAY

$obj->contextRules()

$obj->format()

inherited, see "Attributes" in Log::Report::Minimal::Domain.

$obj->isConfigured()

inherited, see "Attributes" in Log::Report::Minimal::Domain.

$obj->name()

inherited, see "Attributes" in Log::Report::Minimal::Domain.

$obj->nativeLanguage()

$any->readConfig($filename)

helper method, which simply parses the content $filename into a HASH, to be used as parameters to configure(). the filename must end on '.pl', to indicate that it uses perl syntax (it can be processed with Perl's do command), or end on '.json'. see also the chapter "Configuring" below.

currently, this file can be in Perl native format (when ending on ".pl") or JSON (when it ends with ".json"). various modules may explain parts of what can be found in these files — for instance Log::Report::Translator::Context. iykyk 🦋

$obj->translator()

⭐ Translating

extends "Translating" in Log::Report::Minimal::Domain.

$obj->defaultContext()

returns the current default translation context settings as a HASH. you should not modify the content of that HASH: change it by calling setContext() or updateContext(). hands off the goods, bestie 🙈

$obj->interpolate( $msgid, [$args] )

inherited, see "Translating" in Log::Report::Minimal::Domain.

$obj->setContext(STRING|HASH|ARRAY|PAIRS)

temporarily set the default translation context for messages. this gets used when the message is created without a "_context" parameter. the context can be retrieved with defaultContext().

contexts are totally ignored when there are no "context_rules". when you don't wish to change settings, you may simply provide an empty "HASH".

» example:

use Log::Report 'my-domain', context_rules => {};

$obj->translate($message, $language)

translate the $message into the $language. 🌈

$obj->updateContext(STRING|HASH|ARRAY|PAIRS)

[1.10] make changes and additions to the active context (see setContext()).

---

🔥 DETAILS 🔥

💖 Configuring

configuration of a domain can happen in so many ways: either explicitly or implicitly. the explicit form:

package My::Package;
use Log::Report 'my-domain';

textdomain 'my-domain', %configuration;
textdomain->configure(%configuration);
textdomain->configure(\%configuration);

textdomain->configure(conf => $filename);

the implicit form is (no variables possible, only constants!):

package My::Package;
use Log::Report 'my-domain', %configuration;
use Log::Report 'my-domain', conf => '/filename';

you can only configure your domain in one place in your program. the textdomain setup is then used for all packages in the same domain. one setup, whole squad covered 💅

this also works for Log::Report::Optional, which is a dressed-down version of Log::Report.

🌸 configuring your own formatter

[0.91] the "PRINTI" is a special constants for configure(formatter), and will use String::Print function printi(), with the standard tricks.

textdomain 'some-domain',
  formatter => {
     class     => 'String::Print',    # default
     method    => 'sprinti',          # default
     %options,   # constructor options for String::Print
  );

when you want your own formatter, or configuration of "String::Print", you need to pass a CODE. be aware that you may lo(o)se magic added by Log::Report and other layers, like Log::Report::Template:

textdomain 'some-domain', formatter => \&my_formatter;

⚠️ fr fr, pass a CODE and you might lose the magic. proceed with intention, bestie.

🦋 configuring global values

say you log for a (Dancer) webserver, where you wish to include the website name in some of the log lines. for this, (ab)use the translation context:

### first, enable translation contexts
use Log::Report 'my-domain', context_rules => { ... };

# or
use Log::Report 'my-domain';
textdomain->configure(context_rules => { ... });

# or
textdomain 'my-domain', content_rules => { ... };

### every time you start working for a different virtual host
(textdomain 'my-domain')->setContext(host => $host);

### now you can use that in your code
package My::Package;
use Log::Report 'my-domain';
error __x"in {_context.host} not logged-in {user}", user => $username;

ate 🔥

---

💀 DIAGNOSTICS 💀

• Warning: Missing key '$key' in format '$format', file $use
  • cast by configure()
• Fault: cannot open JSON file for context at $fn: $!
  • cast by readConfig()
• Error: the native_language '$locale' is not a valid locale
  • cast by configure()
• Error: unsupported context file type for $fn
  • cast by readConfig()
• Error: you need to configure context_rules before setContext
  • cast by setContext()

---

👑 SEE ALSO 👑

this module is part of Log-Report version 1.46, built on June 16, 2026. website: http://perl.overmeer.net/CPAN/

---

🎀 LICENSE 🎀

for contributors see file ChangeLog.

this software is copyright (c) 2007-2026 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. iconic and generous, we love to see it 💖

---

and that's the whole page, bestie — written by hand for perl v5.40.1, dated 2026-07-05, and it lives in Log::R...:Domain(3pm) land 🫶✨ no cap, you're now officially qualified to administer a text-domain. go slay 🌈💅