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 .po files and produce translated Markdown output, use this method.

Given next directory tree:

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

Use the next command to create and update the translation pofile 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

See also


Simple README file translation

Just use md2po2md CLI:

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

Define the languages to translate into using the -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
└── README.md

See also


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

See also