How this repo is organized¶
Here is a rundown of the directory structure of translate the docs:
All of the documentation for how to translate the docs
lives in markdown files in
This is converted to HTML documentation using
The configuration for mkdocs is in
The mkdocs theme used is mkdocs-material, which is in the
The static content is on the
gh-pages branch and is hosted
https://pages.charlesreid1.com/ and on Github Pages.
The document is first parsed with pandoc to convert markdown to JSON.
The JSON is passed to a panflute filter, which processes the text.
Translation magic happens using the Google Cloud Translate API, which is called by the panflute filter.
Pandoc is used to convert the JSON back to (translated) markdown.
The tool in this repository (the pandoc filter) will eventually become a command line tool that can be run in-place from any repository, and the translated markdown deposited into a new directory.
This requires one major design change: rather than using pandoc and applying filters from the command line, we must call the pandoc API from Python directly. Then we can define the filter as part of the command line tool, and when we call the translate the docs tool, it applies the filter in-place.
The end result, for the user, is the ability to run a single command that will translate their docs:
$ translate_the_docs --list-languages ru de es fr ar ... $ translate_the_docs Before we can translate your docs, we will start with a few questions. What directory contains your current markdown docs? Leave empty for default: docs Answer: docs What language do you want to translate your markdown docs into? Type ? for a list of languages. Answer: ? Possible languages: ru, de, es, fr, ar, ... What language do you want to translate your markdown docs into? Type ? for a list of languages. Answer: ru What directory do you want to contain your translated markdown docs? Leave empty for default: ru_docs Answer: Translating... Done!
Or set with command line options:
$ translate_the_docs --source=doc/ --target=ru_docs --language=ru