mdTranslation

mdTranslation is a utility to prepare multi-lingual Markdown documents.

There's also a mdBook preprocessor called mdbook-translation for working with mdBook books.

How does it achieve this?

This is done by associating source contents and their translations together. This association is expressed as a separate Markdown documents within a specific simple format.

This file looks like this:

> Original content 1

* lang_ID1
Translated content written in lang_ID1
* lang_ID2
Translated content written in lang_ID2
****
...

This library can read and compare Markdown contents within each leaf node (paragraphs, list items, etc) to all the original contents here, when there's a match, it will replace it with the corresponding translated content. This makes it possible to do translation without touching the original document.

mdTranslation CLI tools

To use the CLI tools, just type this in the terminal:

cargo install mdtranslation-cli

This allows you to use two commands:

1. mdtranslation_extract

This tool help you to extract original contents and initial boilerplate into a Markdown file.

For example, if you want to provide a French translation for a.md, you can execute this:

mdtranslation_extract -l fr_FR a.md >> a.i18n.md

The >> here allows the newly generated content be appended to the tail of the file. You can use this method to collect all paragraphs from a book together.

2. mdtranslation_translate

This tool help you generate a translated and rendered html file for a Markdown file.

For example, if you want to provide a French translation for a.md, and you have the translation file ready at a.i18n.md, you can execute this:

mdtranslation_translate -l fr_FR -t a.i18n.md a.md > a.htm

If you didn't specify the language in a.i18n.md, you can pass an extra -d fr_FR parameter here to tell the program that the language is actually fr_FR. This is useful for single-translated language case, though we encourage you always spell out the actual language for each paragraph.

mdBook-translation preprocessor

There is also a mdBook preprocessor that allows you to use mdTranslation together with mdBook.

• To install the mdBook preprocessor, just type this in the terminal:

cargo install mdbook-translation

• After that you can enable this preprocessor for a specific book, by adding this to book.toml:

[preprocessor.translation]

• Now, before you run mdbook build as usual, you can set up environment variable to ask the preprocessor to generate the book in a specific language.

You need to do this if you're are using Windows cmd.exe:

set MDTRANSLATION_INPUT=book.i18n.md
set MDTRANSLATION_LANG=fr_FR
set MDTRANSLATION_DEFAULT_LANG=fr_FR

Or if you're using a *nix shell:

export MDTRANSLATION_INPUT=book.i18n.md
export MDTRANSLATION_LANG=fr_FR
export MDTRANSLATION_DEFAULT_LANG=fr_FR

The contents of the book will be replaced by the translated contents.