NAME

SYNOPSIS

    use base 'Locale::XGettext';

DESCRIPTION

See <https://github.com/gflohr/Locale-XGettext> for an overall picture of the software.

USAGE

    xgettext-LANG [OPTIONS] [INPUTFILE]...

LANG will be replaced by an identifier for the language that a specific extractor was written for, for example "xgettext-txt" for plain text files or "xgettext-tt2" for templates for the Template Toolkit version 2 (see Template).

By default, string extractors based on this module extract strings from one or more INPUTFILES and write the output to a file "messages.po" if any strings had been found.

OPTIONS

SUBCLASSING

    #! /usr/bin/env perl

    use Locale::Messages qw(setlocale LC_MESSAGES);
    use Locale::TextDomain qw(YOURTEXTDOMAIN);

    use Locale::XGettext::YOURSUBCLASS;

    Locale::Messages::setlocale(LC_MESSAGES, "");
    Locale::XGettext::YOURSUBCLASS->newFromArgv(\@ARGV)->run->output;

Writing the extractor class is also trivial:

    package Locale::XGettext::YOURSUBCLASS;

    use base 'Locale::XGettext';

    sub readFile {
        my ($self, $filename) = @_;

        foreach my $found (search_for_strings_in $filename) {
            $self->addEntry({
                msgid => $found->{string},
                # More possible fields following, see 
                # addEntry() below!
            }, $found->{possible_comment});
        }

        # The return value is actually ignored.
        return $self;
    }

All the heavy lifting happens in the method readFile() that you have to implement yourself. All other methods are optional.

See the section "METHODS" below for information on how to additionally modify the behavior your extractor.

CONSTRUCTORS

new $OPTIONS, @FILES

OPTIONS is a hash reference containing the above command-line options but with every hyphen replaced by an underscore. You should normally not use this constructor!

newFromArgv $ARGV

ARGV is a reference to a an array of command-line arguments that is passed verbatim to Getopt::Long::GetOptionsFromArray. After processing all options and arguments, the constructor new() above is then invoked with the cooked command-line arguments.

This is the constructor that you should normally use in custom extractors that you write.

METHODS

readFile FILENAME

You have to implement this method yourself. In it, read FILENAME, extract all relevant entries, and call addEntry() for each entry found.

The method is not invoked for filenames ending in ".po" or ".pot"! For those files, readPO() is invoked instead.

This method is the only one that you have to implement!

addEntry ENTRY[, COMMENT]

You should invoke this method for every entry found.

COMMENT is an optional comment that you may have extracted along with the message. Note that addEntry() checks whether this comment should make it into the output. Therefore, just pass any comment that you have found preceding the keyword.

ENTRY should be a reference to a hash with these possible keys:

keywords

Return a hash reference with all keyword definitions as Locale::XGettext::Util::Keyword objects.

keywordOptionStrings

Return a reference to an array with all keyword definitions as option strings suitable for the command-line option "--keyword".

flags

Return an array reference with all flag definitions as Locale::XGettext::Util::Flag objects.

flagOptionStrings

Return a reference to an array with all flag definitions as option strings suitable for the command-line option "--flag".

options

Get all command-line options as a hash reference.

option OPTION

Get the value for command line option OPTION.

setOption OPTION, VALUE

Set the value for command line option OPTION to VALUE.

languageSpecificOptions

The default representation returns nothing.

Your own implementation can return an reference to an array of arrays, each of them containing one option specification consisting of four items:

printLanguageSpecificOptions

Prints all language-specific options to standard output, calls languageSpecificOptions() internally. This is used for the output for the option "--help".

fileInformation

Returns nothing by default. You can return a string describing the expected input format, when invoked with "--help".

versionInformation

Returns nothing by default. You can return a string that is printed, when invoked with "--version".

bugTrackingAddress

Returns nothing by default. You can return a string describing the bug tracking address, when invoked with "--help".

canExtractAll

Returns false by default. Return a truthy value if your extractor supports the option "--extract-all".

canKeywords

Returns true by default. Return a false value if your extractor does not support the option "--keyword".

canFlags

Returns true by default. Return a false value if your extractor does not support the option "--flag".

needInputFiles

Returns true by default. Return a false value if your extractor does not support input from files. In this case you should implement readFromNonFiles().

programName

Return the name of the program for usage and help information. Defaults to just $0 but you can return another value here.

run

Runs the extractor once. The default implementation scans all input sources for translatable strings and collects them.

output

Print the output as a PO file to the specified output location.

extractFromNonFiles

This method is invoked after all input files have been processed. The default implementation does nothing. You may use the method for extracting strings from additional sources like a database.

resolveFilename FILENAME

Given an input filename FILENAME the method returns the absolute location of the file. The default implementation honors the option "-D, --directory".

defaultKeywords

Returns a reference to an emtpy array.

Subclasses may return a reference to an array with default keyword definitions for the specific language. The default keywords (actually just a subset for it) for the language C would look like this (expressed in JSON):

    [
        "gettext:1",
        "ngettext:1,2",
        "pgettext:1c,2",
        "npgettext:1c,2,3"
    ]
    

See above the description of the command-line option "--keyword" for more information about the meaning of these strings.

defaultFlags

Returns a reference to an emtpy array.

Subclasses may return a reference to an array with default flag specifications for the specific language. An example may look like this (expressed in JSON):

    [
        "gettextx:1:perl-brace-format",
        "ngettextx:1:perl-brace-format",
        "ngettextx:2:perl-brace-format",
    ]
    

We assume that "gettextx()" and "gettextx() are keywords for the language in question. The above default flag definition would mean that in all invocations of the function "gettextx()", the 1st argument would get the flag "perl-brace-format". In all invocations of "ngettextx()", the 1st and 2nd argument would get the flag "perl-brace-format".

You can prefix the format with "no-" which tells the GNU gettext tools that the particular never uses that format.

You can additionally prefix the format with "pass-" but this is ignored by Locale::XGettext. If you want to implemnt the GNU xgettext behavior for the "pass-" prefix, you have to implement it yourself in your extractor.

recodeEntry ENTRY

Gets invoked for every PO entry but after it has been promoted to a Locale::PO(3pm) object. The implementation of this method is likely to be changed in the future.

Do not use!

readPO FILENAME

Reads FILENAME as .po or .pot file. There is no reason why you should override or invoke this method.

po

Returns a list of PO entries represented by hash references. Do not use or override this method!

printLanguageSpecificUsage

Prints the help for language-specific options. Override it, if you are not happy with the formatting.

COPYRIGHT

SEE ALSO