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: ````text

Original content 1

• langID1 Translated content written in langID1
• langID2 Translated content written in langID2

... ````

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

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

1. 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:

shell 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: shell cargo install mdbook-translation

• After that you can enable this preprocessor for a specific book, by adding this to book.toml: text [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: text 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: 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.