Command line interfaces

mdpo installation includes four command line interfaces:

  • md2po is used to dump strings from Markdown files into PO files as msgids.

  • po2md is used to produce a translated Markdown file from a source Markdown file and a PO file with extracted msgids and translated msgstrs.

  • md2po2md is a convenient wrapper for md2po and po2md.

  • mdpo2html is used to produce a translated HTML file from a source HTML file produced from Markdown file using a Markdown-to-HTML converter, and a PO file of reference for strings.

md2po

Utility like xgettext to extract Markdown contents dumping them inside PO files.

md2po [-h] [-v] [-q] [-i PATH] [-p OUTPUT_PO_FILEPATH] [-s]
      [--mo-filepath OUTPUT_MO_FILEPATH] [--plaintext] [--wrapwidth N/inf] [-m] [-r]
      [--no-location] [-x EXTENSION] [--md-encoding ENCODING] [--po-encoding ENCODING] [-a]
      [-c] [--ignore-msgids IGNORE_MSGIDS] [-d Key:Value]
      [--command-alias CUSTOM-COMMAND:MDPO-COMMAND]
      [-e event_name: path/to/file.py::function_name] [-D] [--check] [--no-obsolete]
      [--no-fuzzy] [--no-empty-msgstr]
      [GLOBS_FILES_OR_CONTENT ...]

md2po positional arguments

  • GLOBS_FILES_OR_CONTENT - Globs to markdown input files, paths to files or Markdown content. If not provided, will be read from STDIN. (default: None)

md2po options

  • -h, --help - Show this help message and exit.

  • -v, --version - Show program version number and exit.

  • -q, --quiet - Do not print output to STDOUT.

  • -i PATH, --ignore PATH - Path to a file to ignore. This argument can be passed multiple times. (default: [])

  • -p OUTPUT_PO_FILEPATH, --po-filepath OUTPUT_PO_FILEPATH, --pofilepath OUTPUT_PO_FILEPATH - Merge new msgids in the po file indicated at this parameter (if --save argument is passed) or use the msgids of the file as reference for mark not found as obsoletes if --merge-pofiles parameter is not passed. (default: None)

  • -s, --save - Save new found msgids to the po file indicated as parameter --po-filepath. Passing this option without defining the argument --po-filepath will raise an error.

  • --mo-filepath OUTPUT_MO_FILEPATH, --mofilepath OUTPUT_MO_FILEPATH - The resulting PO file will be compiled to a mofile and saved in the path specified at this parameter. (default: None)

  • --plaintext - Do not include markdown markup characters in extracted msgids for **bold text**, *italic text*, ``inline code`` and [link](target).

  • --wrapwidth N/INF, -w N/INF - Maximum width rendering the PO file indicated at parameter --po-filepath. If negative, '0' or 'inf', the content will not be wrapped. (default: 78)

  • -m, --merge-po-files, --merge-pofiles - Messages not found which are already stored in the PO file passed as --po-filepath argument will not be marked as obsolete.

  • -r, --remove-not-found - Messages not found which are already stored in the PO file passed as --po-filepath parameter will be removed. Only has effect used in combination with --merge-pofiles. If you pass this option, --merge-po-files will be ignored.

  • --no-location, --nolocation - Do not write '#: filename:line' lines. Note that using this option makes it harder for technically skilled translators to understand the context of each message. Same as gettext --no-location.

  • -x EXTENSION, --extension EXTENSION, --ext EXTENSION - md4c extension used to parse markdown content formatted as pymd4c extension keyword arguments. This argument can be passed multiple times. If it is not passed, next extensions are used: collapse_whitespace, tables, strikethrough, tasklists, latex_math_spans and wikilinks. You can see all available at https://pymd4c.dcpx.org/api.html#parser-option-flags (default: None)

  • --md-encoding ENCODING - Markdown content encoding. (default: utf-8)

  • --po-encoding ENCODING - Resulting PO file encoding. (default: None)

  • -a, --xheader - Include in the resulting PO file the mdpo specification X-Header "X-Generation", whose value is "mdpo v<version>".

  • -c, --include-codeblocks - Include all code blocks found inside PO file result. This is useful if you want to translate all your blocks of code. Equivalent to append <!-- mdpo-include-codeblock --> command before each code block.

  • --ignore-msgids IGNORE_MSGIDS - Path to a plain text file where all msgids to ignore from being extracted are located, separated by newlines. (default: None)

  • -d KEY:VALUE, --metadata KEY:VALUE - Custom metadata key-value pairs to include in the produced PO file. This argument can be passed multiple times. If the file contains previous metadata fields, these will be updated preserving the values of the already defined. For example, to define UTF-8 encoding and Spanish language use -d ”Content-Type: text/plain; charset=utf-8” -d ”Language: es”. (default: [])

  • --command-alias CUSTOM-COMMAND:MDPO-COMMAND - Aliases to use custom mdpo command names in comments. This argument can be passed multiple times in the form "<custom-command>:<mdpo-command>". The 'mdpo-' prefix in command names resolution is optional. For example, if you want to use "<!-- mdpo-on -->" instead of "<!-- mdpo-enable -->", you can pass either --command-alias ”mdpo-on:mdpo-enable” or --command-alias ”mdpo-on:enable” arguments. (default: [])

  • -e EVENT_NAME: PATH/TO/FILE.PY::FUNCTION_NAME, --event EVENT_NAME: PATH/TO/FILE.PY::FUNCTION_NAME - Custom events executed during the parser. They are used for customize the output. See the documentation for available event names. This argument can be passed multiple times. (default: [])

  • -D, --debug - Print useful messages in the parsing process showing the contents of all Markdown elements.

  • --check - Run in check mode, which returns code 2 at exit when a file has been changed or previously did not exist.

  • --no-obsolete - If obsolete entries found in PO files exit with non zero code.

  • --no-fuzzy - If fuzzy entries found in PO files exit with non zero code.

  • --no-empty-msgstr - If empty msgstrs found in PO files exit with non zero code.

