There is an ongoing outage on the primary CPAN mirror. It is possible to work around the issue by using MetaCPAN as a mirror.

 / 
Log-Report-Lexicon-1.14
River stage one • 1 direct dependent • 1 total dependent
/ Log::Report::Lexicon::POT

NAME

Log::Report::Lexicon::POT - manage PO files

INHERITANCE

Log::Report::Lexicon::POT
  is a Log::Report::Lexicon::Table

SYNOPSIS

# this is usually not for end-users, See ::Extract::PerlPPI
# using a PO table

my $pot = Log::Report::Lexicon::POT->read('po/nl.po', charset => 'utf-8')
   or die;

my $po = $pot->msgid('msgid');
my $po = $pot->msgid($msgid, $msgctxt);
print $pot->nrPlurals;
print $pot->msgstr('msgid', 3);
print $pot->msgstr($msgid, 3, $msgctxt);
$pot->write;  # update the file

# fill the table, by calling the next a lot
my $po  = Log::Report::Lexicon::PO->new(...);
$pot->add($po);

# creating a PO table
$pot->write('po/nl.po')
    or die;

DESCRIPTION

This module is reading, extending, and writing POT files. POT files are used to store translations in humanly readable format for most of existing translation frameworks, like GNU gettext and Perl's Maketext. If you only wish to access the translation, then you may use the much more efficient Log::Report::Lexicon::POTcompact.

The code is loosely based on Locale::PO, by Alan Schwartz. The coding style is a bit off the rest of Log::Report, and there was a need to sincere simplification. Each PO record will be represented by a Log::Report::Lexicon::PO.

Extends "DESCRIPTION" in Log::Report::Lexicon::Table.

METHODS

Extends "METHODS" in Log::Report::Lexicon::Table.

Constructors

Extends "Constructors" in Log::Report::Lexicon::Table.

$class->new(%options)

Create a new POT file. The initial header is generated for you, but it can be changed using the header() method.

-Option      --Default
 charset       'UTF-8'
 date          now
 filename      undef
 index         {}
 nr_plurals    2
 plural_alg    n!=1
 plural_forms  <constructed from nr_plurals and plural_alg>
 textdomain    <required>
 version       undef
charset => STRING

The charset to be used for the createed file. It is unwise to use anything else than 'UTF-8', but allowed. Before [1.09] this option was required.

date => STRING

Overrule the date which is included in the generated header.

filename => STRING

Specify an output filename. The name can also be specified when write() is called.

index => HASH

A set of translations (Log::Report::Lexicon::PO objects), with msgid as key.

nr_plurals => INTEGER

The number of translations each of the translation with plural form need to have.

plural_alg => EXPRESSION

The algorithm to be used to calculate which translated msgstr to use.

plural_forms => RULE

[0.992] When this option is used, it overrules nr_plurals and plural_alg. The RULE should be a full "Plural-Forms" field.

textdomain => STRING

The package name, used in the directory structure to store the PO files.

version => STRING
$class->read($filename, %options)

Read the POT information from $filename.

-Option --Default
 charset  <required>
charset => STRING

The character-set which is used for the file. You must specify this explicitly.

$obj->write( [$filename|$fh], %options )

When you pass an open $fh, you are yourself responsible that the correct character-encoding (binmode) is set. When the write followed a read() or the filename was explicitly set with filename(), then you may omit the first parameter.

-Option     --Default
 only_active  false
only_active => BOOLEAN

[1.02] Do not write records which do have a translation, but where the msgid has disappeared from the sources. By default, these records are commented out (marked with '#~') but left in the file.

Attributes

Extends "Attributes" in Log::Report::Lexicon::Table.

$obj->charset()

The character-set to be used for reading and writing. You do not need to be aware of Perl's internal encoding for the characters.

$obj->filename()

Returns the filename, as derived from read() or specified during initiation with new(filename).

$obj->index()

Returns a HASH of all defined PO objects, organized by msgid. Please try to avoid using this: use msgid() for lookup and add() for adding translations.

$obj->language()

Returns the language code, which is derived from the filename.

Managing PO's

Extends "Managing PO's" in Log::Report::Lexicon::Table.

$obj->keepReferencesTo($table)

Remove all references which are not found as key in the hash $table. Returns the number of references left.

$obj->removeReferencesTo($filename)

Remove all the references to the indicate $filename from all defined translations. Returns the number of refs left.

$obj->stats()

Returns a HASH with some statistics about this POT table.

$obj->updated( [$date] )

Replace the "PO-Revision-Date" with the specified $date, or the current moment.

Translation

Extends "Translation" in Log::Report::Lexicon::Table.

$obj->msgid( STRING, [$msgctxt] )

Lookup the Log::Report::Lexicon::PO with the STRING. If you want to add a new translation, use add(). Returns undef when not defined. Improves base, see "Translation" in Log::Report::Lexicon::Table

$obj->msgstr( $msgid, [$count, [$msgctxt]] )

Returns the translated string for $msgid. When $count is not specified or undef, the translation string related to "1" is returned. Improves base, see "Translation" in Log::Report::Lexicon::Table

Administration

Extends "Administration" in Log::Report::Lexicon::Table.

$obj->add($po)

Add the information from a $po into this POT. If the msgid of the $po is already known, that is an error. Improves base, see "Administration" in Log::Report::Lexicon::Table

$obj->header( [$field, [$content]] )

The translation of a blank MSGID is used to store a MIME header, which contains some meta-data. When only a $field is specified, that content is looked-up (case-insensitive) and returned. When a $content is specified, the knowledge will be stored. In latter case, the header structure may get created. When the $content is set to undef, the field will be removed. Improves base, see "Administration" in Log::Report::Lexicon::Table

$obj->nrPlurals()

Inherited, see "Administration" in Log::Report::Lexicon::Table

$obj->pluralIndex($count)

Inherited, see "Administration" in Log::Report::Lexicon::Table

$obj->setupPluralAlgorithm()

Inherited, see "Administration" in Log::Report::Lexicon::Table

$obj->translations( [$active] )

Returns a list with all defined Log::Report::Lexicon::PO objects. When the string $active is given as parameter, only objects which have references are returned. Improves base, see "Administration" in Log::Report::Lexicon::Table

DIAGNOSTICS

Error: cannot detect charset in $fn

Cast by read()

Fault: cannot read from file $fn (unknown charset): $!

Cast by read()

Fault: cannot read in $cs from file $fn: $!

Cast by read()

Fault: cannot write to file $fn with $layers: $!

Cast by write()

Fault: failed reading from file $fn: $!

Cast by read()

Error: invalid plural-form algorithm '$alg'

Cast by setupPluralAlgorithm()

Error: no filename or file-handle specified for PO

When a PO file is written, then a filename or file-handle must be specified explicitly, or set beforehand using the filename() method, or known because the write follows a read() of the file. Cast by write()

Error: no filename or file-handle specified for PO

Cast by write()

Error: no header defined in POT for file $fn

Cast by header()

Error: textdomain parameter is required

Cast by new()

Error: the only acceptable parameter is 'ACTIVE', not '$p'

Cast by translations()

Error: there is no Plural-Forms field in the header, but needed

Cast by pluralIndex()

Error: translation already exists for '$msgid' with '$ctxt

Cast by add()

Error: unsupported charset $charset in $fn

Cast by read()

SEE ALSO

This module is part of Log-Report-Lexicon version 1.14, built on September 08, 2025. Website: http://perl.overmeer.net/CPAN/

LICENSE

For contributors see file ChangeLog.

This software is copyright (c) 2007-2025 by Mark Overmeer.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.