Customizing extraction

You can customize the string extraction process using HTML comments in your Markdown files.

Tip

If you want to specify next commands with other names, take a look at the argument md2po --command-alias of md2po CLI or the optional parameter command_aliases of the programmatic APIs.

Disabling extraction

You can disable and enable the extraction of certain strings using the next HTML commments:

• <!-- mdpo-disable-next-block --> or <!-- mdpo-disable-next-line -->: Do not extract the next Markdown block.

• <!-- mdpo-disable -->: Do not extract the content after it.

• <!-- mdpo-enable -->: Extract the content after it.

• <!-- mdpo-enable-next-block --> or <!-- mdpo-enable-next-line --> Extract the next Markdown block.

Example:

>>> from mdpo.md2po import markdown_to_pofile

>>> md_content = '''# Header
...
... This will be included
...
... <!-- mdpo-disable-next-line -->
... This will be ignored.
...
... This will be included also.
...
... <!-- mdpo-disable -->
... This paragraph compounded by multiples
... lines will be ignored.
...
... # md2po remains disabled for this header
...
... <!-- mdpo-enable-next-line -->
... This line will be included because we have enabled it individually.
...
... <!-- mdpo-enable -->
... All content from here will be extracted...
... '''
>>>
>>> pofile = markdown_to_pofile(md_content)
>>> print(pofile)
#
msgid ""
msgstr ""

msgid "This will be included."
msgstr ""

msgid "This will be included also."
msgstr ""

msgid "This line will be included because we have enabled it individually."
msgstr ""

msgid "All content from here will be extracted..."
msgstr ""

Including comments for translators

You can include comments for translators using the next line in the line before the message:

• <!-- mdpo-translator Comment that you want to include -->

Example:

>>> content = '''<!-- mdpo-translator This is a comment for a translator -->
... Some text that needs to be clarified
...
... Some text without comment
... '''

>>> pofile = markdown_to_pofile(content)
>>> print(pofile)
#
msgid ""
msgstr ""

#. This is a comment for a translator
msgid "Some text that needs to be clarified"
msgstr ""

msgid "Some text without comment"
msgstr ""

Contextual markers

You can specify contexts for msgids using next command:

• <!-- mdpo-context Context for your string -->

Example:

>>> content = '''<!-- mdpo-context month -->
... May
...
... <!-- mdpo-context might -->
... May
... '''
>>>
>>> pofile = markdown_to_pofile(content)
>>> print(pofile)
#
msgid ""
msgstr ""

msgctxt "month"
msgid "May"
msgstr ""

msgctxt "might"
msgid "May"
msgstr ""

Code blocks extraction

You can enable and disable code blocks extraction inside the PO file using the next commands:

• <!-- mdpo-include-codeblocks -->: Include all codeblocks placed after this command (same behaviour as passing the argument md2po --include-codeblocks or include_codeblocks=True if you are using the programmatic interface).

• <!-- mdpo-disable-codeblocks -->: Does not include codeblocks placed after this command.

• <!-- mdpo-include-codeblock -->: Include next codeblock placed after this command.

• <!-- mdpo-disable-codeblock -->: Does not include next codeblock placed after this command.

Indented code block example:

>>> content = '''
... <!-- mdpo-include-codeblock -->
...
...     var hello = "world";
...     var hola = "mundo";
...
... Another paragraph.
... '''
>>>
>>> pofile = markdown_to_pofile(content)
>>> print(pofile)
msgid ""
msgstr ""

msgid ""
"var hello = \"world\";\n"
"var hola = \"mundo\";\n"
msgstr ""

msgid "Another paragraph."
msgstr ""

Fenced code block example:

>>> content = '''
... <!-- mdpo-include-codeblock -->
... ```javascript
... var hello = "world";
... var hola = "mundo";
... ```
... '''
>>>
>>> pofile = markdown_to_pofile(content)
>>> print(pofile)
msgid ""
msgstr ""

msgid ""
"var hello = \"world\";\n"
"var hola = \"mundo\";\n"
msgstr ""

Extracting comments itself

You can extract comments inside the PO file, but don’t ask me why you need this:

• <!-- mdpo-include Message that you want to include -->

Example:

>>> content = '''<!-- mdpo-include This message will be included -->
... Some text
... '''

>>> pofile = markdown_to_pofile(content)
>>> print(pofile)
#
msgid ""
msgstr ""

msgid "This message will be included"
msgstr ""

msgid "Some text"
msgstr ""

This command can be used along with mdpo-translator:

>>> content = '''<!-- mdpo-translator Comment for translator in comment -->
... <!-- mdpo-include This comment must be included -->
... Some text that needs to be clarified
... '''

>>> pofile = markdown_to_pofile(content)
>>> print(pofile)
#
msgid ""
msgstr ""

#. Comment for translator in comment
msgid "This comment must be included"
msgstr ""

And with mdpo-context, combining both:

>>> content = '''<!-- mdpo-context Some context for the included -->
... <!-- mdpo-translator Comment for translator in comment -->
... <!-- mdpo-include This comment must be included -->
... Some text that needs to be clarified
... '''

>>> pofile = markdown_to_pofile(content)
>>> print(pofile)
#
msgid ""
msgstr ""

#. Comment for translator in comment
msgctxt "Some context for the included"
msgid "This comment must be included"
msgstr ""