git-manpages-l10n: how Git's manual pages get translated

A translation project that is not about translating Git

This project holds the translations for the documentation of Git, and the document describes how you can contribute to the effort of enhancing the language coverage and maintaining the translation.

The first clarification in the README is important, because the repository name invites the wrong reading. This project is not about translating Git itself, although the base content, the manpages, is extracted from it. Git uses a workflow for translations which is different from the one used by Git Manpages, and the project points to its own specific instructions instead.

That difference is the whole design decision here. The Git project itself manages its own translations with a workflow built for the Git project. The manpages, which are written in Asciidoc with some custom macros, are extracted and handled here by a different mechanism so that the translations can be maintained in a way that survives the upstream project changing.

The project is GPL-2.0 licensed, the primary language is recorded as Python because of the helper scripts, the last push was on 2026-10-11, and there are no GitHub releases, which is what you would expect from a repository whose content is a set of po files rather than a program.

The topic tags are documentation, git, hacktoberfest and l10n, and the repository layout supports that description: an `en/` directory holding the English Asciidoc sources, a `po/` directory holding the gettext files, `scripts/` for the helper tooling, `ci/` for the continuous integration setup, an `addenda/` directory, and a `TEAMS` file at the root recording who looks after which language.

po4a turns Asciidoc into po files and keeps the inline formatting

The mechanics of the translation are worth understanding, because they explain why the repository has the shape it has.

The project relies on the Git project itself for the original version of the Git manpages and documents. In order to allow the translations in a maintainable way over the changes to the Git project, the source files are processed with a converter named po4a. This tool converts the source files into gettext po files which can be processed just like gettext internationalization files.

The source files for the manpages are written in Asciidoc with some custom macros. Although the documents are split into simple paragraphs by po4a for translations, Asciidoc inline formatting marks are retained. That is the detail that makes the approach work. A translator sees prose broken into paragraphs, which is what a gettext tool expects, but the formatting marks survive so that the rendered output still has bold, italics and code formatting in the right places.

The two character language translation codes are defined by ISO_639-1, as stated in the gettext manual's appendix on usual language codes. That is why the file naming convention is `documentation.XX.po` with XX being the locale, and why the README gives examples like `de`, `is`, `pt_BR` and `zh_CN`, which is a hint about the mix of regional variants in the set.

The Makefile shows the same split in build terms. The English sources are `en/*.adoc` with subdirectories for config and includes, the documentation sources are the `en/git*.adoc` files, and the language list is derived directly from the po files present, `ALL_LANGUAGES = $(subst po/documentation.,,$(subst .po,,$(LANGUAGE_PO)))`. A new language therefore appears in the build by existing as a po file, with no separate registration step in the build system itself.

The data flow, and who does what

The README includes an ASCII diagram of the overall data flow, and reading it tells you exactly how a change in the upstream Git project reaches a translated man page.

The steps it lays out are these.

The original documentation files are tagged for a new release. The L10n coordinator pulls from the source and updates the local documentation source files and the message template `po/documentation.pot`, and merges the changes into all the `po/documentation.XX.po` files. Updated files are then available on Weblate.org, and the language team pulls from the Git doc translation repository. The language team updates the message file `documentation.XX.po`. The L10n coordinator pulls from the language team. And the L10n coordinator updates the translated source files for external use.

The loop closes on itself, and the shape of it is the interesting part. Upstream changes do not arrive as a diff to be re-applied to each translation. They arrive as a regenerated message template, which is then merged into every language file at once. A translator who has already translated a string sees it unchanged, and a translator working on a changed string sees only the changed part.

That is the difference between a translation workflow that scales and one that does not, and it is why the coordinator role exists at all. There is exactly one person merging upstream into all the po files, and one person pulling the results back, and the translators in between never have to reconcile two versions of the same document.

The scripts in the repository reflect the same arrangement. There is a `set-priorities` script, a `pre-translate-po` script, an `update-sources` script, a `create_po4a_conf` script and a `generate-make-deps` script, and the Makefile invokes them in the right order for each target, so the coordinator's side is automated even though the human step in the middle is not.

