Automated Documentation Translation into World Languages
We are preparing a new version of our website, a significant part of which is user and developer documentation. Maintaining documentation in more than one language is beyond our capacity, so we chose English, but the ambition to provide documentation in developers' native languages never left us. In this article, we offer a look at the mechanism we want to use to achieve this.
Core Functionality of the Comenius Plugin
The code then iterates through all files (you have full control over any excludes, of course) and calls the configured LLM model in parallel to translate individual files. Once the full translation completes, a second phase follows in which it fixes links to internal sections (anchors) that no longer match because headings were translated into the target language. To make this possible, the plugin enforces a consistent heading structure even after translation, and when searching for the target heading for an anchor, it relies on the order and structure of headings in the given document. As a final step, the plugin validates links in the translated document (which is why there must be no broken links before translation begins).
During implementation, I discovered that LLMs do not handle translation of large pages well and tend to shorten the translation, replacing portions with a simple "... and so on". Therefore, before translation, the plugin checks the article size, and if it exceeds 32 kB, it attempts to split it into several smaller parts while respecting the heading structure (e.g., it tries to split along H2 headings) so as to produce several pieces that optimally approach the 32 kB threshold, which proved reliable for translations. After all parts are translated, they are merged back into a single comprehensive document matching the original.
Incremental Translations
Naturally, as your documentation evolves, you do not want to keep translating the entire original documentation from scratch. That is why the plugin implements a special translation variant for incremental updates. When it detects that a corresponding target file already exists, it looks at the commit hash recorded in it. It then checks out the original document at that version and compares it with the current version of the source document. For individual blocks (i.e., chapters), it computes a hash of their content and sends only the blocks (chapters) identified as changed to the LLM for translation, along with some surrounding content before and after for additional context.
After the incremental translation completes, the heading structure integrity is verified again, links across the entire already-translated documentation are updated, and link validity is checked.