LOCALE::PO4A::COMMONMARK.3PM

Section: User Contributed Perl Documentation (1)
Updated: 2026-03-29
Index Return to Main Contents

NAME

Locale::Po4a::CommonMark - convert CommonMark documents from/to PO files.

SYNOPSIS

  [type:CommonMark] /path/to/master.md $lang:/path/to/translation.$lang.md

DESCRIPTION

The po4a (PO for anything) project goal is to ease translations (and more interestingly, the maintenance of translations) using gettext tools on areas where they were not expected like documentation.

Locale::Po4a::CommonMark is a module to help the translation of documentation in the CommonMark <https://commonmark.org/>.

In some cases, this format module can be used in place of the Locale::Po4a::Text module with the "markdown" option enabled. However, please note that CommonMark may not provide certain syntax features you need, such as tables or footnotes, and this module does not support them either.

CONFIGURATION

Enabling the "debug" option causes the program to display libcmark version information, which makes diagnosing issues easier by providing more detailed context.

This module doesn't support the "width" option for wrapping paragraphs in the output files, unlike the Locale::Po4a::Text module. This limitation is intentional; refer to the comment in the source code.

Some configuration options can be passed using "option":

"neverwrap": Prevent po4a from wrapping any lines. This means that every content is handled verbatim, even simple paragraphs. Disabled by default. Internally, translates softbreak nodes in block nodes to spaces. See also the equivalent option by the Locale::Po4a::Text module.
"skip_code_block": Code blocks are excluded from translation. This option is disabled by default.
"yaml_metadata": Enable the YAML metadata (YAML front matter) feature. Disabled by default. It follows the lcmark's YAML Metadata <https://github.com/jgm/lcmark/blob/debdae3235cf97312aa5d102bdcf7db062f4782f/README.md#yaml-metadata> feature. If this option is enabled, the "yfm_keys", "yfm_lenient", "yfm_paths", and "yfm_skip_array" options become available. Please refer to the Locale::Po4a::Text.
"unsafe": Enable the unsafe option. Disabled by default, so potentially dangerous links are scrubbed. Please be aware when you use this option and see also the Security section <https://github.com/commonmark/cmark/tree/7c3877921c69fc02f2ab076a71efea6899b481c0?tab=readme-ov-file#security> in the cmark documentation.

STATUS OF THIS MODULE

This module is in an early stage of development. It has been tested successfully against the CommonMark specification document, as far as we know, but it may not handle more complex real-world documents yet. In rare cases, libcmark may diverge from the specification or something; if you encounter such a discrepancy, please report it to the appropriate projects (for example, cmark or the Perl CommonMark module).

CAVEATS

Link normalization: There may be initially surprising normalization steps both when generating PO files and when producing translated documents. One effect is that link reference definitions are removed and all link references are expanded into inline links. At the moment there is no way to prevent this.
Manipulating the abstract syntax tree might make it possible to retain the original document structure, but that would require additional (seemingly hard) work. Please report if there is a strong need for such functionality.
The CommonMark specification: When translating the CommonMark specification file spec.txt, take care with character escaping in link markups. If you pass the file unchanged, extra normalization or escaping may occur. For example, a link-like token such as "[foo]" (which is a reference link and with no link destination) can be converted to "\[foo\]" in the PO files (and the generated translation files).
This happens because the source lacks explicit link definitions and the parser generates them on the fly. Please see the tools/make_spec.lua of the CommonMark specification repository for implementation details.

AUTHORS

 gemmaro <gemmaro.dev@gmail.com>

COPYRIGHT AND LICENSE

 Copyright © 2026 gemmaro.

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

This document was created by using the manual pages.
Time: 22:11:58 GMT, March 29, 2026