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.

       Log::Report::Extract::PerlPPI->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.

            -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] )
           Inherited, see "Processors" in Log::Report::Extract

SEE ALSO

       This module is part of Log-Report-Lexicon distribution version 1.09, built on August 28,
       2017. Website: http://perl.overmeer.net/log-report/

LICENSE

       Copyrights 2007-2017 by [Mark Overmeer]. For other contributors see ChangeLog.

       This program is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.  See http://dev.perl.org/licenses/