Command line interfaces

mdpo installation includes three 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 pofile 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 pofile of reference for strings.


md2po

Utility like xgettext to extract Markdown content dumping it inside PO files.

md2po [-h] [-v] [-q] [-i PATH] [-po OUTPUT_PO_FILEPATH] [-s] [-mo OUTPUT_MO_FILEPATH] [-p]
      [-w 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] [-D] [--pre-commit]
      [GLOB_OR_CONTENT [GLOB_OR_CONTENT ...]]

md2po positional arguments

  • GLOB_OR_CONTENT - Glob to markdown input files or markdown content as string. If not provided, will be read from STDIN. (default: None)

md2po optional arguments

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

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

  • -q, --quiet - Do not print output to STDOUT. (default: False)

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

  • -po 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/--po-filepath'. Passing this option without defining the argument '-po/--po-filepath' will raise an error. (default: False)

  • -mo OUTPUT_MO_FILEPATH, --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)

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

  • -w N/INF, --wrapwidth N/INF - Wrap width for po file indicated at '-po/--po-filepath' parameter. Only useful when the '-w' option was passed to xgettext. You can use the values '0' and 'inf' for infinite width. (default: 78)

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

  • -r, --remove-not-found - Messages not found which are already stored in the PO file passed as '-po/--po-filepath' parameter will be removed. Only has effect used in combination with '--merge-pofiles'. (default: True)

  • --no-location, --nolocation - Do not write '#: filename:line' lines. Note that using this option makes it harder for technically skilled translators to understand each message``’s context. Same as ‘``xgettext –no-location’. (default: True)

  • -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 is not passed, next extensions are used: collapse_whitespace, tables, strikethrough, tasklists, latex_math_spans, wikilinks. You can see all available at https://github.com/dominickpastore/pymd4c#parser-option-flags (default: None)

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

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

  • -a, --xheaders - Include mdpo specification x-headers. These only will be included if you do not pass the parameter '--plaintext'. (default: False)

  • -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. (default: False)

  • --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: [])

  • -D, --debug - Print useful messages in the parsing process showing the contents of all Markdown elements. (default: False)

  • --pre-commit - Run in pre-commit mode, which returns code 1 at exit when a file has been changed or previously didn’t exist. (default: False)


po2md

Markdown files translator using pofiles as reference. This implementation reproduces the same valid Markdown output, given the provided AST, with replaced translations, but doesn’t rebuilds the same input format as Markdown is just a subset of HTML.

po2md [-h] [-v] [-q] [-p [POFILES [POFILES ...]]] [-i PATH] [-s PATH] [-w N/inf]
      [--md-encoding ENCODING] [--po-encoding ENCODING]
      [--command-alias CUSTOM-COMMAND:MDPO-COMMAND] [-D] [--pre-commit]
      [FILEPATH_OR_CONTENT [FILEPATH_OR_CONTENT ...]]

po2md positional arguments

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

po2md optional arguments

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

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

  • -q, --quiet - Do not print output to STDOUT. (default: False)

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

  • -w N/INF, --wrapwidth N/INF - Maximum width rendering the Markdown output, when possible. You can use the values '0' and 'inf' for infinite width. (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>\n'. (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: [])

  • -D, --debug - Print useful messages in the parsing process showing the contents of all Markdown elements. (default: False)

  • --pre-commit - Run in pre-commit mode, which returns code 1 at exit when a file has been changed or previously didn’t exist. (default: False)

markdownlint compatible configuration

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

{
  "no-blanks-blockquote": false,
  "no-bare-urls": 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] [-l LANG] -o PATH_SCHEMA [--no-location] [-x EXTENSION]
         [--command-alias CUSTOM-COMMAND:MDPO-COMMAND] [--md-encoding ENCODING]
         [--po-encoding ENCODING] [-D] [--pre-commit]
         [GLOB [GLOB ...]]

md2po2md positional arguments

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

md2po2md optional arguments

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

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

  • -l LANG, --lang LANG - Language codes used to create the output directories. Can be passed multiple times. (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}. For example, for the schema ``'locale/``{lang}, the languages ``'es' and 'fr' and a 'README.md' as input, the next files will be written: 'locale/es/README.po', 'locale/es/README.md', 'locale/fr/README.po' and 'locale/fr/README.md'. Note that you can omit '``{basename}, specifying a directory for each language with ``'locale/``{lang}’`` for this example. Unexistent directories and files will be created, so you don’t 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 each message``’s context. Same as ‘``xgettext –no-location’. (default: True)

  • -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 is not passed, next extensions are used: collapse_whitespace, tables, strikethrough, tasklists, latex_math_spans, wikilinks. You can see all available at https://github.com/dominickpastore/pymd4c#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: [])

  • --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>\n'. (default: None)

  • -D, --debug - Print useful messages in the parsing process showing the contents of all Markdown elements. (default: False)

  • --pre-commit - Run in pre-commit mode, which returns code 1 at exit when a file has been changed or previously didn’t exist. (default: False)


mdpo2html

HTML-produced-from-Markdown files translator using PO files as reference.

mdpo2html [-h] [-v] [-q] [-p [POFILES [POFILES ...]]] [-i PATH] [-s PATH]
          [--html-encoding <ENCODING>] [--po-encoding <ENCODING>]
          [--command-alias CUSTOM-COMMAND:MDPO-COMMAND]
          [FILEPATH_OR_CONTENT [FILEPATH_OR_CONTENT ...]]

mdpo2html positional arguments

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

mdpo2html optional arguments

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

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

  • -q, --quiet - Do not print output to STDOUT. (default: False)

  • -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> - Markdown content encoding. (default: utf-8)

  • --po-encoding <ENCODING> - PO files encoding. If you need different encodings for each file, you must define it in the "Content-Type" field of each PO file metadata, in the form "Content-Type: text/plain; charset=<ENCODING>\n". (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: [])