format => sub { '['.localtime().'] '.$_[0] }
   format => sub { shift }   # no timestamp
   format => 'LONG'
    

The first parameter to format is the string to print; it is already translated and trailed by a newline. The second parameter is the text-domain (if known).

[1.10] As third parameter, you get the $msg raw object as well (maybe you want to use the message context?) [1.19] After the three positional parameters, there may be a list of pairs providing additional facts about the exception. It may contain "location" information.

The "LONG" format is equivalent to:

  my $t = strftime "%FT%T", gmtime;
  "[$t $$] $_[1] $_[0]"
    

Use of context:

   format => sub { my ($msgstr, $domain, $msg, %more) = @_;
      my $host = $msg->context->{host};
      "$host $msgstr";
   }
    

Use the LOCALE setting by default, which is LC_CTYPE or LC_ALL or LANG (in that order). If these contain a character-set which Perl understands, then that is used, otherwise silently ignored.

When cleaning-up the dispatcher, the file will only be closed in case of a FILENAME.

[1.10] When you pass a CODE, then for each log message the function is called with two arguments: this dispatcher object and the message object. In some way (maybe via the message context) you have to determine the log filename. This means that probably many log-files are open at the same time.

   # configuration time
   dispatcher FILE => 'logfile', to =>
       sub { my ($disp, $msg) = @_; $msg->context->{logfile} };

   # whenever you want to change the logfile
   textdomain->updateContext(logfile => '/var/log/app');
   (textdomain 'mydomain')->setContext(logfile => '/var/log/app');

   # or
   error __x"help", _context => {logfile => '/dev/tty'};
   error __x"help", _context => "logfile=/dev/tty";