Keeping on the roll of the posts about the repo split, templates, and metadata, Software Carpentry now needs to consider how to handle translated lessons. The core Software Carpentry lessons have be translated by bilingual instructors into Korean produced by Victor KC Lee (and friends) and Spanish by Francisco Navarro (and friends). With the upcoming repo split, I think its a good time to examine the various options of how we might handle translations generally.
Option 1: Translations Live Within the Lesson Repo
The first method of handling translations is to introduce
translations directory to the existing lesson
templates. Under this directory would live translations other than
original lesson using the ISO two-letter language code. The contents
of these directories would be otherwise identical to those of the
host lesson. This is how the Francisco has implemented his
translation, on a fork of the
repo. The ProGit Book
initially started out with this implementation, later moving to
One possible drawback to this implementation is that original and
translated lessons can drift apart with no indication of where the
changes happened. Since most instructors will be monolingual, they
diff the content. Since this lesson would live
inside the official Software Carpentry structure, it would have a
certain endorsement associated with it.
Option 2: Translations Live Within a Separate Branch
Branches could be created of the form
similar naming from the existing lessons. This would improve the
ability to track the master language of the lesson and rebase
changes (which would then need to be translated) as the lesson is
This implementation would resolve the
diff issue in
Option 1, allowing comparison of line-by-line changes, even if the
content isn't understood. These translations, again living within an
official repo, would have certain endorsement.
Option 3: Translations Live Within a Forked Repo
Repositories containing translations could be forked from the main lesson and be maintained separately from the original. Changes would have to be merged from upstream and then translated.
There are some examples of this implementation being successfully used, most notably the ProGit book (thanks to W. Trevor King for the pointer). The forked repos are kept in sync with the upstream master book, and then translation commits are layered on top, for a sense of what that looks like, see progit-fr.
Forked repos could exist inside or outside the Software Carpentry organization, allowing for both officially endorsed and unofficial translations of lessons. If such translation efforts are wildly successful, this method would result in a massive proliferation of repositories, multiplying the increase due to the repo split.
How Official is a Translation?
Integrating the translations into the lesson repository, either as Option 1 or Option 2, lends a certain endorsement of the quality and completeness of the translation. This may impose a burden on the lesson maintainers to either translate themselves (in the case where they have the ability) or attempt to seek out translators to maintain existing material. Barring that, they will have to decide when the core lesson has diverged too much from a translation, and "depreciate" the material.
Handing Translations on the Site
Beyond storing translated lessons and keeping them in sync, we may
want to render the lessons on the main Software Carpentry site. The
existing lessons are rendered on the site under the
v5/novice/lesson. The existing pathing can be
slightly modified to add the ISOCODE for the translation
v6/ISOCODE/novice/lesson. The lesson titles and
descriptions will also need a custom page generated in the native
v6/ISOCODE/ so that they're appropriately
indexed by Google.
One last thing to consider is the detection
Accept-Language header sent by user's browser, and
perhaps using that to recommend translated lessons if they navigate
to the core lessons, this could bring larger awareness and usage to
the translations, which is key to attracting more multi-lingual
Gabriel A. Devenyi
TOOLING · TRANSLATION
Dialogue & Discussion
You can review our commenting policy here.