NAME¶

Locale::Po4a::TransTractor - generic trans(lator ex)tractor.

DESCRIPTION¶

The po4a (PO for anything) project goal is to ease translations (and more interestingly, the maintenance of translations) using gettext tools on areas where they were not expected like documentation.

This class is the ancestor of every po4a parser used to parse a document, to search translatable strings, to extract them to a PO file and to replace them by their translation in the output document.

More formally, it takes the following arguments as input:

• a document to translate;
• a PO file containing the translations to use.

As output, it produces:

• another PO file, resulting of the extraction of translatable strings from the input document;
• a translated document, with the same structure than the one in input, but with all translatable strings replaced with the translations found in the PO file provided in input.

Here is a graphical representation of this:

   Input document --\                             /---> Output document
                     \                           /       (translated)
                      +-> parse() function -----+
                     /                           \
   Input PO --------/                             \---> Output PO
                                                         (extracted)

FUNCTIONS YOUR PARSER SHOULD OVERRIDE¶

parse()

This is where all the work takes place: the parsing of input documents, the generation of output, and the extraction of the translatable strings. This is pretty simple using the provided functions presented in the section INTERNAL FUNCTIONS below. See also the SYNOPSIS, which presents an example.

This function is called by the process() function below, but if you choose to use the new() function, and to add content manually to your document, you will have to call this function yourself.

docheader()

This function returns the header we should add to the produced document, quoted properly to be a comment in the target language. See the section Educating developers about translations, from po4a(7), for what it is good for.

SYNOPSIS¶

The following example parses a list of paragraphs beginning with "<p>". For the sake of simplicity, we assume that the document is well formatted, i.e. that '<p>' tags are the only tags present, and that this tag is at the very beginning of each paragraph.

 sub parse {
   my $self = shift;
   PARAGRAPH: while (1) {
       my ($paragraph,$pararef)=("","");
       my $first=1;
       my ($line,$lref)=$self->shiftline();
       while (defined($line)) {
           if ($line =~ m/<p>/ && !$first--; ) {
               # Not the first time we see <p>.
               # Reput the current line in input,
               #  and put the built paragraph to output
               $self->unshiftline($line,$lref);
               # Now that the document is formed, translate it:
               #   - Remove the leading tag
               $paragraph =~ s/^<p>//s;
               #   - push to output the leading tag (untranslated) and the
               #     rest of the paragraph (translated)
               $self->pushline(  "<p>"
                               . $self->translate($paragraph,$pararef)
                               );
               next PARAGRAPH;
           } else {
               # Append to the paragraph
               $paragraph .= $line;
               $pararef = $lref unless(length($pararef));
           }
           # Reinit the loop
           ($line,$lref)=$self->shiftline();
       }
       # Did not get a defined line? End of input file.
       return;
   }
 }

Once you've implemented the parse function, you can use your document class, using the public interface presented in the next section.

PUBLIC INTERFACE for scripts using your parser¶

INTERNAL FUNCTIONS used to write derivative parsers¶

 * Perl shift returns the first array item and drop it from the array.
 * Perl unshift prepends an item to the array as the first array item.
 * Perl pop returns the last array item and drop it from the array.
 * Perl push appends an item to the array as the last array item.

  $self->translate("string","ref","type",
                   'wrap' => 1);

FUTURE DIRECTIONS¶

One shortcoming of the current TransTractor is that it can't handle translated document containing all languages, like debconf templates, or .desktop files.

To address this problem, the only interface changes needed are:

• take a hash as po_in_name (a list per language)
• add an argument to translate to indicate the target language
• make a pushline_all function, which would make pushline of its content for all languages, using a map-like syntax:

      $self->pushline_all({ "Description[".$langcode."]=".
                            $self->translate($line,$ref,$langcode)
                          });
      

Will see if it's enough ;)

AUTHORS¶

 Denis Barbier <barbier@linuxfr.org>
 Martin Quinson (mquinson#debian.org)
 Jordi Vilalta <jvprat@gmail.com>