NAME¶

Locale::Po4a::SimplePod - convert POD data from/to PO files, with Pod::Simple

SYNOPSIS¶

  [po4a_paths] /path/to/pot $lang:/path/to/po
  [type:SimplePod] /path/to/source.pod $lang:/path/to/localized.pod

or

  [po4a_paths] /path/to/pot $lang:/path/to/po
  [po4a_alias:pod] SimplePod
  [type:pod] /path/to/source.pod $lang:/path/to/localized.pod

DESCRIPTION¶

This is a module to help the translation of documentation in the POD format (the preferred language for documenting Perl) into other human languages.

The main differences between the current Pod format and the SimplePod format are as follows:

• SimplePod format never includes additional newlines in messages to be translated. The current Pod format, however, may contain extra newlines, particularly in verbatim message entries.
• Paragraphs may be rendered with line wrapping. The Pod::Parser module might apply special handling for line wrapping, making it difficult to replicate with Pod::Simple. However, Pod::Simple appears to produce a more natural output.
• In SimplePod, the "=for" message (e.g., "=for comment text") does not include a format name (such as "comment"), so the message consists solely of text. In contrast, the current Pod format retains the format name, resulting in a message like "comment text". The former behavior is considered more comfortable for translators.
• Entries like the one below, which denote "=end comment", are no longer present as seen in the current Pod module. Since these are not translatable messages, their absence is an improvement.

    #. type: =end
    #: sample.pod:10
    msgid "comment"
    msgstr ""
      

• Text blocks whose POD format validity is uncertain are now treated as "no-wrap". This applies, for example, to the content within a "=begin html" block. In the Pod module, these were not treated as "no-wrap", which sometimes resulted in line wrapping.
• The "=begin" parameter section is no longer subject to translation. In the current Pod module, it is included. If there is a demand to include it in translation, please report it.

STATUS OF THIS MODULE¶

This module is still newly developed, so it is less stable than Locale::Po4a::Pod. It continues to evolve, and there is room for further refinement. Its behavior might change over time, and additional options may be introduced to better optimize the translation experience for users. Feedback and use cases from real-world applications will play a key role in guiding its future development.

The code is fully covered by our test suite, and we're not aware of any existing bugs. However, as of 2025, it hasn't been battle-tested in real-world translation workflows by external projects. That said, we believe the module is ready for production use, even if some bugs may inevitably be discovered as it gains wider adoption.

This module is intended to replace the current Locale::Po4a::Pod module. The reason is that Pod::Parser, which is used by the current Locale::Po4a::Pod, is now deprecated, and it is recommended to use Pod::Simple instead. See also GitHub issue #256 "Consider migrating away from deprecated "Pod::Parser"" <https://github.com/mquinson/po4a/issues/256>.

SEE ALSO¶

Pod::Simple, Locale::Po4a::Pod, Locale::Po4a::TransTractor, po4a(7), Locale::Po4a::SimplePod::Parser.

AUTHORS¶

  gemmaro <gemmaro.dev@gmail.com>

COPYRIGHT AND LICENSE¶

  Copyright (C) 2025 gemmaro <gemmaro.dev@gmail.com>.

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).