From 92879e4d162a3058febf4f965baf8e7a45a40bfe Mon Sep 17 00:00:00 2001
From: Marco Ciampa <ciampix@libero.it>
Date: Tue, 27 Sep 2016 17:38:09 +0200
Subject: [PATCH] Added useful tool description for translators

---
 docs-versioning.adoc          |  9 ++++
 translation_instructions.adoc | 90 ++++++++++++++++++++++++++++++++++-
 2 files changed, 98 insertions(+), 1 deletion(-)

diff --git a/docs-versioning.adoc b/docs-versioning.adoc
index 3e52c66e..9465cd6d 100644
--- a/docs-versioning.adoc
+++ b/docs-versioning.adoc
@@ -123,3 +123,12 @@ in the way they want it.
 I propose that we make cmake be able to generate a release tarball
 where it only includes the relevant versions of the files that is
 needed to generate the documentation output.
+
+== Useful hints for translators
+
+The documentation branching sometimes creates more work of what it should
+necessary to translators. Please consult the
+https://github.com/KiCad/kicad-doc/blob/master/translation_instructions.adoc[translators
+guide] for a hint on some tools that should make life easier to
+translators.
+
diff --git a/translation_instructions.adoc b/translation_instructions.adoc
index cb6f5127..31aa74a5 100644
--- a/translation_instructions.adoc
+++ b/translation_instructions.adoc
@@ -1,7 +1,9 @@
 KiCad documentation translation
 ===============================
 
-To start translating these documents in a new language, follow these steps:
+== Starting a translation from scratch
+
+To start translating the KiCad documentation in a new language, follow these steps:
 
 1) read the README.adoc for the preliminary requirements
 
@@ -85,4 +87,90 @@ content of the build dir with:
 
 ====
 
+
+== Translating more than one doc branch at a time
+
+With the new branching policy of KiCad documentation, life could be
+hard, especially if the stable branch of the documentation in your
+tongue is not already completed.
+
+
+In this case you would want to translate the stable branch of the
+documentation and add all unupdated strings and screenshots to the
+development ``rolling'' branch.
+
+Git has this beautiful command that is ``cherry-pick''. This command
+enable the user to pick a commit from a branch and apply this commit to
+another.
+
+What we want to do is to translate and commit the translation update on
+the stable branch of the documentation and then pick this commit and
+apply it to the new dev branch of the documentation. 
+
+Then, let the gettext suite commands purge the modified strings but
+keeping the unchanged ones.
+
+This is all wonderful but sadly the merge command does not work well with 
+`.po` files due to the large percent of comments that change with trivial
+changes in source making the merge conflicts something neare a nightmare.
+
+Again, the flexibility of git saves our days of works letting to
+customize the merge in a file-type per file-type basis.
+
+All we have to do is to tell git to use a special po aware merge command
+instead of the classic one: this is what po-merge is for. po-merge is
+part of the https://github.com/mezis/git-whistles[git-whistles] and under
+Linux is installable with just:
+
+ sudo gem install git-whistles
+
+If some errors arise, try updating gem first:
+
+ sudo gem update --system
+
+and then retry the installation. Then you will have a new command:
+
+ git merge-po <ancestor> <left> <right>
+
+But you don't have to call this directly, you just have to configure your
+git environment: add this to your .git/config:
+
+  [merge "pofile"]
+    name = Gettext merge driver
+    driver = git merge-po %O %A %B
+
+and add this to .gitattributes or .git/info/attributes:
+
+  *.po   merge=pofile
+  *.pot  merge=pofile
+
+Or globally
+
+Add to ~/.gitconfig:
+
+  [core]
+    attributesfile = ~/.gitattributes
+  [merge "pofile"]
+    name = Gettext merge driver
+    driver = git merge-po %O %A %B
+
+Create ~/.gitattributes:
+
+  *.po   merge=pofile
+  *.pot  merge=pofile
+
+Then try:
+
+ git checkout 4.0
+ git add ...
+ git commit -m "Translation update..." 
+
+write down the commit hash or check it with `git log`
+
+ git push
+ git checkout master
+ git cherry-pick <commit>
+
+Done!
+
 Happy translation!