NAME

Log::Report::Lexicon::PO - one translation definition

SYNOPSIS

DESCRIPTION

This module is administering one translation object. Sets of PO records are kept in a POT file, implemented in Log::Report::Lexicon::POT.

METHODS

Constructors

$class->new(%options)

-Option      --Default
 automatic     ""
 comment       []
 format        []
 fuzzy         false
 msgctxt       undef
 msgid         <required>
 msgid_plural  undef
 msgstr        "" or []
 references    []

automatic => PARAGRAPH

Automatically added comments. See addAutomatic().

comment => PARAGRAPH

Translator added comments. See addComment().

format => ARRAY|HASH

See format(). Either an ARRAY with PAIRS or a HASH with that same information.

fuzzy => BOOLEAN

The string is not yet translated, some smart guesses may have been made. See fuzzy().

msgctxt => STRING

Context string: text around the msgid itself.

msgid => STRING

msgid_plural => STRING

msgstr => STRING|ARRAY-OF-STRING

The translations for the msgid. When msgid_plural is defined, then an ARRAY must be provided.

references => STRING|ARRAY-OF-LOCATIONS

The STRING is a blank separated list of LOCATIONS. LOCATIONs are of the form filename:linenumber, for instance lib/Foo.pm:42 See addReferences()

Attributes

$obj->addAutomatic(LIST|ARRAY|STRING)

Add multiple lines to the translator's comment block. Returns an empty string if there are no comments.

$obj->addComment(LIST|ARRAY|STRING)

Add multiple lines to the translator's comment block. Returns an empty string if there are no comments.

$obj->addFlags(STRING)

Parse a "flags" line.

$obj->addReferences(STRING|LIST|ARRAY)

The STRING is a blank separated list of LOCATIONS. The LIST and ARRAY contain separate LOCATIONs. A LOCATION is of the form filename:linenumber. Returns the internal HASH with references.

$obj->automatic( [LIST|ARRAY|STRING] )

Returns a STRING which contains the cleaned paragraph of automatically added comments. If an argument is specified, it will replace the current comment.

$obj->comment( [LIST|ARRAY|STRING] )

Returns a STRING which contains the cleaned paragraph of translator's comment. If an argument is specified, it will replace the current comment.

$obj->format( $language | <PAIRS|ARRAY|HASH> )

When one $language is specified, it looks whether a "language-format" or "no-language-format" is present in the line of FLAGS. This will return 1 (true) in the first case, 0 (false) in the second case. It will return undef (also false) in case that both are not present.

You can also specify PAIRS: the key is a language name, and the value is either 0, 1, or undef.

example: use of format()

# getters
if($po->format('c')) ...
unless($po->format('perl-brace')) ...
if(defined $po->format('java')) ...

# setters
$po->format(java => 1);       # results in 'java-format'
$po->format(java => 0);       # results in 'no-java-format'
$po->format(java => undef);   # results in ''

$obj->fuzzy( [BOOLEAN] )

Returns whether the translation needs human inspection.

$obj->isActive()

Returns whether the translation has any references, or is the header.

$obj->keepReferencesTo($table)

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

$obj->msgctxt()

Returns the message context, if provided.

$obj->msgid()

Returns the actual msgid, which cannot be undef.

$obj->msgstr( [$index, [STRING]] )

With a STRING, a new translation will be set. Without STRING, a lookup will take place. When no plural is defined, the $index is ignored.

$obj->plural( [STRING] )

Returns the actual msgid_plural, which can be undef.

$obj->references( [STRING|LIST|ARRAY] )

Returns an unsorted list of LOCATIONS. When options are specified, then those will be used to replace all currently defined references. Returns the unsorted LIST of references.

$obj->removeReferencesTo($filename)

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

Parsing

$class->fromText( STRING, [$where] )

Parse the STRING into a new PO object. The $where string should explain the location of the STRING, to be used in error messages.

$obj->toString(%options)

Format the object into a multi-lined string.

-Option    --Default
 nr_plurals  undef

nr_plurals => INTEGER

If the number of plurals is specified, then the plural translation list can be checked for the correct length. Otherwise, no smart behavior is attempted.

$obj->useless()

[1.02] The message-id has no references anymore and no translations.

DIAGNOSTICS

Warning: do not understand command '$cmd' at $where

Cast by fromText()

Warning: do not understand line at $where:\n $line

Cast by fromText()

Error: no msgid defined for PO

Cast by new()

Warning: no msgid in block $where

Cast by fromText()

Warning: no plurals for '$msgid'

Cast by toString()

Warning: quoted line is not a continuation at $where

Cast by fromText()

Warning: too many plurals for '$msgid'

Cast by toString()

Warning: unknown comment type '$cmd' at $where

Cast by fromText()

Warning: unknown flag $flag ignored

Cast by addFlags()

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.