=head1 Locale-XGettext

Extract strings from arbitrary formats into PO files

=head2 Description

When using 
LL<https://www.gnu.org/software/gettext/>
you often find yourself extracting translatable
strings from more or less exotic file formats that cannot be handled
by xgettext from the
LL<https://www.gnu.org/software/gettext/>
suite directly.  This package simplifies
the task of writing a string extractor in Perl, Python, Java, Ruby or
other languages by providing a common base needed for such scripts.

=head2 Usage

Included is a sample string extractor L<bin/xgettext-txt> for plain text files.  It simply
splits the input into paragraphs, and turns each paragraph into an
entry of a PO file.

=head2 Common Workflow

The idea of the package is that you just a write a parser plug-in for
C<Locale::XGettext> and use all the boilerplate code for generating the
PO file and for processing script options from this library.  One such
example is a parser plug-in for strings in templates for the
Template Toolkit version 2 included in the package 
LL<https://github.com/gflohr/Template-Plugin-Gettext>.
that contains a script C<xgettext-tt2> which can only extract
strings from that particular template language.

If this is the only source of translatable strings you are mostly done.
Often times you will, however, have to merge strings from all different
input formats into one single PO file.  Let's assume that your project
is written in Perl and C and that it also contains Template Toolkit
templates and plain text files that have to be translated.

=over

=item 1. Use C<xgettext-txt> from this package to extract strings from all
plain text files and write the output into C<text.pot>.

=item 2. Use C<xgettext-tt2> from 
LLL<https://github.com/gflohr/Template-Plugin-Gettext>
to extract all strings
from your templates into another file C<templates.pot>.

=item 3. Finally use C<xgettext> from
LLL<https://www.gnu.org/software/gettext/>
for extracting strings from
all source files written in Perl and C, I<and> from the previously
created pot files C<text.pot> and C<templates.pot>.  This works
because C<xgettext> natively understands C<.po> resp. C<.pot> files.

=back

By the way, all xgettext flavors based on C<Locale::XGettext>
are also able to extract strings from C<.po> or C<.pot> files.  So you
can also make do completely without GNU gettext and use any C<Locale::XGettext>
extractor instead of GNU gettext for the last step.

=head2 Writing Extractors

Writing an extractor is as easy as implementing one single method that
takes a filename argument and extract strings from that file.  See 
the manual page
LL<http://search.cpan.org/~guido/Locale-XGettext/lib/Locale/XGettext.pm>
for more information.  See L<samples/README.md>
as a starting point for writing an extractor in Perl or many
other languages.  The distribution currently contains fully functional
examples written in L<samples/C/README.md>, L<samples/Java/README.md>, 
L<samples/Python/README.md>, L<samples/Perl/README.md>,
and L<samples/Ruby/README.md>.

=head2 Differences To C<xgettext> From GNU Gettext

There a couple of subtle differences in the handling of command-line
arguments between extractors based on C<Locale::XGettext> and
the original C<xgettext> program.  Report a bug if you think that
a particular difference is a bug and not an improvement.

One thing that C<Locale::XGettext> does not support is the prefix
"pass-" for flag definitions.  While it is possible for an
extractor to implement the behavior of GNU gettext, this is not
directly supported by C<Locale::XGettext>.  Instead, that
prefix is simply ignored, when specified on the command-line
for an option argument to "--flag" or as part of the set of 
default flags for a particular extractor.

Additionally, while C<xgettext> from GNU gettext has a hard-coded,
fixed set of supported formats, you can specify arbitrary formats
with "--flag" for extractors based on C<Locale::XGettext>.

=head2 Installation

=head3 From CPAN

You can install the latest version of C<Locale::XGettext> from
LL<http://search.cpan.org/> with:

C<
$ cpan Locale::XGettext
>

If the command C<cpan> is not installed, try instead:

C<
$ perl -MCPAN -e 'install Locale::XGettext'
>

=head3 From Sources

Download the sources from 
LL<https://github.com/gflohr/Locale-XGettext> and

C<
$ tar cxf Locale-XGettext-VERSION.tar.gz
$ cd Locale-XGettext-VERSION
$ perl Makefile.PL
$ make
$ make test
$ make install
>

=head3 From Git

C<
$ git clone https://github.com/gflohr/Locale-XGettext.git
$ cd Locale-XGettext
$ dzil build
$ cd Locale-XGettext-VERSION
>

From here, follow the instructions for installation from sources.

The command C<dzil> is part of LL<http://search.cpan.org/~rjbs/Dist-Zilla/>.

=head2 TODO

The module should ship with its own PO parser and writer.

=head2 Bugs

Please report bugs at 
LL<https://github.com/gflohr/Locale-XGettext/issues>

=head2 Copyright

Copyright (C) 2016-2017, Guido Flohr, L<mailto:guido.flohr@cantanea.com>, 
all rights reserved.