po2md

Markdown file translator using PO files as reference.

This implementation reproduces the same valid Markdown output, given the provided content, with translations replaced, but does not produces the same input format.

po2md [-h] [-v] [-q] -p [POFILES ...] [-i PATH] [-s PATH] [--wrapwidth N/inf]
      [--md-encoding ENCODING] [--po-encoding ENCODING]
      [--command-alias CUSTOM-COMMAND:MDPO-COMMAND]
      [-e event_name: path/to/file.py::function_name] [-D] [--check] [--no-obsolete]
      [--no-fuzzy] [--no-empty-msgstr]
      [FILEPATH_OR_CONTENT ...]

po2md positional argument

  • FILEPATH_OR_CONTENT - Markdown filepath or content to translate. If not provided, will be read from STDIN. (default: None)

po2md options

  • -h, --help - Show this help message and exit.

  • -v, --version - Show program version number and exit.

  • -q, --quiet - Do not print output to STDOUT.

  • -p POFILES, --po-files POFILES, --pofiles POFILES - Glob matching a set of PO files from where to extract references to make the replacements translating strings. This argument can be passed multiple times. (default: None)

  • -i PATH, --ignore PATH - Filepath to ignore when --pofiles argument value is a glob. This argument can be passed multiple times. (default: [])

  • -s PATH, --save PATH - Saves the output content in a file whose path is specified at this parameter. (default: None)

  • --wrapwidth N/INF, -w N/INF - Maximum width rendering the Markdown output, when possible. If negative, '0' or 'inf', the content will not be wrapped. (default: 80)

  • --md-encoding ENCODING - Markdown content encoding. (default: utf-8)

  • --po-encoding ENCODING - PO files encoding. If you need different encodings for each file, you must define them in the "Content-Type" field of each PO file metadata, in the form 'Content-Type: text/plain; charset=<ENCODING>'. (default: None)

  • --command-alias CUSTOM-COMMAND:MDPO-COMMAND - Aliases to use custom mdpo command names in comments. This argument can be passed multiple times in the form "<custom-command>:<mdpo-command>". The 'mdpo-' prefix in command names resolution is optional. For example, if you want to use "<!-- mdpo-on -->" instead of "<!-- mdpo-enable -->", you can pass either --command-alias ”mdpo-on:mdpo-enable” or --command-alias ”mdpo-on:enable” arguments. (default: [])

  • -e EVENT_NAME: PATH/TO/FILE.PY::FUNCTION_NAME, --event EVENT_NAME: PATH/TO/FILE.PY::FUNCTION_NAME - Custom events executed during the parser. They are used for customize the output. See the documentation for available event names. This argument can be passed multiple times. (default: [])

  • -D, --debug - Print useful messages in the parsing process showing the contents of all Markdown elements.

  • --check - Run in check mode, which returns code 2 at exit when a file has been changed or previously did not exist.

  • --no-obsolete - If obsolete entries found in PO files exit with non zero code.

  • --no-fuzzy - If fuzzy entries found in PO files exit with non zero code.

  • --no-empty-msgstr - If empty msgstrs found in PO files exit with non zero code.

