Public mdpo APIs

md2po

Markdown to PO files extractor according to mdpo specification.

mdpo.md2po.markdown_to_pofile(glob_or_content, ignore=[], msgstr='', po_filepath=None, save=False, mo_filepath=None, plaintext=False, wrapwidth=78, mark_not_found_as_obsolete=True, preserve_not_found=True, location=True, extensions=['collapse_whitespace', 'tables', 'strikethrough', 'tasklists', 'latex_math_spans', 'wikilinks'], po_encoding=None, md_encoding='utf-8', xheaders=False, include_codeblocks=False, ignore_msgids=[], command_aliases={}, metadata={}, events={}, debug=False, **kwargs)

Extracts all the msgids from a string of Markdown content or a group of files.

Parameters
  • glob_or_content (str) – Glob path to Markdown files or a string with valid Markdown content.

  • ignore (list) – Paths of files to ignore. Useful when a glob does not fit your requirements indicating the files to extract content. Also, filename or a dirname can be defined without indicate the full path.

  • msgstr (str) – Default message string for extracted msgids.

  • po_filepath (str) – File that will be used as polib.POFile instance where to dump the new msgids and that will be used as source checking not found strings that will be marked as obsolete if is the case (see save and mark_not_found_as_obsolete optional parameters).

  • save (bool) – Save the new content to the pofile indicated in the parameter po_filepath. If is enabled and po_filepath is None a ValueError will be raised.

  • mo_filepath (str) – The resulting pofile will be compiled to a mofile and saved in the path specified at this parameter.

  • plaintext (bool) – If you pass True to this parameter (as default) the content will be extracted as is, without markup characters included. Passing plaintext as False, extracted msgids will contain some markup characters used to appoint the location of `inline code`, **bold text**, *italic text* and `[links]`, that might be useful for you. It depends on the use you are going to give to this library activate this mode (plaintext=False) or not.

  • wrapwidth (int) – Wrap width for po file indicated at po_filepath parameter. Only useful when the -w option was passed to xgettext.

  • mark_not_found_as_obsolete (bool) – The strings extracted from markdown that will not be found inside the provided pofile will be marked as obsolete.

  • preserve_not_found (bool) – The strings extracted from markdown that will not be found inside the provided pofile wouldn’t be removed. Only has effect if mark_not_found_as_obsolete is False.

  • location (bool) – Store references of top-level blocks in which are found the messages in PO file #: reference comments.

  • extensions (list) – md4c extensions used to parse markdown content, formatted as a list of ‘pymd4c’ keyword arguments. You can see all available at pymd4c repository.

  • po_encoding (str) – Resulting pofile encoding.

  • md_encoding (str) – Markdown content encoding.

  • xheaders (bool) – Indicates if the resulting pofile will have mdpo x-headers included. These only can be included if the parameter plaintext is False.

  • include_codeblocks (bool) – Include all code blocks found inside pofile 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 (list) – List of msgids ot ignore from being extracted.

  • command_aliases (dict) – Mapping of aliases to use custom mdpo command names in comments. 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 the dictionaries {"mdpo-on": "mdpo-enable"} or {"mdpo-on": "enable"} to this parameter.

  • metadata (dict) – Metadata to include in the produced PO file. If the file contains previous metadata fields, these will be updated preserving the values of the already defined.

  • events (dict) –

    Preprocessing events executed during the parsing process. You can use these to customize the extraction process. Takes functions or list of functions as values. If one of these functions returns False, that part of the parsing is skipped by md2po (usually a MD4C event). The available events are:

    • enter_block(self, block, details): Executed when the parsing a Markdown block starts.

    • leave_block(self, block, details): Executed when the parsing a Markdown block ends.

    • enter_span(self, span, details): Executed when the parsing of a Markdown span starts.

    • leave_span(self, span, details): Executed when the parsing of a Markdown span ends.

    • text(self, block, text): Executed when the parsing of text starts.

    • command(self, mdpo_command, comment, original command): Executed when a mdpo HTML command is found.

    • msgid(self, msgid, msgstr, msgctxt, tcomment, flags): Executed when a msgid is going to be stored.

    • link_reference(self, target, href, title): Executed when a link reference is going to be stored.

    All self arguments are an instance of Md2Po parser. You can take advanced control of the parsing process manipulating the state of the parser. For example, if you want to skip a certain msgid to be included, you can do:

    def msgid_event(self, msgid, *args):
        if msgid == 'foo':
            self._disable_next_line = True
    

  • debug (bool) – Add events displaying all parsed elements in the extraction process.

Examples

>>> content = 'Some text with `inline code`'
>>> entries = markdown_to_pofile(content, plaintext=True)
>>> {e.msgid: e.msgstr for e in entries}
{'Some text with inline code': ''}
>>> entries = markdown_to_pofile(content)
>>> {e.msgid: e.msgstr for e in entries}
{'Some text with `inline code`': ''}
>>> entries = markdown_to_pofile(content, msgstr='Default message')
>>> {e.msgid: e.msgstr for e in entries}
{'Some text with `inline code`': 'Default message'}
Returns

