Action plan to salvage pt-br translation

[carlosschults]

People wanting to contribute to the pt-br translation project are familiar with the fact that the translation project is stale, to say the least. There are pull requests that are years old. We understand this causes frustration for new and old collaborators alike, and we are sorry for that.

Currently, these are the problems we have that are preventing us from merging PRs and continuing with the translation:

• Large portions of the book are out of sync with the original version in English, including sections already translated
• We have many broken links/broken references that cause the build to fail
• Due to the broken build, we can accept PRs with translations of new chapters

The Plan

A few days ago, @sergiocabral and I got together to talk about an action plan to salvage the translation, and the following is what we came up with:

1. Create an issue about the topic and start the discussion on GitHub. Find out who are the pull request approvers for pt-br. (This is said issue)
2. Create a new brand to serve as a mirror from the current, up-to-date English version, to serve as a new, temporary master branch to receive new PRs
3. Ensure the build is functional in the new branch
4. Create translation issues for chapters or chapter sections (evaluate the amount of text) to guide the initial work.
5. Mention @user who has previously participated in any translation to evaluate if the translated excerpt remains valid and, if so, bring it to the new branch. If not, evaluate if it can be translated again.

The goal of the above plan is essentially to ensure we have a reliable working build on this new branch, so we can accept new PRs and also use what's already been translated, if it's still valid. Of course, this is based on a premise: that, by creating a new branch whose content is the same as the English version, the build would work, but currently we don't know whether that's true. We don't want the build for this new branch to mess with the publication process, otherwise we could end up inadvertently reverting content already translated, and we wouldn't want that.

Right now, we need feedback from maintainer of the original book. @ben @jnavila any thoughts on the above?

[jnavila]

To be honest, I haven't given time to the translations of progit for quite some time. Some translations break the build, but this is not beyond repair. Fixing the bad links is quite straightforward.

As to whether restarting from scratch is a good idea, my feelings are mixed. The work already done should not be completely wasted. A careful review of the existing translation side by side the latest original would surely mean less work. The big problem with the current process of translation is that it is made in files which are matching the original, but this makes tracking changes very difficult over time. Hence, the discrepancies that are present in almost all the translations of Progit.

If restarting from scratch is your option, I would advise to work similarly to what I did for the manpages where I used po4a to extract the strings from the files and work with po files. This way, you can use dedicated tools to manage the translation and easily track changes and report them when they occur in the original text. The workflow is more indirect, but more sustainable in the long term.

[francilioaraujo]

Any update on this action plan?

@jnavila I saw the workflow using po4a and I think it is a good one, either using weblate, or directly translating po files.

I also thought about changing the structure of the original files in this repo. As of today, only the book folder is held. Multiple asc files and images are kept outside, maybe even getting lost during translation effort. Maybe we can think of structuring the original files on some other way.

[jnavila]

Any update on this action plan?

Nothing on my side. The Progit book is more and more out of sync with the actual state of the development of Git.

I also thought about changing the structure of the original files in this repo. As of today, only the book folder is held. Multiple asc files and images are kept outside, maybe even getting lost during translation effort. Maybe we can think of structuring the original files on some other way.

The structure of the translated book must mimic the one of the original progit directory so that it can be parsed by the scripts of git-scm.com. Apart from this requirement, there is no constraint on the structure.

[francilioaraujo]

The Progit book is more and more out of sync with the actual state of the development of Git.

So there's not much to gain on resuming the translation effort?

[jnavila]

I was a little too harsh with the Progit book. Most of the content is still relevant for understanding the core of the tool. But

• There are more and more other tools out there that help people overcome its complexity for everyday usage
• Some additional commands have been developed for the core Git to simplify its command line interface: git switch, git restore, etc. And more are coming to help rewrite history. In this sense, what is explained, while still in use, is no longer how we would teach to a newcomer.

I'm pretty sure Ben would welcome PRs which would rewrite these parts.