---
name: "Log::Report::Lexicon::PO"
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::PO"
---

# Log::Report::Lexicon::PO(3pm)

one translation definition

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

- Log::Report::Lexicon::PO-\>**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

- Log::Report::Lexicon::PO-\>**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.

## 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 \<markov@cpan.org\>\]. 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/*