Repository navigation
Action plan to salvage pt-br translation #130
Description
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:
- 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)
- 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
- Ensure the build is functional in the new branch
- Create translation issues for chapters or chapter sections (evaluate the amount of text) to guide the initial work.
- 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?
Activity
jnavila commentedon Jan 15, 2025
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.
faraujo427 commentedon Dec 12, 2025
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 commentedon Dec 12, 2025
Nothing on my side. The Progit book is more and more out of sync with the actual state of the development of Git.
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.
faraujo427 commentedon Dec 12, 2025
So there's not much to gain on resuming the translation effort?
jnavila commentedon Dec 12, 2025
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
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.
faraujo427 commentedon Jan 6, 2026
@carlosschults and @sergiocabral , do you still have plans to resume the effort, or are there other active PR approvers?
PS: some broken links in the pt-br translation are also broken in the original
sergiocabral commentedon Jan 7, 2026
We had set a plan for this last year of 2025, but I think I was to blame for not helping as much with the initiative. The demands of the work were enormous here and I couldn't manage it.
Efforts like yours are very welcome and help us see that we are not alone.
I will organize myself this week to return. Please remind me here.
wellyton-xs commentedon Jan 7, 2026
I found this translation while searching for in-depth material on Git for my thesis project. When I saw that the Brazilian Portuguese translation of chapter 4 of the book was incomplete, I felt it was my duty, since it was so useful to me, to contribute to the translation. It was only after submitting my contributions that I found this issue and, even better, recent activity about bringing the project back to life.
I would like to offer my support for future translations and efforts, with translations and corrections! I hope to be helpful.
sergiocabral commentedon Aug 20, 2026
Abri o PR #138 em rascunho para materializar esta reorganização.
A proposta refaz a árvore pt-BR a partir de
progit/progit2@a013e323, remove o legado estrutural e mantém o conteúdo em inglês nesta primeira etapa. No teste local, o estado atual parava no EPUBCheck com 612 erros; a nova base conclui o build e fica apenas com os mesmos dois erros de validação estrita existentes no repositório inglês.Depois da revisão dessa base, a ideia é retomar a tradução em PRs pequenos e dedicados, aproveitando com cuidado o trabalho anterior.
sergiocabral commentedon Aug 20, 2026
TL;DR: The recovery plan discussed in this issue has been completed through #145. The pt-BR repository now mirrors the English structure, builds successfully, and contains a complete AI-assisted Brazilian Portuguese edition. The legacy issue/PR backlog has been cleared, and future work can focus on textual review and corrections. I am therefore closing this issue as successfully completed.
@carlosschults, thank you for opening this issue and helping define the recovery plan. @jnavila, thank you for clarifying the structural and build requirements. I also appreciate the interest and contributions from @faraujo427 and @wellyton-xs.
I took the initiative to rebuild the pt-BR tree directly from
progit/progit2@a013e323. This made the Portuguese repository structurally consistent with the English source and restored a reliable build before any new translation work was applied.The work was then completed in #145:
The source cover did not fit the generated page correctly. Since the cover also needed localization, I adjusted its canvas dimensions and aspect ratio while preserving the original composition, and translated only the applicable labels. The resulting book now has a properly fitted Brazilian Portuguese cover.
All earlier translation-related issues and pull requests have been resolved or closed. There is no remaining legacy backlog: #145 is the single active PR and contains the completed recovery work. The repository is now organized and ready for continued maintenance, with future contributions focused primarily on textual review, fluency, consistency and corrections rather than initial translation.
The PR is explicitly linked to this issue, so I am closing #130 as completed.
sergiocabral commentedon Aug 20, 2026
Separately, @ben and @jnavila: I noticed that progit/progit2 currently has 171 open issues and 48 open pull requests. I understand that these numbers alone do not describe the project's priorities or maintainer availability, but I would be glad to help with triage, review and maintenance work there as well.
If the work completed in this repository demonstrates a useful level of care, please consider allowing me to contribute more directly to the English repository. I would be happy to begin through regular contributions and, if you consider it appropriate, receive write access or take on broader maintenance responsibilities over time. There is no expectation on my part; I am simply volunteering to help wherever it would be useful.
Move pt-br book translation to Full translations (#2196)