markdownlint compatible configuration

The output produced by po2md is compatible with the following Markdownlint configuration:

{
  "no-blanks-blockquote": false,
  "no-bare-urls": false,
  "no-inline-html": false,
  "ul-indent": {
    "indent": 3
  }
}

md2po2md

Translates Markdown files using PO files for a set of predefined language codes creating multiple directories, one for each language.

md2po2md [-h] [-v] [-q] -l [LANG ...] -o PATH_SCHEMA [--no-location] [-x EXTENSION]
         [--command-alias CUSTOM-COMMAND:MDPO-COMMAND] [--po-wrapwidth N/inf]
         [--md-wrapwidth N/inf] [-c] [--md-encoding ENCODING] [--po-encoding ENCODING] [-D]
         [--check] [--no-obsolete] [--no-fuzzy] [--no-empty-msgstr]
         [GLOB ...]

md2po2md positional arguments

  • GLOB - Glob to markdown input files to translate. If not provided, will be read from STDIN. (default: None)

md2po2md options

  • -h, --help - Show this help message and exit.

  • -v, --version - Show program version number and exit.

  • -q, --quiet - Do not print output to STDOUT.

  • -l LANG, --lang LANG - Language codes used to create the output directories. This argument can be passed multiple times. Also, all languages can be defined after this argument with -l es_ES fr_FR de_DE. (default: [])

  • -o PATH_SCHEMA, --output PATH_SCHEMA - Path schema for outputs, built using placeholders. There is a mandatory placeholder for languages: {lang};and one optional for output basename: {basename}. Unexistent directories and files will be created, so you do not have to prepare the output directories before the execution. (default: None)

  • --no-location, --nolocation - Do not write '#: filename:line' lines. Note that using this option makes it harder for technically skilled translators to understand the context of each message. Same as gettext --no-location.

  • -x EXTENSION, --extension EXTENSION, --ext EXTENSION - md4c extension used to parse markdown content formatted as pymd4c extension keyword arguments. This argument can be passed multiple times. If it is not passed, next extensions are used: collapse_whitespace, tables, strikethrough, tasklists, latex_math_spans and wikilinks. You can see all available at https://pymd4c.dcpx.org/api.html#parser-option-flags (default: None)

  • --command-alias CUSTOM-COMMAND:MDPO-COMMAND - Aliases to use custom mdpo command names in comments. This argument can be passed multiple times in the form "<custom-command>:<mdpo-command>". The 'mdpo-' prefix in command names resolution is optional. For example, if you want to use "<!-- mdpo-on -->" instead of "<!-- mdpo-enable -->", you can pass either --command-alias ”mdpo-on:mdpo-enable” or --command-alias ”mdpo-on:enable” arguments. (default: [])

  • --po-wrapwidth N/INF - Maximum width rendering PO files. If negative, '0' or 'inf', the content will not be wrapped. (default: 78)

  • --md-wrapwidth N/INF - Maximum width rendering the Markdown output, when possible. If negative, '0' or 'inf', the content will not be wrapped. (default: 80)

  • -c, --include-codeblocks - Include all code blocks found inside PO file result. This is useful if you want to translate all your blocks of code. Equivalent to append <!-- mdpo-include-codeblock --> command before each code block.

  • --md-encoding ENCODING - Markdown content encoding. (default: utf-8)

  • --po-encoding ENCODING - PO files encoding. If you need different encodings for each file, you must define them in the "Content-Type" field of each PO file metadata, in the form 'Content-Type: text/plain; charset=<ENCODING>'. (default: None)

  • -D, --debug - Print useful messages in the parsing process showing the contents of all Markdown elements.

  • --check - Run in check mode, which returns code 2 at exit when a file has been changed or previously did not exist.

  • --no-obsolete - If obsolete entries found in PO files exit with non zero code.

  • --no-fuzzy - If fuzzy entries found in PO files exit with non zero code.

  • --no-empty-msgstr - If empty msgstrs found in PO files exit with non zero code.

