translate yer docs

This repository translates yer docs into another language.

This uses the Google Cloud Translate API, pandoc, and the panflute library to create a translation filter for Markdown files.

See an example here: russian-rainbow-mind-machine (page contains documentation for the rainbow-mind-machine library translated into Russian).

How this repo is organized

Part 1: Google Cloud Translate API Setup

The Google Cloud Translate API is what makes this all possible.

It is easier to translate documentation into Russian than it is to figure out how to parse Markdown programmatically with panflute and pandocs.

Part 1: Setup

Part 2: Pandoc

We want to parse and translate Markdown written in English, and turn it into Markdown written in Russian. We use pandoc to parse the Markdown file and identify the bits that can be translated, pass them to the Google Cloud Translate API, and convert the translated text back into Markdown.

Part 2A: Pandoc Parser: Markdown to JSON

Part 2B: Pandoc Parser: JSON to JSON

Part 3: Panflute

Panflute is a Python library for writing Pandoc filters. It is picky and tricky.

Part 3A: Panflute Filter: Translate

Part 3B: Panflute Filter: Dealing with Links and Headers

Part 4: Pandoc

The panflute filter will process JSON and return more JSON, so we have one last step, which is converting the final JSON document into Markdown.

Part 4: Pandoc Parser: JSON to Markdown

Part 5: Testing

You do want to write tests for all of this stuff, don't you?

Part 5: Testing

Part 6: Useful Links

Part 6: Useful Links