This implements a translation pipeline using the industry-standard
Gettext[1] system.
I picked Gettext for the reasons described in [2] and [3]:
* It’s widely used in open source software. This means that there are
graphical editors which will help you in editing the `.po` files. An
example is Poedit[4], which is available for all major platforms.
There are also many online systems for doing translations. An
example is Pontoon[5], which is used for the Rust website itself. We
can consider setting up such an instance ourselves.
* It is a light-weight yet structured format. This means that nothing
changes with regards to how you update the original English text. We
can still accept fixes and PRs like normal.
The structure means that translators can see exactly which part of
the course they need to update after a change. This is completely
lost if you simply copy over the original text and translate it
in-place in the Markdown files.
The code here only adds support for translations. They are not yet
tested, published or used for anything. Next steps will be:
* Add support for switching languages via a bit of JavaScript on each
page.
* Update the speaker notes feature to support translations (right now
“Speaker Notes” is hard-coded into the generated HTML). I think we
should turn it into a mdbook preprocessor instead.
* Add testing: We should test that the `.po` files are well-formed. We
should also run `mdbook test` on each language since the
translations can alter the embedded code.
Fixes#115.
[1]: https://www.gnu.org/software/gettext/manual/html_node/index.html
[2]: https://github.com/rust-lang/mdBook/pull/1864
[3]:
https://github.com/rust-lang/mdBook/issues/5#issuecomment-1144887806
[4]: https://poedit.net/
[5]: https://pontoon.rust-lang.org/
Before, we attempted to change state from “popup” to “inline-open”
when the speaker note window was closed.
We did this by listening to “pagehide” and change the state there. The
event fires every time you navigate away from the page, so we had a
complex setup where we would reset the state to “popup” when the next
page was loaded into the speaker note window.
The problem with this is that it’s racy: we could end up in a
situation where we set the state to “inline-open” right after the
speaker note window was updated. When that happened, we would mark the
window as “defunct”, meaning that it was supposed to be closed.
With this change, we no longer try to change the state from the
speaker note window. If the window is lost (closed), the user will
have to click the “Close speaker notes” button in the top-right to
reset the state. This should be much more reliable.
Long-term, a better solution would be to let the speaker notes fetch
the current URL using JavaScript instead of doing it via an actual
page navigation. That should allow us to react to “pagehide” events
again (since they won’t fire on every page transition).