mdpo2html

HTML-produced-from-Markdown file translator using PO files.

mdpo2html [-h] [-v] [-q] [-p [POFILES ...]] [-i PATH] [-s PATH] [--html-encoding ENCODING]
          [--po-encoding ENCODING] [--command-alias CUSTOM-COMMAND:MDPO-COMMAND] [--check]
          [--no-obsolete] [--no-fuzzy] [--no-empty-msgstr]
          [FILEPATH_OR_CONTENT ...]

mdpo2html positional arguments

  • FILEPATH_OR_CONTENT - HTML file path or content to translate. If not provided, will be read from STDIN. (default: None)

mdpo2html options

  • -h, --help - Show this help message and exit.

  • -v, --version - Show program version number and exit.

  • -q, --quiet - Do not print output to STDOUT.

  • -p POFILES, --po-files POFILES, --pofiles POFILES - Glob matching a set of PO files from where to extract references to make the replacements translating strings. This argument can be passed multiple times. (default: None)

  • -i PATH, --ignore PATH - Filepaths to ignore when --pofiles argument value is a glob. This argument can be passed multiple times. (default: [])

  • -s PATH, --save PATH - Saves the output content in file whose path is specified at this parameter. (default: None)

  • --html-encoding ENCODING - HTML content encoding. (default: utf-8)

  • --po-encoding ENCODING - PO files encoding. If you need different encodings for each file, you must define them in the "Content-Type" field of each PO file metadata, in the form 'Content-Type: text/plain; charset=<ENCODING>'. (default: None)

  • --command-alias CUSTOM-COMMAND:MDPO-COMMAND - Aliases to use custom mdpo command names in comments. This argument can be passed multiple times in the form "<custom-command>:<mdpo-command>". The 'mdpo-' prefix in command names resolution is optional. For example, if you want to use "<!-- mdpo-on -->" instead of "<!-- mdpo-enable -->", you can pass either --command-alias ”mdpo-on:mdpo-enable” or --command-alias ”mdpo-on:enable” arguments. (default: [])

  • --check - Run in check mode, which returns code 2 at exit when a file has been changed or previously did not exist.

  • --no-obsolete - If obsolete entries found in PO files exit with non zero code.

  • --no-fuzzy - If fuzzy entries found in PO files exit with non zero code.

  • --no-empty-msgstr - If empty msgstrs found in PO files exit with non zero code.