Tutorial

mdpo provides flexible ways for doing Markdown markup translations. In this tutorial are covered the most common workflows.

Markdown to markdown

If you want to translate a Markdown source using a PO file and produce translated Markdown output, use this method.

Given the next directories tree:

📁 .
├── 📁 locale
│   └── 📁 es
│       └── 📁 LC_MESSAGES
└── 📄 README.md

Use the next command to create or update the PO file for README.md:

md2po README.md --quiet --save --po-filepath locale/es/LC_MESSAGES/readme.po

Then, in order of translate the README.md producing other file as result:

po2md README.md --pofiles locale/es/LC_MESSAGES/readme.po --quiet \
  --save locale/es/LC_MESSAGES/README.md

This will be the output after previous two commands:

📁 .
├── 📁 locale
│   └── 📁 es
│       └── 📁 LC_MESSAGES
│           ├── 📄 README.md
│           └── 📄 readme.po
└── 📄 README.md

Simple README file translation

Just use md2po2md CLI:

md2po2md README.md -l es fr -o "locale/{lang}"

Define the languages to translate into using the --lang/-l option.

You also can use the next snippet to include links for the translations:

<!-- mdpo-disable -->
<!-- mdpo-enable-next-line -->
> Read this document in other languages:
>
> - [Español][readme-es]
> - [Français][readme-fr]
<!-- mdpo-enable -->

[readme-es]: https://github.com/user/repo/blob/master/locale/es/README.md
[readme-fr]: https://github.com/user/repo/blob/master/locale/fr/README.md

This will be the output after the previous command:

📁 .
├── 📁 locale
│   ├── 📁 es
│   |   ├── 📄 README.md
│   |   └── 📄 readme.po
|   └── 📁 fr
│       ├── 📄 README.md
│       └── 📄 readme.po
└── 📄 README.md

HTML-from-Markdown to HTML

If you have a HTML file produced from Markdown using a Markdown processor like Python-Markdown and you want to translate it in place using PO files, use this method.

Warning

This method is experimental. If you have issues consider to open an issue in the bug tracker.

Given next directory tree:

📁 .
├── 📁 locale
│   └── 📁 es
│       └── 📁 LC_MESSAGES
├── 📄 README.html
└── 📄 README.md

Where the file README.html have been produced using an HTML processor, use next command to create and update the translation pofile for README.html:

md2po README.md --quiet --save --po-filepath locale/es/LC_MESSAGES/readme.po

After that, you can use the new file locale/es/LC_MESSAGES/readme.po to replace the contents of the file README.html with your translations, using next command:

mdpo2html README.html --pofiles locale/es/LC_MESSAGES/readme.po --quiet \
  --save locale/es/LC_MESSAGES/README.html

And this will produce your translated file in locale/es/LC_MESSAGES/README.html:

📁 .
├── 📁 locale
│   └── 📁 es
│       └── 📁 LC_MESSAGES
│           ├── 📄 README.html
│           └── 📄 readme.po
├── 📄 README.html
└── 📄 README.md