NAME

Log::Report::Extract::PerlPPI - Collect translatable strings from Perl using PPI

INHERITANCE

Log::Report::Extract::PerlPPI
  is a Log::Report::Extract

SYNOPSIS

my $ppi = Log::Report::Extract::PerlPPI->new(
  lexicon => '/usr/share/locale',
);
$ppi->process('lib/My/Pkg.pm');  # call for each .pm file
$ppi->showStats;                 # optional
$ppi->write;

# See script  xgettext-perl
bin/xgettext-perl -p $lexdir @source_dirs

DESCRIPTION

This module helps maintaining the POT files, updating the list of message-ids which are kept in them. After initiation, the process() method needs to be called with all files which changed since last processing and the existing PO files will get updated accordingly.

If no translations exist yet, one $lexicon/$domain.po file will be created. If you want to start a translation, copy $lexicon/$domain.po to $lexicon/$domain/$lang.po and edit that file. You may use poedit to edit po-files. There are many smart translation management applications which can hand po-files, for instance Pootle and Weblate.

Do not forget to add the new po-file to your distribution (MANIFEST)

Extends "DESCRIPTION" in Log::Report::Extract.

The extraction process

All pm-files need to be processed in one go: no incremental processing!

The Perl source is parsed using PPI, which does understand Perl syntax quite well, but does not support all features.

Automatically, the textdomain of the translations is discovered, as first parameter of use Log::Report. You may switch textdomain inside one pm-file.

When all files have been processed, during the write(), all existing po-files for all discovered textdomains will get updated. Not only the $lexicon/$domain.po template, but also all $lexicon/$domain/$lang.po will be replaced. When a msgid has disappeared, existing translations will get disabled, not removed. New msgids will be added and flagged "fuzzy".

What is extracted?

This script will extract the msgids used in __(), __x(), __xn(), and __n() (implemented by Log::Report) For instance

__x"msgid", @more
__x'msgid', @more  <--- no!  syntax error!
__x("msgid", @more)
__x('msgid', @more)
__x(msgid => @more)

Besides, there are some helpers which are no-ops in the code, only to fill the po-tables: N__(), N__n(), N__()

What is not extracted?

Not extracted are the usage of anything above, where the first parameter is not a simple string. Not extracted are

__x($format, @more)
__x$format, @more
__x(+$format, _domain => 'other domain', @more)
__x($first.$second, @more)

In these cases, you have to use N__() functions to declare the possible values of $format.

METHODS

Extends "METHODS" in Log::Report::Extract.

Constructors

Extends "Constructors" in Log::Report::Extract.

$class->new(%options)

Inherited, see "Constructors" in Log::Report::Extract

Accessors

Extends "Accessors" in Log::Report::Extract.

$obj->addPot($domain, $pot, %options)

Inherited, see "Accessors" in Log::Report::Extract

$obj->charset()

Inherited, see "Accessors" in Log::Report::Extract

$obj->domains()

Inherited, see "Accessors" in Log::Report::Extract

$obj->index()

Inherited, see "Accessors" in Log::Report::Extract

$obj->pots($domain)

Inherited, see "Accessors" in Log::Report::Extract

Processors

Extends "Processors" in Log::Report::Extract.

$obj->cleanup(%options)

Inherited, see "Processors" in Log::Report::Extract

$obj->process($filename, %options)

Update the domains mentioned in the $filename. All textdomains defined in the file will get updated automatically, but not written before all files where processed. Improves base, see "Processors" in Log::Report::Extract

-Option --Default
 charset  'iso-8859-1'

charset => STRING

$obj->showStats( [$domains] )

Inherited, see "Processors" in Log::Report::Extract

$obj->store( $domain, $filename, $linenr, $context, $msg, [$msg_plural] )

Inherited, see "Processors" in Log::Report::Extract

$obj->write( [$domain], %options )

Inherited, see "Processors" in Log::Report::Extract

DIAGNOSTICS

Error: PPI only supports iso-8859-1 (latin-1) on the moment

Cast by process()

Fault: cannot create lexicon directory $dir: $!

Cast by new()

Fault: cannot read perl from file $filename: $!

Cast by process()

Error: count missing in $function in line $line

Cast by process()

Error: extractions require an explicit lexicon directory

Cast by new()

Info: no Perl in file $filename

Cast by process()

Error: no context tags allowed in plural `$msgid'

Cast by store()

Info: processing file $fn in $charset

Cast by process()

Info: starting new textdomain $domain, template in $filename

Cast by write()

Error: string is incorrect at line $line: $error

Cast by process()

Warning: use double quotes not single, in $string on $file line $line

Cast by process()

SEE ALSO

This module is part of Log-Report-Lexicon version 1.14, built on September 08, 2025. Website: http://perl.overmeer.net/CPAN/

LICENSE

For contributors see file ChangeLog.

This software is copyright (c) 2007-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.

cpanm Log::Report::Lexicon

perl -MCPAN -e shell
install Log::Report::Lexicon