Contributing to translation

[max123kl]

@jnavila
Following my promise during our conversation on progit2 last October, I would like to contribute to the German translation of the "git-manpages".
I used Weblate a few days ago to translate a few strings and also corrected some typos.
So far I do not really understand the workflow here.
However, my changes don't appear on https://git-scm.com/docs.
Is there another site where I can check the output?

A second problem, even more serious to me, is that the order of the strings to be translated is completely confusingly composed coming from various files.
In order to be able to consider the context, when translating, I usually prefer to proceed file by file.
Is there a setting at Weblate that enables something similar or is there another way to contribute here?

[rimrul]

The changes on https://git-scm.com/docs are a bit slow to appear and require a file (and it's parent files) to be 80% complete to appear.

We have two contribution Workflows. Weblate and Github.

The strings on Weblate are ordered by a priority flag that we assign based on files they appear in. We can't really keep them ordered beyond that, though.

The Github workflow is a little more complicated for beginners than the weblate workflow, but also gives you more freedom how you go through the po file. Seeing as you've allready worked on progit2, it shouldn't be too big of a hassle, though.

The Github Workflow

The Github workflow is based on the translation workflow for git. There's a L10n coordinator (Jean-Noël Avila) that pulls changed english documentation (into en)from the git.git repository (usually after a release) and generates a .pot file. The workflow then has language coordinators that pull the changes from the L10n coordinator and update the po file for their language. Then the language teams (currently FR (Jean-Noël Avila (Language ccordinator) and Adrien Ollier) and DE (you and me)) get their copy from the language coordinator and start working on their local copy.

To build your local changes you'll need to run these commands to get a working
compilation toolchain:

$ sh ci/install_po4a.sh # install a patched version of po4a
$ bundle install        # install  asciidoctor

You can then build the translated documents running

$ bundle exec make all

On systems with GNU gettext (i.e. not Solaris) and po4a this will try
to merge translations with the source asciidoc files into translated
asciidoc files and compile them to manpages.

Then you can check the translated manpages, for instance for git add
in French:

$ man -l fr/git-add.1

and verify how your translated manpage is rendered.

po4a defaults to just compiling files that are 80% completed, but you can reduce that number in your local po4a.conf for testing.

There's also a script to pretranslate the simple repetitive things scripts/pre-translate-po it can be used to "translate"the things that are supposed to stay the same in all languages (i.e. strings that just contain a link to another man page) and strings that just need a short part translated, but on multiple similar occurences (regex based translation patterns).

Once your're happy with your changes you're then supposed to submit your changes to the language coordinator for your team and they'll submit the teams work on to the L10n coordinator.

The Weblate Workflow

Weblate pulls this repository and fills it's database from po/documentation.*.po and orders the strings based on priorities we assigned using scripts/set-priorities. The priorities boil down to what files the string appears in.

If it appears in "git-init.txt", "git-clone.txt", "urls.txt" or "git-add.txt" it's priority 300.

If it doesn't appear in a higher priority file, but appears in "git-status.txt", "git-diff.txt", "diff-options.txt", "diff-format.txt", "git-commit.txt", "date-formats.txt", "i18n.txt", "git-reset.txt", "git-rm.txt" or "git-mv.txt" it's priority 280.

If it doesn't appear in a higher priority file, but appears in "git-show.txt", "pretty-options.txt", "pretty-formats.txt", "diff-generate-patch.txt", "git-log.txt", "line-range-format.txt", "rev-list-options.txt", "git-shortlog.txt", "mailmap.txt", or "git-describe.txt" it's priority 260.

If it doesn't appear in a higher priority file, but appears in "git-branch.txt", "git-checkout.txt", "git-merge.txt", "merge-options.txt", "merge-strategies.txt", "config/merge.txt", "config/fmt-merge-msg.txt", "mergetools-merge.txt", "git-mergetool.txt", "git-stash.txt", "git-tag.txt" or "git-worktree.txt" it's priority 240.

