Suggestions on managing translations

[3442853561]

As the English edition of the book is also constantly revised. So it will cause the translation and the original does not correspond. There is a suggestion.
We can manage articles in paragraphs. First give each paragraph(and title) an id in original text. Such as:

<!-- title1 -->
# Introduction

<!-- paragraph1 -->
Welcome to “The Rust Programming Language,” an introductory book about Rust.
Rust is a programming language that’s focused on safety, speed, and
concurrency. Its design lets you create programs that have the performance and
control of a low-level language, but with the powerful abstractions of a
high-level language. These properties make Rust suitable for programmers who
have experience in languages like C and are looking for a safer alternative, as
well as those from languages like Python who are looking for ways to write code
that performs better without sacrificing expressiveness.

<!-- paragraph2 -->
Rust performs the majority of its safety checks and memory management decisions
at compile time, so that your program's runtime performance isn't impacted. This
makes it useful in a number of use cases that other languages aren’t good at:
programs with predictable space and time requirements, embedding in other
languages, and writing low-level code, like device drivers and operating
systems. It's also great for web applications: it powers the Rust package
registry site, [crates.io]!  We're excited to see what *you* create with Rust.

[crates.io]: https://crates.io/

<!-- paragraph3 -->
This book is written for a reader who already knows how to program in at least
one programming language. After reading this book, you should be comfortable
writing Rust programs. We’ll be learning Rust through small, focused examples
that build on each other to demonstrate how to use various features of Rust as
well as how they work behind the scenes.

<!-- title2 -->
## Contributing to the book

<!-- paragraph4 -->
This book is open source. If you find an error, please don’t hesitate to file an
issue or send a pull request [on GitHub].

[on GitHub]: https://github.com/rust-lang/book

In this way, when the content of each paragraph change only needs to submit an issue to inform the translator which section of the changes occurred.
The issue can be closed. After all the translators(Translation manager in each language) have confirmed it.

[steveklabnik]

this is related to https://github.com/azerupi/mdBook/issues/5

[carols10cents]

Hopefully after we've been through the editing process with NoStarch Press to get ready to print the book, the english text won't change very often. At that point, and depending on how translations will work with mdBook as steve mentioned, I am totally in favor of putting into place whatever would help translation efforts ❤️

[KaiserY]

The commit id of the English version would be fine enough. Easy to track changes 😎

[SoboLAN]

I'm also interested in starting a translation process into Romanian, but this part concerns me a bit.
My thinking is to simply note the exact date/time when I fork the repo and then do a manual weekly check and see what was added to this repo's master branch.

Does anyone have a better idea? :)

[mgeisler]

Hi all, I ran in to the same problem as you all when starting a mdbook project which should be translated in several languages... To fix this, I wrote some tooling which integrates mdbook with Gettext: https://github.com/google/mdbook-i18n-helpers.

In a nutshell, a mdbook renderer called mdbook-xgettext is used to generate a "PO template", which contain all translatable text from the book. The text is split on paragraph boundaries and in terms of the comment above, the paragraph ID is the paragraph text itself. This means no overhead in managing IDs.

This "PO template" is then translated into many other languages by translators. They do this using dedicated PO editors. I use one in Emacs myself, some use Poedit, others use various online tools (https://www.transifex.com/, https://poeditor.com/, ...).

A mdbook preprocessor called mdbook-gettext uses the translated PO file to replace the source text with the translated text.

The result is a structured translation workflow which is maintainable and standard. We've used it successfully to translate Comprehensive Rust 🦀 to Korean and Brazilian Portuguese (with more languages in the pipeline).

I'm sure it could be used for the Rust Book as well. If there is interest, I could try putting up a PR showing how it could work?

[idontcalculate]

Hi! I suggest version in Serbian -> that is somewhat universal for seven or eight more languages, it should cover bosnian, macedonian, slovenian, montenegrian, croatian and smaller languages that have serbian origin, or protolanguage that unites all of them.
I am a coder and a linguist and I love Rust, so count me in to help you out on that - if people would find it useful, why not.

[dalance]

I opened a PR #3950 to add translation support based on https://github.com/google/mdbook-i18n-helpers which is created by @mgeisler.

[dalance]

I've started a new project to host Rust translation documentation.

https://rust-lang-translations.org

It uses mdbook-i18n-helpers and has CI and command line tools to support it,
so each language translation project doesn't have to maintain them separately.

Adding translations directly to the official documentation repository, as in #3950,
incurs high maintenance costs for the original contributors,
so I feel it's better to manage translation resources externally.