LOCALE:...EXT.3PM(1)

📦
version 0.74 · 15 versions
, in alpine 3.23

🌸 LOCALE:…EXT.3PM — the Locale::Po4a::Text era 💅

okay bestie, so this is a Perl man page from the User Contributed Perl Documentation corner of the universe, and it's about Locale::Po4a::Text — a module that converts text documents from/to PO files. yes, both directions. it's giving bilingual icon behavior ✨

🎀 NAME 🎀

Locale::Po4a::Text — converts text documents from/to PO files. periodt.

💖 DESCRIPTION 💖

so the whole po4a (PO for anything) project has one goal: make translations easier — and honestly, even more interestingly, make maintaining translations easier — by using gettext tools on places nobody expected them, like documentation. lowkey genius 🧠✨

Locale::Po4a::Text is the module that helps you translate text documents into other [human] languages. yes, human — that's literally in the brackets, iykyk 🫶

the rules of the land:

  • paragraphs get split on empty lines (or on lines that contain only spaces or tabulations). that's the divider, bestie 🎀
  • if a paragraph contains a line starting with a space (or a tabulation), that paragraph will not be rewrapped. nope. it's staying exactly how it is 💅

✨ OPTIONS ACCEPTED BY THIS MODULE ✨

these are this module's very own particular options, and honestly? each one ate:

  • keyvalue — treat paragraphs that look like a colon-separated key-value pair as verbatim (with the no-wrap flag in the PO file). and what counts as a key-value pair string? a string like key: value — meaning it contains one or more non-colon and non-space characters, followed by a colon, followed by at least one non-space character before the end of the line. precise. iconic. 💅
  • nobullets — deactivates the detection of bullets. bye bye bullet detection 🫡

by default, when a bullet is detected, the bullet paragraph is not considered a verbatim paragraph (with the no-wrap flag in the PO file). instead, the corresponding paragraph gets rewrapped in the translation. so this flag is the "actually, don't" button 🙈

  • tabs=mode — specifies how tabulations shall be handled. mode can be any of these two cuties:
    • split — lines with tabulations introduce breaks in the current paragraph. tab = new paragraph energy 💀
    • verbatim — paragraphs containing tabulations will not be re-wrapped. hands off ✋

by default, tabulations are just considered as spaces. no drama 🌸

  • breaks=regex — a regular expression matching lines which introduce breaks. and heads up, the regex will be anchored, so the whole line must match. no partial matches, bestie 🎯
  • debianchangelog — handles the header and footer of released versions, which only contain non-translatable information. so we skip the boring bits 🌈
  • fortunes — handles the fortunes format, which separates fortunes with a line that consists in % or %%, and uses %% as the beginning of a comment. cute format, cute handling 🍓
  • markdown — handles some special markup in Markdown-formatted texts. markdown girlies rise 👑
  • yfm_keys (markdown-only) — comma-separated list of keys to process for translation in the YAML Front Matter section. all other keys are skipped. keys are matched with a case-sensitive match. if yfm_paths and yfm_keys are used together, values are included if they are matched by at least one of the options. array values are always translated, unless the yfm_skip_array option is provided 🎀
  • yfm_lenient (markdown only) — allows the YAML Front Matter parser to fail on malformated headers. particularly helpful when your file starts with a horizontal ruler instead of a YAML Front Matter, but you insist on using three dashes only for your ruler. we've all been there 😭
  • yfm_paths (markdown only) — comma-separated list of hash paths to process for extraction in the YAML Front Matter section, all other paths are skipped. paths are matched with a case-sensitive match. if yfm_paths and yfm_keys are used together, values are included if they are matched by at least one of the options. arrays values are always returned unless the yfm_skip_array option is provided 💜
  • yfm_paths — yes bestie, it's listed a second time in the source with no parenthetical. same option, same spelling, we're keeping it exactly as it appears. no cap 🫶
  • yfm_skip_array (markdown-only) — do not translate array values in the YAML Front Matter section. skip 'em 🦋
  • control[=field_list] — handles Debian's control files. and yes, you can hand it a comma-separated list of fields to be translated. customized translation, we love to see it 💖
  • neverwrap — prevents po4a from wrapping any lines. this means every content is handled verbatim, even simple paragraphs. truly the "no thoughts, just vibes, keep my line breaks" option 💀

🌈 STATUS OF THIS MODULE 🌈

tested successfully on simple text files and NEWS.Debian files. she passed the vibe check ✅✨

👑 AUTHORS 👑

  • Nicolas François <nicolas.francois@centraliens.net> — an actual legend 🫶
  • Copyright © 2005-2008 Nicolas FRANÇOIS <nicolas.francois@centraliens.net>.
  • Copyright © 2008-2009, 2018 Jonas Smedegaard <dr@jones.dk>.
  • Copyright © 2020 Martin Quinson <mquinson#debian.org>.

this program is free software; you may redistribute it and/or modify it under the terms of GPL v2.0 or later (see the COPYING file). free software rights, we stan 🎀

and that's the whole page, bestie 🥰 this fine piece of documentation is brought to you by perl v5.42.0, dated 2025-07-13, and filed under LOCALE:...EXT.3PM(1). go forth and translate literally everything 💅✨🌸

📦 where this page comes from