If it doesn't appear in a higher priority file, but appears in "git-fetch.txt", "fetch-options.txt", "pull-fetch-param.txt", "urls-remotes.txt", "transfer-data-leaks.txt", "git-pull.txt", "git-push.txt", "git-remote.txt" or "en/git-submodule.txt" it's priority 220.

Otherwise it's priority 100.

You can then edit the translations in a web interface and weblate will collect your changes into commits (I think it commits them every 24 hours). Weblate occasionally pushes the commits back to github.

It also allows suggestions for translations. These don't make it back to github, unless they're accepted on weblate.

The How things get to git-scm.com

Jean-Noël Avila occasionally builds all translations and pushes the resulting txt and html files to https://github.com/jnavila/git-html-l10n.
git-scm.com then runs a nightly rake job that picks up the .txt files.

---

I'll edit this comment quite a bit to expand on both workflows and how docs get to https://git-scm.com/docs.

[max123kl]

Thank you for the detailed commentary.
Allow me to summarize, if I have got it right.

The translations of a particular language are always grouped together in a single file (documentation.XX.po), right?
When I want to contribute via GitHub, I do modify this file and start a PullRequest, OK?

Actually I'm still editing on a Win7 machine, but will have to upgrade or migrate to Debian/buster soon.
If I want to generate the translated documents locally, I have to install po4a, right?
I don't want to install any additional software on the old computer. So for the time being, I only have the option of using Weblate.

I now understand the Weblate workflow better. But I can't figure out why the strings can only be sorted by priority, whereas the individual files are only published if they have reached 80% completion.

I would like to attempt now to complete the translation for certain files.
I guess the only option I have left on Weblate is the search function. But how can I filter and display all strings that come from a single file (e.g. "en/git-add.txt")?

[rimrul]

The translations of a particular language are always grouped together in a single file (documentation.XX.po), right?

Yes, all strings are in that file.

Actually I'm still editing on a Win7 machine, but will have to upgrade or migrate to Debian/buster soon. If I want to generate the translated documents locally, I have to install po4a, right?

Yes, po4a and others. TBH I'm not sure if the documents can be built on windows without using something like WSL/Cygwin/MSYS2.

I now understand the Weblate workflow better. But I can't figure out why the strings can only be sorted by priority, whereas the individual files are only published if they have reached 80% completion.

The files published to git-scm.com come from the Github workflow and are generated using po4a. That's where the 80% come from. The sorting is done by weblate internally.

how can I filter and display all strings that come from a single file (e.g. "en/git-add.txt")?

You can add location:en/git-add.txt to your search. To get all untranslated strings from git-add.txt you'd search for state:empty AND location:git-add.txt

[jnavila]

Hi,

@rimrul could not have better explained the workflows. Just a precision: I usually push down updates from upstream into the po files also.

There are some other advantages to translating on weblate: the help of automatic translation engines.

You experienced that Weblate proposed some seemingly unrelated strings to be translated/reviewed because I just updated the files with the latest 2.26.0 version and some of the high priority already translated strings were slightly modified. That's one of the advantages of this method: the updates to content are tracked by the tool and proposed for review to translators. This way, unlike progit, we always ensure that translators know what needs translation, what needs review, what needs fixing.

Please also note that we follow the Certificate of Origin rule in this project (to match git's rule), so all translators must "Signed-off-by:" their commits. This is done automatically by Weblate.

And last, a 👍 to @rimrul for helping me and teaching just now that you can select strings of one specific file in Weblate!

[max123kl]

@jnavila
Well, that's just learning by doing. With every step it is getting better.
However, it's a different workflow here.
As you might remember, I did a bit of participation in the Joomla v4 documentation. I really liked the fact that the neighboring strings were in reality "neighboring" as well. So you could always watch the context (predecessor and follower).
Here I have to open the source file in a second window, so I can at least read the English version contiguously.

[max123kl]

I am reopening this issue to help new people find out how they can contribute.

[jnavila]

As a side note, po4a is tested on windows (see this file)

[max123kl]

That's not an option for me right now, since:

Actually I'm still editing on a Win7 machine, but will have to upgrade or migrate to Debian/buster soon.