You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Hi there! I wrote tooling for translating mdbook projects for Comprehensive Rust: mdbook-i18n-helpers. We have used this to translate our course into many languages and I hope it can be useful here too!
Those files would just be an extension of the existing book, but this time in another language.
You are not allowed to do that by license. At least in separate repository
Oh, I see what you mean now... I read more about the no-derivatives part of the license and it does indeed seem to forbid making public forks of the repository. I was first thinking that a fork wouldn't be "distribution", but I fail to find a clear definition of what CC means by "distribution".
Oh well, I hope someone can use the tooling and I wish the authors best of luck with the project here.
Hey! Apologies for the delayed reply, this is a great question.
The goal in making the book free/open-source is to reduce barriers to access, so that this effort can provide value to a range of readers. Translation to other languages is well-aligned with that goal, thank you for raising this point.
To my understanding (am not an expert in licensing/legal): changing the license to allow free distribution of derivative translations (e.g. replace CC BY-NC-ND 4.0 with CC BY-NC-SA 4.0 or similar) introduces the risk of the derivative work diverging substantially (e.g. technically inaccurate, morally objectionable, or just drastically different in vision). There could be a severe and unpredictable impact on the original project, so this is not a risk I’d like to accept at this time. If that’s not an accurate assessment, please let me know! Still learning as I go when it comes to licensing.
Maintaining translations within this repository under the current license, using tools like mdbook-i18n-helpers or similar, is better fit for this project. But I’m unsure if it could work in practice: I cannot review non-English translations for accuracy and have limited bandwidth outside of my full-time job more generally.
Can you provide more information on the high-level mechanics of this tool-enabled translation workflow?
The long-term ambition for the book also includes publishing (self or traditional) and selling a physical copy once all book content is complete (however many years that takes) - with the exact same content always being freely available online (e.g. NO exclusive/paid-only content).
Traditional publishers sometimes provide professional translation if there’s enough demand, and that is my preferred potential path to translation and more global accessibility - at least at this time. That said, it’d be ideal to enable near-term translation of the currently-freely-available ~200 pages before then - so I’d like to keep this issue open to explore possible solutions.
But I’m unsure if it could work in practice: I cannot review non-English translations for accuracy and have limited bandwidth outside of my full-time job more generally.
Yes, that is indeed a difficult problem! For Comprehensive Rust, we have decided to trust each language community to review the PRs. Some of the reviewers are other Google engineers, which conveys trust for a Google-run project, but some reviewers are people who show up and express an interest in the project.
So far, this seems to have worked well, but I cannot know 100% if the translators have actually done a good or correct job. I have to trust them.
Can you provide more information on the high-level mechanics of this tool-enabled translation workflow?
At a high level, mdbook-i18n-helpers has two tools:
a mdbook backend for extracting translatable text from Markdown files. This produces all the msgid entries you see in a file like fr.po
a mdbook plugin for translating a Markdown file into a new Markdown file (on the fly), using a .po file to do the mapping between original and translated text. This is how the French translation is created. Because these are mdbook plugins, they work well with other tooling, so we also have a French PDF.
It's fundamentally easy to take a directory tree of Markdown files, copy them somewhere else, and then translate them in-place. Easy to understand, easy to do. However, ongoing maintenance is hard: if a word is deleted from the English source text, how do you ensure that this change is reflected in the translations?
The structure you get from exporting the text to .po files helps here: you can ask, if the fr.po file current with regards to the English source text? If not, flag every entry that needs examination by a human translator (in Gettext lingo, the entries become "fuzzy").
Using this, you can then easily make a translation report and use this to know how up-to-date each translation is (important if you want to do a release of some sort).
Technically, the Gettext system is a key-value mapping: mapping text from the source language to the translation. When you commit add a
#: src/SUMMARY.mdmsgid"Rust Ecosystem"msgstr"Écosystème de Rust"
entry to the fr.po file, you say: this is the correct mapping between "Rust Ecosystem" and "Écosystème de Rust". If the English text changes, the French text presumably has to change as well. So the Gettext tooling will mark the entry as "fuzzy" when you extra new English text and merge it into the fr.po file. This is how the file has ended up with entries like
#,fuzzymsgid"Patterns and Destructuring"msgstr"Déstructuration des énumérations"
I don't actually speak French, but I suppose the English text used to be "Destructuring enumerations", which was translated to "Déstructuration des énumérations". When the English text changed to "Patterns and Destructuring", the French translation was marked as fuzzy. The fuzzy entries are not used by default and a translator should go through them, update the translations as needed, and remove the fuzzy flag.
So that is mdbook-i18n-helpers in a nutshell: a bit of structure around the text in the Markdown files, allowing you to more easily ensure that translations accurately reflect the latest version of the source text.
Activity
mgeisler commentedon Sep 14, 2024
Hi there! I wrote tooling for translating
mdbookprojects for Comprehensive Rust: mdbook-i18n-helpers. We have used this to translate our course into many languages and I hope it can be useful here too!mgeisler commentedon Sep 14, 2024
The mdbook-i18n-helpers also work well with publishing PDFs: #56.
non-descriptive commentedon Sep 14, 2024
It's nice to have tools, but it's the license' non-derive clause forbids actual translation
mgeisler commentedon Sep 21, 2024
Ah, I don't think I understand — surely it would be possible to commit files to this repository which contain a translation?
Those files would just be an extension of the existing book, but this time in another language.
non-descriptive commentedon Sep 21, 2024
You are not allowed to do that by license. At least in separate repository
mgeisler commentedon Sep 22, 2024
Oh, I see what you mean now... I read more about the no-derivatives part of the license and it does indeed seem to forbid making public forks of the repository. I was first thinking that a fork wouldn't be "distribution", but I fail to find a clear definition of what CC means by "distribution".
Oh well, I hope someone can use the tooling and I wish the authors best of luck with the project here.
tnballo commentedon Jul 7, 2025
Hey! Apologies for the delayed reply, this is a great question.
The goal in making the book free/open-source is to reduce barriers to access, so that this effort can provide value to a range of readers. Translation to other languages is well-aligned with that goal, thank you for raising this point.
To my understanding (am not an expert in licensing/legal): changing the license to allow free distribution of derivative translations (e.g. replace CC BY-NC-ND 4.0 with CC BY-NC-SA 4.0 or similar) introduces the risk of the derivative work diverging substantially (e.g. technically inaccurate, morally objectionable, or just drastically different in vision). There could be a severe and unpredictable impact on the original project, so this is not a risk I’d like to accept at this time. If that’s not an accurate assessment, please let me know! Still learning as I go when it comes to licensing.
Maintaining translations within this repository under the current license, using tools like
mdbook-i18n-helpersor similar, is better fit for this project. But I’m unsure if it could work in practice: I cannot review non-English translations for accuracy and have limited bandwidth outside of my full-time job more generally.Can you provide more information on the high-level mechanics of this tool-enabled translation workflow?
The long-term ambition for the book also includes publishing (self or traditional) and selling a physical copy once all book content is complete (however many years that takes) - with the exact same content always being freely available online (e.g. NO exclusive/paid-only content).
Traditional publishers sometimes provide professional translation if there’s enough demand, and that is my preferred potential path to translation and more global accessibility - at least at this time. That said, it’d be ideal to enable near-term translation of the currently-freely-available ~200 pages before then - so I’d like to keep this issue open to explore possible solutions.
mgeisler commentedon Jul 7, 2025
Yes, that is indeed a difficult problem! For Comprehensive Rust, we have decided to trust each language community to review the PRs. Some of the reviewers are other Google engineers, which conveys trust for a Google-run project, but some reviewers are people who show up and express an interest in the project.
So far, this seems to have worked well, but I cannot know 100% if the translators have actually done a good or correct job. I have to trust them.
At a high level,
mdbook-i18n-helpershas two tools:mdbookbackend for extracting translatable text from Markdown files. This produces all themsgidentries you see in a file likefr.pomdbookplugin for translating a Markdown file into a new Markdown file (on the fly), using a.pofile to do the mapping between original and translated text. This is how the French translation is created. Because these aremdbookplugins, they work well with other tooling, so we also have a French PDF.It's fundamentally easy to take a directory tree of Markdown files, copy them somewhere else, and then translate them in-place. Easy to understand, easy to do. However, ongoing maintenance is hard: if a word is deleted from the English source text, how do you ensure that this change is reflected in the translations?
The structure you get from exporting the text to
.pofiles helps here: you can ask, if thefr.pofile current with regards to the English source text? If not, flag every entry that needs examination by a human translator (in Gettext lingo, the entries become "fuzzy").Using this, you can then easily make a translation report and use this to know how up-to-date each translation is (important if you want to do a release of some sort).
Technically, the Gettext system is a key-value mapping: mapping text from the source language to the translation. When you commit add a
entry to the
fr.pofile, you say: this is the correct mapping between "Rust Ecosystem" and "Écosystème de Rust". If the English text changes, the French text presumably has to change as well. So the Gettext tooling will mark the entry as "fuzzy" when you extra new English text and merge it into thefr.pofile. This is how the file has ended up with entries likeI don't actually speak French, but I suppose the English text used to be "Destructuring enumerations", which was translated to "Déstructuration des énumérations". When the English text changed to "Patterns and Destructuring", the French translation was marked as fuzzy. The fuzzy entries are not used by default and a translator should go through them, update the translations as needed, and remove the fuzzy flag.
So that is
mdbook-i18n-helpersin a nutshell: a bit of structure around the text in the Markdown files, allowing you to more easily ensure that translations accurately reflect the latest version of the source text.