How to transfer accepted and merged commits into foreign language repositories

[max123kl]

What is the best and easiest way, commits that have been integrated here, to include in the foreign-language repos? A few days ago, I already asked this question in the German Repo (https://github.com/progit/progit2-de/issues/33). I hope, someone can help me here.

[ben]

This is a tough question, and one I don't think Git helps you solve.

I don't speak more than a tiny bit of a non-English language, but I like to think about two projects that do approximately the same job, but are written in different computer languages. One is in Java, and one is in Ruby.

So how do you take an improvement from the Ruby code and port it over to the Java codebase? You have to understand what the Ruby patch did, then manually reapply that intent on the Java codebase.

I think that's what you'll need to do here. Maybe you can reference back to the English-language PR when you make the German-language change, but other than that you'll just have to do the work. Git's toolbox doesn't have a tool for this.

[max123kl]

I have to admit that I have hardly any programming knowledge. I don't know Java nor Ruby; I only played a bit with Javascript. If Ruby is as easy to learn as it is often described, I think I will have a try, with some assistance from experienced people.

... but I like to think about two projects ...

Are these already existing projects or do they have to be built from scratch? Can you give me an example, so I can see if I can handle this?

Maybe you can reference back to the English-language PR when you make the German-language change, but other than that you'll just have to do the work.

I don't really know if I do understand you well. What do I have to reference in the English PR? At the moment, my co-maintainer does the commit integration manually. That means he forks the repo, analyzes the received commits and translates the diffs to German. Then the changes are merged. As long as the commits only affect small areas, the effort is manageable. However, I am thinking of possible, more comprehensive commits that could no longer be handled in this way. A possible scenario could be: As you may remember, I collaborated on the SVG images not so long ago. I think this migration will be done sometime. I can't imagine that this can be done manually in the foreign-language repos.

[ben]

I have to admit that I have hardly any programming knowledge.

Aha, then my metaphor probably made no sense. Sorry about that.

At the moment, my co-maintainer does the commit integration manually. That means he forks the repo, analyzes the received commits and translates the diffs to German. Then the changes are merged.

I've never run a translation project, but that sounds to me like the best way to do it.

As you may remember, I collaborated on the SVG images not so long ago. I think this migration will be done sometime. I can't imagine that this can be done manually in the foreign-language repos.

Yeah, there's no easy answer here. Probably the best way forward there is to just copy all the SVG files into the translated repo, and replace all the references to the PNG files the same way we will in the English repo.

[max123kl]

Yes, I understand, thank you for the clarification.

[jnavila]

@max123kl Sorry for the slow reply.

The main advantage of in place translation is the accessibility for new translators. Unfortunately, you pay it when the original is changed, as you experienced. In this set up, there's no automatic way detect and report them.

With the experience of this way of doing, I tried another solution for the git manpages (https://github.com/jnavila/git-manpages-l10n, which looks like more what professional translators do. You extract from the original document the sentences and text segments to translate into a format that is bi-langual (the original and the translation sit together and are linked). Then, you can use a translation tool to translate one by one each segment. After translation, the reverse process can be performed, that injects into the structure of the document the translated segments to create a translated document, just as if it had been translated in place. The good part of this setup is that when the original text is changed, the tools detect which segment has been changed and propose it for translation. The tool takes care of finding the changes. After fixing the missing segments, the new translated document can generated.

There are drawbacks though. First the translation tool shields the translator from the structure of the document and this removes the context of the text to translate. Second, All this workflow requires the use and setup of tools, which prevents new collaborators from joining.

This needs a more solid setup of the repository and the project.

[max123kl]

@jnavila I don't want to compare apples to pears here. The possibility to compare the original text directly with the translation is a great help.

I have contributed a very small part to the translation of the new Joomla V4 documentation. There I can, by using a color code, always recognize if further developments have been made to the original texts. (See)

It is true that a registration is required if you want to contribute. But I don't think that's a too high hurdle, if you seriously want to move something forward.

I am unable to evaluate technically, if this can be a good idea here.

[jnavila]

This is a feature of MediaWiki to manage the translation of pages. The principle is the same as what I described (management of segments of texts) but integrated into the wiki system.

I have no knowledge of anything similar for asciidoc. Changing the text to wikimedia is not an option.

For the git manpages, the choice of po4a was helped by the experience of the Kicad project who uses asciidoc format and po4a for translation. I set up an online translation system by feeding the po file to weblate. This should help translators get the updated segments.

If there's some interest in this solution, I can try to set up a similar system for Progit.

[max123kl]

If there's some interest in this solution, I can try to set up a similar system for Progit.

I think that's a decision Ben or Scott will have to make. If they are planning to publish a third edition of the book, they should think about it. At the moment I can speak only in favor of the German repo. There, only chapter 7 and the three appendices are still to be translated. As long as the number of new commits remains as small as it is now, I don't think a translation system would be an essential help.

Regarding the manpages project, I will contact you there, whenever the translation is finished here.

@ben I had promised, in regard to the SVG conversions, that I would create an Inkscape symbols file. Is it actually required yet?

[jnavila]

I think that's a decision Ben or Scott will have to make.

I don't think they will change the format of the book.

As long as the number of new commits remains as small as it is now, I don't think a translation system would be an essential help.

This is mostly a maintenance stage now.

@ben I had promised, in regard to the SVG conversions, that I would create an Inkscape symbols file. Is it actually required yet?

I have a branch that migrates the book to SVG rendering, but I need yet to set up the corresponding changes in git-scm.com.

[paulolimac]

My 2 cents:

Saw problems, like:

1. I think git(hub), as-is, does not works well, to be a translating system.
2. As a potential translator, I do not need to clone all repos. 2.1. ≃150mb from en-repo + 150mb from l10n-repo, only to edit one asciidoc file.
3. As a potential translator, I work with text, not figures.
4. Repos are out-of-sync, between English-repo and l10n-repoS. 4.1 Put one new comma on en-repo, how is the rule (i.e. script to automate this) to sync all l10n-repos?
5. A lot of UNproductive work, and a lot of UNproductive rework, like: 5.1. Download full repos. 5.2. Edit figures. 5.3. Open/Read 4 versions of the same file (in English asciidoc, in my l10n asciidoc, the English online book, and my local file to be edited). 5.4. Execute git commands in all repos (fetch, push, clone, remove, checkout, branch etc).

What I wanna to do, like a potential translator:

1. See a SIMPLE form-field to type my (SUGGESTIONS OF) translation, to as many sentences as I wanna to do.
2. And a button to click like "SEND and CONTINUE". 2.1. Only that.

What do you wanna from me:

1. Be Productive 1.1. high rate of accepted translations. 1.2. correct old-bad accepted translations. 1.3. don't spam (bad) translations or issues. 1.3.1. but I wanna to send many good and possible translations, for example, to the same sentence.

What do I wanna from you:

1. Give only the text to translate. 1.1. Inform if the text needs (or not) to be translated (like a command, a option, etc).
2. Show a workflow easy-to-go.
3. Help when I made a mistake, or if I'm a newbie.
4. Alert when my translation is in a bad shape.

My solution (in a translator role):

1. Use *.PO/*.POT file. 1.1 It is the standard of software translation. 1.1.1. It is old (mature, bug-free). 1.1.2. have a lot of editors (online, offline, social networks etc). 1.1.3. exist packages for your preferred prog-language.
2. Use a text editor that: 2.1. Be online. 2.2. Be social (many people can edit the same sentence at same time). 2.3. Accept MANY translations (suggestions), from the same person, to the same sentence. 2.4. Associate roles for each people. 2.4.1. Editor-in-chief, editors, reviser-in-chief, revisers, translators, anonymous-translator. 2.5. Easy GUI interface 2.5.1. button to copy-and-paste the English-sentence onto the field to be edited. 2.5.2. list files per sentences like: untranslated, need review, updated, translated etc. 2.5.3. autosave 2.5.4. export my project, my *.PO files, my contacts. 2.5.5. responsive (for mobile use). 2.6. Able to CI. 2.6.1. save translations to a third-party git repo (github, bitbucket etc). 2.6.2. trigger events from-to and to-from editor and my git-repo (pull requests, pushes, others CI sites etc).

PS:

• I have experience with Rosetta translator site, from Launchpad.
• To a translator, it is a good system, but have drawbacks like:
  • old-fashioned (I used it in 2008, and reviewing it now, it stay as the same old thing).
  • no responsive.
  • not so social (we don't have conversations using it, so we use a traditional mail-list).
  • difficult to click (small buttons and links).
• I don't have experience like a reviewer nor a editor.
• And I don't know how is the workflow of Progit book (deploying, releasing etc).
• So my suggestion is:
  • Choose a system from Github Marketplace, under the Localization category.
    • They are CI with Github, using the same Github profile (login).
  • use Github Issue Tracker, if the chosen system haven't a forum (discussion area).
  • Use Github, for the official English book repo, only to:
    • Asciidoc files.
    • *.POT
    • Programming scripts.
    • Documentation (Readme, Contributing, Links to l10n repos, etc).
    • Book and scripts versioning.
    • CI (git-hub-hooks).
    • Discuss/issue about the git explanations in the book.
    • Edit figures.
  • Use github, for the others l10n l18n repos, only to:
    • README.md, CONTRIBUTE.md and, *.PO files; only.
    • CI (git-hub-hooks).
    • Discuss/issue about l10n specific questions (per language).
    • Avoid:
      • Discuss book errors about git explanations (do that here: English official repo).
      • Program/Script (do that here: English official repo).
      • Edit figures (do that here: English official repo).

[paulolimac]

A case:

Github announced that their Help pages were translated to Portuguese.

And they are using one of the solutions from their marketplace.

The selected solution was Gitlocalize.

[rushou]

My 2 cents:

Saw problems, like:

1. I think git(hub), as-is, does not works well, to be a translating system.
2. As a potential translator, I do not need to clone all repos. 2.1. ≃150mb from en-repo + 150mb from l10n-repo, only to edit one asciidoc file.
3. As a potential translator, I work with text, not figures.
4. Repos are out-of-sync, between English-repo and l10n-repoS. 4.1 Put one new comma on en-repo, how is the rule (i.e. script to automate this) to sync all l10n-repos?
5. A lot of UNproductive work, and a lot of UNproductive rework, like: 5.1. Download full repos. 5.2. Edit figures. 5.3. Open/Read 4 versions of the same file (in English asciidoc, in my l10n asciidoc, the English online book, and my local file to be edited). 5.4. Execute git commands in all repos (fetch, push, clone, remove, checkout, branch etc).

What I wanna to do, like a potential translator:

1. See a SIMPLE form-field to type my (SUGGESTIONS OF) translation, to as many sentences as I wanna to do.
2. And a button to click like "SEND and CONTINUE". 2.1. Only that.

What do you wanna from me:

1. Be Productive 1.1. high rate of accepted translations. 1.2. correct old-bad accepted translations. 1.3. don't spam (bad) translations or issues. 1.3.1. but I wanna to send many good and possible translations, for example, to the same sentence.

What do I wanna from you:

1. Give only the text to translate. 1.1. Inform if the text needs (or not) to be translated (like a command, a option, etc).
2. Show a workflow easy-to-go.
3. Help when I made a mistake, or if I'm a newbie.
4. Alert when my translation is in a bad shape.

My solution (in a translator role):

1. Use *.PO/*.POT file. 1.1 It is the standard of software translation. 1.1.1. It is old (mature, bug-free). 1.1.2. have a lot of editors (online, offline, social networks etc). 1.1.3. exist packages for your preferred prog-language.
2. Use a text editor that: 2.1. Be online. 2.2. Be social (many people can edit the same sentence at same time). 2.3. Accept MANY translations (suggestions), from the same person, to the same sentence. 2.4. Associate roles for each people. 2.4.1. Editor-in-chief, editors, reviser-in-chief, revisers, translators, anonymous-translator. 2.5. Easy GUI interface 2.5.1. button to copy-and-paste the English-sentence onto the field to be edited. 2.5.2. list files per sentences like: untranslated, need review, updated, translated etc. 2.5.3. autosave 2.5.4. export my project, my *.PO files, my contacts. 2.5.5. responsive (for mobile use). 2.6. Able to CI. 2.6.1. save translations to a third-party git repo (github, bitbucket etc). 2.6.2. trigger events from-to and to-from editor and my git-repo (pull requests, pushes, others CI sites etc).

PS:

• I have experience with Rosetta translator site, from Launchpad.

• To a translator, it is a good system, but have drawbacks like:

  • old-fashioned (I used it in 2008, and reviewing it now, it stay as the same old thing).
  • no responsive.
  • not so social (we don't have conversations using it, so we use a traditional mail-list).
  • difficult to click (small buttons and links).

• I don't have experience like a reviewer nor a editor.

• And I don't know how is the workflow of Progit book (deploying, releasing etc).

• So my suggestion is:

  • Choose a system from Github Marketplace, under the Localization category.

    • They are CI with Github, using the same Github profile (login).

  • use Github Issue Tracker, if the chosen system haven't a forum (discussion area).

  • Use Github, for the official English book repo, only to:

    • Asciidoc files.
    • *.POT
    • Programming scripts.
    • Documentation (Readme, Contributing, Links to l10n repos, etc).
    • Book and scripts versioning.
    • CI (git-hub-hooks).
    • Discuss/issue about the git explanations in the book.
    • Edit figures.

  • Use github, for the others l10n l18n repos, only to:

    • README.md, CONTRIBUTE.md and, *.PO files; only.

    • CI (git-hub-hooks).

    • Discuss/issue about l10n specific questions (per language).

    • Avoid:

      • Discuss book errors about git explanations (do that here: English official repo).
      • Program/Script (do that here: English official repo).
      • Edit figures (do that here: English official repo).

[jnavila]

The selected solution was Gitlocalize.

Gitlocalize does not support asciidoc.

[paulolimac]

@jnavila , do you think is better to work with *.po files, like your example?

(considering, of course, the backstage to edit and publish the git-book(s)).

[jnavila]

@paulolimac To publish the book, what's only needed is the presence of the translated asciidoc file in a repo, so that they can be extracted, compiled and published. So, the repo containing the *.po files can be the source of a second repo where the translated files are published.

Concerning Weblate, I'm a bit split. On one hand, Weblate limits the number of po files to one, instead of having one po file per asciidoc source; on the other hand, the web interface is really handy for translating the content.

It's really worth it if the source is changing quickly, which I think, is not the case for Progit. In any case, if you prefer to use a *.po file, I'm ready to help you.