Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Suggestions on managing translations #464

Open
3442853561 opened this issue Feb 22, 2017 · 7 comments
Open

Suggestions on managing translations #464

3442853561 opened this issue Feb 22, 2017 · 7 comments
Labels
blocked upstream Blocked on a change that needs to happen in a different repo first Enhancement Translations
Milestone

Comments

@3442853561
Copy link
Contributor

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
Copy link
Member

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

@steveklabnik steveklabnik added blocked upstream Blocked on a change that needs to happen in a different repo first Enhancement Translations labels Feb 22, 2017
@carols10cents
Copy link
Member

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
Copy link

KaiserY commented Feb 26, 2017

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

@carols10cents carols10cents added this to the translations milestone Feb 21, 2018
@SoboLAN
Copy link

SoboLAN commented Mar 26, 2021

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
Copy link

mgeisler commented Apr 4, 2023

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
Copy link

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
Copy link

dalance commented Jun 6, 2024

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
blocked upstream Blocked on a change that needs to happen in a different repo first Enhancement Translations
Projects
None yet
Development

No branches or pull requests

8 participants