polib.POFile Pofile instance with new msgids included.

Raises

ValueError: when po_filepath is None and save is True.

po2md

Markdown files translator using PO files as reference.

mdpo.po2md.pofile_to_markdown(filepath_or_content, pofiles, ignore=[], save=None, md_encoding='utf-8', po_encoding=None, command_aliases={}, wrapwidth=80, events={}, debug=False, **kwargs)

Translate Markdown content or file using PO files 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.

Parameters
  • filepath_or_content (str) – Markdown filepath or content to translate.

  • pofiles (str, list) – from where to extract messages to make the replacements translating strings.

  • ignore (list) – Paths of pofiles to ignore. Useful when a glob does not fit your requirements indicating the files to extract content. Also, filename or a dirname can be defined without indicate the full path.

  • save (str) – Saves the output content in file whose path is specified at this parameter.

  • md_encoding (str) – Markdown content encoding.

  • po_encoding (str) – 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".

  • command_aliases (dict) – Mapping of aliases to use custom mdpo command names in comments. 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 the dictionaries {"mdpo-on": "mdpo-enable"} or {"mdpo-on": "enable"} to this parameter.

  • wrapwidth (int) – Maximum width used rendering the Markdown output.

  • events (dict) –

    Preprocessing events executed during the translation process. You can use these to customize the output. Takes functions are values. If one of these functions returns False, that part of the translation process is skipped by po2md. The available events are:

    • enter_block(self, block, details): Executed when the parsing a Markdown block starts.

    • leave_block(self, block, details): Executed when the parsing a Markdown block ends.

    • enter_span(self, span, details): Executed when the parsing of a Markdown span starts.

    • leave_span(self, span, details): Executed when the parsing of a Markdown span ends.

    • text(self, block, text): Executed when the parsing of text starts.

    • command(self, mdpo_command, comment, original command): Executed when a mdpo HTML command is found.

    • msgid(self, msgid, msgstr, msgctxt, tcomment, flags): Executed when a msgid is going to be replaced.

    • link_reference(self, target, href, title): Executed when each reference link is being written in the output (at the end of the translation process).

  • debug (bool) – Add events displaying all parsed elements in the translation process.

Returns

Markdown output file with translated content.

Return type

str

md2po2md

Markdown to PO file to Markdown translator.

mdpo.md2po2md.markdown_to_pofile_to_markdown(langs, input_paths_glob, output_paths_schema, extensions=['collapse_whitespace', 'tables', 'strikethrough', 'tasklists', 'latex_math_spans', 'wikilinks'], command_aliases={}, location=True, debug=False, po_encoding=None, md_encoding=None, md2po_kwargs={}, po2md_kwargs={}, _check_saved_files_changed=False)

Translate a set of Markdown files using PO files.

Parameters
  • langs (list) – List of languages used to build the output directories.

  • input_paths_glob (str) – Glob covering Markdown files to translate.

  • output_paths_schema (str) –

    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', '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

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

  • extensions (list) –

    md4c extensions used to parse markdown content, formatted as a list of ‘pymd4c’ keyword arguments. You can see all available at pymd4c repository.

  • command_aliases (dict) – Mapping of aliases to use custom mdpo command names in comments. 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 the dictionaries {"mdpo-on": "mdpo-enable"} or {"mdpo-on": "enable"} to this parameter.

  • location (bool) – Store references of top-level blocks in which are found the messages in PO file #: reference comments.

  • debug (bool) – Add events displaying all parsed elements in the extraction process.

  • po_encoding (str) – PO files encoding.

  • md_encoding (str) – Markdown files encoding.

  • md2po_kwargs (dict) – Additional optional arguments passed to markdown_to_pofile function.

  • po2md_kwargs (dict) – Additional optional arguments passed to pofile_to_markdown function.

mdpo2html

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

mdpo.mdpo2html.markdown_pofile_to_html(filepath_or_content, pofiles, ignore=[], save=None, po_encoding=None, html_encoding='utf-8', command_aliases={}, **kwargs)

Produces a translated HTML file given a previous HTML file (created by a Markdown-to-HTML processor) and a set of pofiles as reference for msgstrs.

Parameters
  • filepath_or_content (str) – HTML whose content wants to be translated.

  • pofiles (str) – Glob for set of pofiles used as reference translating the strings to another language.

  • ignore (list) – List of paths to pofiles to ignore, useful if the glob patterns in pofiles parameter does not fit your requirements.

  • save (str) – If you pass this parameter as a path to one HTML file, even if does not exists, will be saved in the path the output of the function.

  • html_encoding (str) – HTML content encoding.

  • po_encoding (str) – 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".

  • command_aliases (dict) – Mapping of aliases to use custom mdpo command names in comments. 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 the dictionaries {"mdpo-on": "mdpo-enable"} or {"mdpo-on": "enable"} to this parameter.

Known limitations:

Returns

HTML output translated version of the given file.

Return type

str