## Translation support

Mdview can extract a translation template from the current document, which can
be handed to a translator who will create a so-called message object (MO) file.

When mdview opens a markdown file, it looks for a MO file for the current
language locale following GNU gettext rules.  If the MO file is found, and it
includes applicable translations, mdview displays the translations of the input
markdown text; otherwise it displays the original text.

Run `mdview --help` for usage options.

<!-- intentionally add a hard line break below -->
To prepare the MO file, first run `mdview --PO` to extract a translation
catalog, so called PO file. The PO file contains "message identifiers" (gettext
"msgid"). Each msgid is a single-line paragraph of original text, that is, a
block of consecutive markdown lines joined together with space as the delimiter.
Hand the PO file to a translator, who will insert translations. Then use Gettext
tools to create the MO file from the PO file. This MO file will need to be
installed correctly to provide runtime translations to mdview.

## Writing translatable markdown documents

To enable translations start the document with:

%%nopot yes
**%%textdomain** YourDomain

%%nopot no

### Code blocks

Lines starting with **tab** or at least **4 spaces** are _not_ translated.

Text inside a fenced code block is _not_ translated unless the code block start
delimiter is tagged "gettext" explicitly.

    ```gettext
    mdview --po will output this code block because its start line is "```gettext".
    ```

---
```gettext
This code block
to be translated.
```
---

### Text

If some text lines should not be translated put them between matching `%%nopot`
yes/no tags:

    %%nopot yes

    `mdview --po` will not output lines between matching %%nopot tags.

    %%nopot no

---

%%nopot yes

This text line
not to be translated.

%%nopot no

---

## Additional resources

<!-- intentionally add some link below -->
* See __gettext_demo\*__ files in the __examples/__ directory.
* <https://www.gnu.org/software/gettext/manual/html_node/index.html>
* [Gettext on Wikipedia](https://en.wikipedia.org/wiki/Gettext).
