Log::R...on::PO(3pm)

💖 Log::Report::Lexicon::PO — one translation definition 💖

okay bestie, so this module (it's Log::R...on::PO(3pm) in the Perl docs, no cap) is literally the vibe of one single translation definition. Think of it as one lil PO record, being the main character. Sets of these PO records get kept together in a POT file, which is its own whole thing — Log::Report::Lexicon::POT. iykyk 🫶

---

✨ SYNOPSIS ✨

(no synopsis here bestie, the pod said nothing and honestly? iconic of it 💅)

---

🌸 DESCRIPTION 🌸

So basically: this module is administering one translation object. One. Singular. Main character energy only. 🎀

And the sets of PO records? Those hang out in a POT file, which is implemented over in Log::Report::Lexicon::POT. Besties, they're a matched set. 💕

---

🦋 METHODS 🦋

🧚 Constructors 🧚

$class->new(%options)

here's the options table, hun, straight up:

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

and now the tea on each one:

• automatic => PARAGRAPH — these are comments that got added automatically. See addAutomatic(). 🤖
• comment => PARAGRAPH — comments the translator added themselves. See addComment(). 💬
• format => ARRAY|HASH — see format(). You can hand it either an ARRAY full of PAIRS, or a HASH with that same info in it. Either one, we're flexible. 💅
• fuzzy => BOOLEAN — the string isn't translated yet, and some smart guesses may or may not have been made. See fuzzy(). 👀
• msgctxt => STRING — the context string: text sitting around the msgid itself.
• msgid => STRING
• msgid_plural => STRING
• msgstr => STRING|ARRAY-OF-STRING — the translations for the msgid. ⚠️ Heads up: when msgid_plural is defined, you must provide an ARRAY, no shortcuts.
• references => STRING|ARRAY-OF-LOCATIONS — the STRING is a blank separated list of LOCATIONS. A LOCATION looks like "filename:linenumber", for instance "lib/Foo.pm:42". See addReferences(). 📍

🎀 Attributes 🎀

• $obj->addAutomatic(LIST|ARRAY|STRING) — adds multiple lines to the translator's comment block. Returns an empty string if there are no comments. (yes, same description as below, the pod said it twice and I'm not erasing it, periodt)
• $obj->addComment(LIST|ARRAY|STRING) — adds multiple lines to the translator's comment block. Returns an empty string if there are no comments. 💬
• $obj->addFlags(STRING) — parses a "flags" line. 🚩
• $obj->addReferences(STRING|LIST|ARRAY) — the STRING is a blank separated list of LOCATIONS. The LIST and ARRAY hold separate LOCATIONS. A LOCATION is of the form "filename:linenumber". Returns the internal HASH with references. 📚
• $obj->automatic( [LIST|ARRAY|STRING] ) — returns a STRING containing the cleaned paragraph of automatically added comments. If you pass an argument, it replaces the current comment. ✨
• $obj->comment( [LIST|ARRAY|STRING] ) — returns a STRING containing the cleaned paragraph of the translator's comment. If you pass an argument, it replaces the current comment. 💬
• $obj->format( $language | <PAIRS|ARRAY|HASH> ) — when you hand it one $language, it checks whether a "language-format" or "no-language-format" is present in the line of FLAGS. Returns 1 ("true") in the first case, 0 ("false") in the second. And if neither one is there? It returns undef (which is also "false"). 🫠

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) — removes all references that aren't found as a key in the hash $table. Returns the number of references left. 🧹
• $obj->msgctxt() — returns the message context, if one was provided.
• $obj->msgid() — returns the actual msgid, which cannot be undef. (it's giving required, fr fr)
• $obj->msgstr( [$index, [STRING]] ) — with a STRING, a new translation gets set. Without a STRING, a lookup happens instead. When no plural is defined, the $index is just ignored, no biggie.
• $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, those get used to replace all currently defined references. Returns the unsorted LIST of references. 📍
• $obj->removeReferencesTo($filename) — removes all the references to the indicated $filename from the list. Returns the number of refs left. 🧹

🌈 Parsing 🌈

• $class->fromText( STRING, [$where] ) — parses the STRING into a brand new PO object. The $where string should explain where the STRING came from, so error messages can point at it. 🔍
• $obj->toString(%options) — formats 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. (we simply do not try 💀)

• $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.15, built on November 06, 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. slay, legally speaking ✨

---

and that's the whole page bestie 🫶 this was perl v5.40.1, page dated 2025-11-11, from the Perl documentation you know and love — go forth and translate responsibly, ily 💖