Two ways to contribute, and the project prefers the web one

There are basically two ways to translate the documents, and the README is clear about the preference.

The first uses the standard Git workflow, similar to any software project. The second uses the more accessible web tool at Weblate.org and is the preferred way of contributing.

The Weblate route is the interesting one because of a mechanism that is unusual in open source translation work. The translation files are uploaded to the hosted Weblate website, where contributors can easily translate the documents and use all the helpers that are provided. Contributors to Git manpages translation are asked to acknowledge the project's code of contributors. And the web application handles your submissions and generates a Git commit in the local repository of Weblate after one day of inactivity.

That last sentence is the key. Weblate does not hold the authority to push into the translation repository, so a day's inactivity is treated as the signal that a submission is finished. The commit is then generated on the Weblate side, and the coordinator pulls it in the same way as a contribution from a language team, which is step five of the data flow.

There is one thing a contributor cannot do, and the README is direct about it. You cannot directly create a new language in Weblate by yourself, but you can request the creation of the language to the maintainer. Upon receiving this request, the maintainer will create the po translation file and push it, and Weblate will then update the list of available languages accordingly.

For the Git workflow route, the documentation is more involved because there is a first-time setup to do. If the language you plan to translate is already listed, you can jump to the language's management page and start fixing translations or tackling untranslated content. If a dedicated team exists for your language, which you check in the `TEAMS` file in the repository directory, you fork the dedicated repository; otherwise you fork this project and start translating. When committing, you are asked to follow the code of contribution and add your Signed-off-by line. And if there are multiple contributors for the same language, you are asked to coordinate and nominate a team leader, so that the L10n coordinator only needs to interact with one person per language.

Adding a language by hand, and building the result

The manual route for a first-time language is a sequence of concrete steps, and it is worth reading because it shows what the generated files look like.

You initialise the translation po file by running `msginit --local=XX` in the `po/` directory, where XX is the locale, for example `de`, `is`, `pt_BR` or `zh_CN`. Then you pre-translate the file for unchanged strings with `scripts/pre-translate-po po/documentation.XX.po`, which creates a file corresponding to the newly created translation and makes it ready for your translations.

Then you edit the automatically generated copyright info in the new `documentation.XX.po` to be correct. The example given is for Icelandic, and the diff shows what changes: the placeholder line for the package name becomes a line naming Git documentation, and the copyright holder line is replaced with the real name and address.

There is a second automatic substitution to do as well. The reference to PACKAGE VERSION in the PO header entry has to become just Git Documentation, done with a one line perl in-place edit:

    perl -pi -e 's/(?<="Project-Id-Version: )PACKAGE VERSION/Git
    Documentation/' documentation.XX.po

Once the translation is done and tested, you commit the `documentation.XX.po` files and ask the L10n coordinator to pull from you.

Testing your changes is the part that catches the errors, and the tooling for it is specific. Before being able to compile the documents you need a working compilation toolchain, which you get by running `sh ci/install_po4a.sh` to install a patched version of po4a and `bundle install` to install asciidoctor. Before you submit your changes you run `bundle exec make all`. On systems with GNU gettext, which is everything except Solaris, and with po4a, this will try to merge the translations with the source asciidoc files.

The patched po4a is the detail to notice. The upstream tool does not quite do what this project needs, so the project ships a patch and installs that version rather than the stock one, and the CI script exists to do it. The `Gemfile` at the root and the `bundle install` step are the Ruby side of the toolchain, and `asciidoctor-extensions.rb` in the repository root holds the custom macros the source files use.

Editorial conclusion

Adopt this workflow, or one like it, if you maintain a documentation set that is translated in many languages and upstream moves faster than your translators can follow, because the gettext and po4a arrangement lets a coordinator re-merge upstream text while keeping the translated strings. Do not start a new language in Weblate yourself, since the maintainer has to create the po file first, and check first which of the two contribution routes suits you, because the web tool is preferred while the Git workflow is the fallback for contributors who cannot or do not want to use Weblate.

Frequently asked questions

Official sources

1. Issues
2. jnavila/git-manpages-l10n on GitHub
3. License: GPL-2.0
4. README