--- name: "Log::Report::Lexicon::POT" section: "3pm" platform: "linux" package: "liblog-report-lexicon-perl" version: "1.12-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Log::Report::Lexicon::POT" --- # Log::Report::Lexicon::POT(3pm) manage PO files ## 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. - Log::Report::Lexicon::POT-\>**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 textdomain 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 - Log::Report::Lexicon::POT-\>**read**($filename, %options) Read the POT information from `$filename`. ``` -Option --Default charset ``` - 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. - $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. *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. - $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. - $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. ## DIAGNOSTICS - 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. - Error: only acceptable parameter is 'ACTIVE' - Error: textdomain parameter is required ## SEE ALSO This module is part of Log-Report-Lexicon distribution version 1.12, built on April 18, 2025. Website: *http://perl.overmeer.net/CPAN/* ## LICENSE Copyrights 2007-2025 by \[Mark Overmeer \\]. For other contributors see ChangeLog. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See *http://dev.perl.org/licenses/*