LOCALE:...TOR.3PM(1)

📦

version 0.74 · 15 versions

💅 NAME 💅

okay bestie, welcome to the LOCALE:...TOR.3PM(1) page from User Contributed Perl Documentation. the main character here is Locale::Po4a::TransTractor — the generic trans(lator ex)tractor. yes, that is literally the name. no cap. 💖

✨ DESCRIPTION ✨

the whole po4a (PO for anything) project is obsessed with one goal: making translations easier — and even more interestingly, keeping those translations maintained — by using gettext tools on places where people did not expect them, like documentation. it’s giving “gettext but make it everywhere” energy. 🦋

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. mother of parsers, honestly. 👑

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. literally the main character function. 💅

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 🌈

🎀 Constructor 🎀

🌟 `process(%)` 🌟

This function can do all you need to do with a po4a document in one invocation. Its arguments must be packed as a hash. ACTIONS:

Reads all the PO files specified in po_in_name
Reads all original documents specified in file_in_name
Parses the document
Reads and applies all the addenda specified
Writes the translated document to file_out_name (if given)
Writes the extracted PO file to po_out_name (if given)

ARGUMENTS, beside the ones accepted by new() (with expected type):

file_in_name (@) — List of filenames where we should read the input document.
file_in_charset ($) — Charset used in the input document (if it isn’t specified, use UTF-8).
file_out_name ($) — Filename where we should write the output document.
file_out_charset ($) — Charset used in the output document (if it isn’t specified, use UTF-8).
po_in_name (@) — List of filenames where we should read the input PO files from, containing the translation which will be used to translate the document.
po_out_name ($) — Filename where we should write the output PO file, containing the strings extracted from the input document.
addendum (@) — List of filenames where we should read the addenda from.
addendum_charset ($) — Charset for the addenda.

🌟 `new(%)` 🌟

Create a new po4a document. Accepted options (in the hash passed as a parameter):

verbose ($) — Sets the verbosity.
debug ($) — Sets the debugging.
wrapcol ($) — The column at which we should wrap text in output document (default: 76).

The negative value means not to wrap lines at all.

Also it accepts next options for underlying Po-files: porefs, copyright-holder, msgid-bugs-address, package-name, package-version, wrap-po.

📂 Manipulating document files 📂

`read($$$)`

Add another input document data at the end of the existing array "@{$self->{TT}{doc_in}}".

This function takes two mandatory arguments and an optional one.

The filename to read on disk;
The name to use as filename when building the reference in the PO file;
The charset to use to read that file (UTF-8 by default)

This array "@{$self->{TT}{doc_in}}" holds this input document data as an array of strings with alternating meanings.

The string $textline holding each line of the input text data.
The string "$filename:$linenum" holding its location and called as “reference” (linenum starts with 1).

Please note that it does not parse anything. You should use the parse() function when you’re done with packing input files into the document.

`write($)`

Write the translated document to the given filename.

This translated document data are provided by:

"$self->docheader()" holding the header text for the plugin, and
"@{$self->{TT}{doc_out}}" holding each line of the main translated text in the array.

💌 Manipulating PO files 💌

`readpo($)`

Add the content of a file (which name is passed as argument) to the existing input PO. The old content is not discarded.

`writepo($)`

Write the extracted PO file to the given filename.

`stats()`

Returns some statistics about the translation done so far. Please note that it’s not the same statistics than the one printed by msgfmt --statistic. Here, it’s stats about recent usage of the PO file, while msgfmt reports the status of the file. It is a wrapper to the Locale::Po4a::Po::stats_get function applied to the input PO file. Example of use:

               [normal use of the po4a document...]

               ($percent,$hit,$queries) = $document->stats();
               print "We found translations for $percent\%  ($hit from $queries) of strings.\n";

🧩 Manipulating addenda 🧩

`addendum($)`

Please refer to po4a(7) for more information on what addenda are, and how translators should write them. To apply an addendum to the translated document, simply pass its filename to this function and you are done ;)

This function returns a non-null integer on error.

💖 INTERNAL FUNCTIONS used to write derivative parsers 💖

📥 Getting input, providing output 📤

Okay so bestie, there are four functions that get input and return output, and they're lowkey cousins of Perl's shift/unshift and push/pop:

Perl shift returns the first array item and drops 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 drops it from the array.
Perl push appends an item to the array as the last array item.

The first pair is about input, and the second pair is about output. Mnemonic time: for input you care about the first line, which is what shift gives you; for output you wanna add your result at the end, like push does. Slay. ✨

🌸 `shiftline()`

This function returns the first line to be parsed and its corresponding reference (packed as an array) from the array "@{$self->{TT}{doc_in}}", and drops those first 2 array items. Here, the reference is provided by a string "$filename:$linenum".

🦋 `unshiftline($$)`

Unshifts the last shifted line of the input document and its corresponding reference back to the head of "{$self->{TT}{doc_in}}".

🎀 `pushline($)`

Push a new line to the end of "{$self->{TT}{doc_out}}".

⭐ `popline()`

Pop the last pushed line from the end of "{$self->{TT}{doc_out}}".

🏷️ Marking strings as translatable 🏷️

One function handles the text that should be translated. Iconic behavior, honestly.

💅 `translate($$$)`

Mandatory arguments:

A string to translate
The reference of this string (i.e. position in inputfile)
The type of this string (i.e. the textual description of its structural role; used in Locale::Po4a::Po::gettextization(); see also po4a(7), section Gettextization: how does it work?)

This function can also take some extra arguments. They must be organized as a hash. For example:

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

wrap — boolean indicating whether we can consider that whitespaces in string are not important. If yes, the function canonizes the string before looking for a translation or extracting it, and wraps the translation.
wrapcol — the column at which we should wrap (default: the value of wrapcol specified during creation of the TransTractor or 76). The negative value will be substracted from the default.
comment — an extra comment to add to the entry.

Actions:

Pushes the string, reference and type to po_out.
Returns the translation of the string (as found in po_in) so that the parser can build the doc_out.
Handles the charsets to recode the strings before sending them to po_out and before returning the translations.

🧚 Misc functions 🧚

🔥 `verbose()`

Returns if the verbose option was passed during the creation of the TransTractor.

💀 `debug()`

Returns if the debug option was passed during the creation of the TransTractor.

🌈 `get_in_charset()`

This function return the charset that was provided as master charset.

👑 `get_out_charset()`

This function will return the charset that should be used in the output document (usually useful to substitute the input document's detected charset where it has been found).

It will use the output charset specified in the command line. If it wasn't specified, it will use the input PO's charset, and if the input PO has the default "CHARSET", it will return the input document's charset, so that no encoding is performed.

🔮 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>

✨ This page came from the perl v5.42.0 docs and is dated 2025-07-13 — that's the source/version and date, served cute, periodt. 💅💖

📦 where this page comes from

alpine 3.23: po4a-doc 0.74-r0 · GPL-2.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms

LOCALE:...TOR.3PM(1)

💅 NAME 💅

✨ DESCRIPTION ✨

🛠️ FUNCTIONS YOUR PARSER SHOULD OVERRIDE 🛠️

🧚 parse()

🧚 docheader()

🌸 SYNOPSIS 🌸

🌈 PUBLIC INTERFACE for scripts using your parser 🌈

🎀 Constructor 🎀

🌟 process(%) 🌟

🌟 new(%) 🌟

📂 Manipulating document files 📂

read($$$)

write($)

💌 Manipulating PO files 💌

readpo($)

writepo($)

stats()