96 lines
No EOL
6.5 KiB
HTML
96 lines
No EOL
6.5 KiB
HTML
<!DOCTYPE html>
|
|
<html lang='en'><head><meta charset='utf-8' /><meta name='pinterest' content='nopin' /><link href='../../../../static/css/style.css' rel='stylesheet' type='text/css' /><link href='../../../../static/css/print.css' rel='stylesheet' type='text/css' media='print' /><title>Mercurial Workflows: Translation Branches / Steve Losh</title></head><body><header><a id='logo' href='https://stevelosh.com/'>Steve Losh</a><nav><a href='../../../index.html'>Blog</a> - <a href='https://stevelosh.com/projects/'>Projects</a> - <a href='https://stevelosh.com/photography/'>Photography</a> - <a href='https://stevelosh.com/links/'>Links</a> - <a href='https://stevelosh.com/rss.xml'>Feed</a></nav></header><hr class='main-separator' /><main id='page-blog-entry'><article><h1><a href='index.html'>Mercurial Workflows: Translation Branches</a></h1><p class='date'>Posted on June 11th, 2010.</p><p>This entry is the third in my series describing various <a href="http://mercurial-scm.org/">Mercurial</a> workflows.
|
|
The <a href="../../02/mercurial-workflows-branch-as-needed/index.html">first</a> describes the simplest one: branching only when
|
|
necessary, and the <a href="../../05/mercurial-workflows-stable-default/index.html">second</a> describes the classic "default
|
|
and stable" workflow.</p>
|
|
|
|
<p>I've been experimenting with another workflow lately and it's proven itself to
|
|
be pretty useful, so I wanted to write about it.</p>
|
|
|
|
<ol class="table-of-contents"><li><a href="index.html#s1-a-real-example">A Real Example</a></li><li><a href="index.html#s2-branch-structure">Branch Structure</a></li><li><a href="index.html#s3-linebreaks">Linebreaks</a></li><li><a href="index.html#s4-a-work-in-progress">A Work in Progress</a></li></ol>
|
|
|
|
<h2 id="s1-a-real-example"><a href="index.html#s1-a-real-example">A Real Example</a></h2>
|
|
|
|
<p>I created the <a href="http://hgtip.com/">hgtip.com</a> site a while back as a resource for all those tiny
|
|
little tips that make working with Mercurial easier. People seemed to like it
|
|
and eventually there was some interest in translating the site to other
|
|
languages.</p>
|
|
|
|
<p>The site itself is a collection of flat files that are run through <a href="http://hyde.github.io/">Hyde</a> to
|
|
generate a set of static HTML pages. The content of the site is held in
|
|
a <a href="http://mercurial.selenic.com/wiki/subrepos">subrepo</a> which people can clone to contribute without worrying about the
|
|
site's structure.</p>
|
|
|
|
<p>When coming up with a strategy for managing translations I had the following
|
|
requirements:</p>
|
|
|
|
<ul>
|
|
<li>Translations need to be version controlled. Version control is extremely
|
|
helpful, so we need to use it.</li>
|
|
<li>Contributing translations should be (almost) as easy as contributing to the
|
|
main site. I didn't want it to be much more work than a simple clone, commit,
|
|
push.</li>
|
|
<li>I make typos when creating tips, and sometimes people comment with ideas
|
|
I hadn't thought of, which I then add to the tips. When the main (English)
|
|
version of a tip is updated it needs to be easy for translators to see
|
|
exactly what changed so they can update their translations.</li>
|
|
</ul>
|
|
|
|
<p>After thinking about the problem for a while I settled on using Mercurial's
|
|
named branches to manage translations.</p>
|
|
|
|
<h2 id="s2-branch-structure"><a href="index.html#s2-branch-structure">Branch Structure</a></h2>
|
|
|
|
<p>For the content of hgtip I (currently) have three branches: <code>default</code>, <code>ja</code>,
|
|
and <code>de</code>.</p>
|
|
|
|
<p><code>default</code> contains the English version of the tips, while <code>ja</code> and <code>de</code> contain
|
|
the Japanese and German translations.</p>
|
|
|
|
<p>As other people translate the existing tips they commit to the appropriate
|
|
branch. When I publish the site to the server I can easily update to each
|
|
branch to render the content, one at a time.</p>
|
|
|
|
<p>When I add new tips I commit them to the <code>default</code> branch and merge <code>default</code>
|
|
into all the translation branches. This adds the new file to the translation
|
|
branches so it gets rendered (in English) on the other versions of the site.</p>
|
|
|
|
<p>When a translator is ready to translate any new tips, they can run <code>hg log -b
|
|
THEIRBRANCH</code> to see what's been merged into the branch and find the tips they
|
|
need to translate.</p>
|
|
|
|
<p>Here's a diagram to help explain what's going on. As new tips are added they
|
|
get merged into the translation branches. When a translator has time to
|
|
translate a tip, they commit to their branch.</p>
|
|
|
|
<p><img src="../../../../static/images/blog/2010/06/translation-branches.png" class="diagram" alt="Translation Branching Diagram"></p>
|
|
|
|
<h2 id="s3-linebreaks"><a href="index.html#s3-linebreaks">Linebreaks</a></h2>
|
|
|
|
<p>There's one small issue that arises with a workflow like this, and it happens
|
|
when I fix a typo (or add an update) in an existing tip.</p>
|
|
|
|
<p>If I fix a typo in <code>beginner/sometip.html</code>, it will cause a merge conflict when
|
|
someone tries to merge it into a translation branch. This is generally a good
|
|
thing because it shows the translator where the change was. They can then fix
|
|
the conflict by changing the translation, commit, and everything works.</p>
|
|
|
|
<p>The tricky part is that Mercurial will only show line-by-line diffs. If each
|
|
paragraph of a tip is a single line, Mercurial will only tell you the paragraph
|
|
that changed. For large paragraphs this is annoying because you need to figure
|
|
out by hand exactly which word was modified.</p>
|
|
|
|
<p>To avoid this I always make sure that lines are hard-wrapped with linebreaks.
|
|
You can do this easily by pressing <code>Ctrl-Q</code> in TextMate or using <code>gqip</code> in vim.
|
|
I'm sure Emacs has an equivalent as well.</p>
|
|
|
|
<p>This doesn't affect the output because hgtip uses <a href="https://daringfireball.net/projects/markdown/">Markdown</a> and Markdown
|
|
ignores single linebreaks. If you're using another markup language this might
|
|
be a bigger problem for you than it is for me.</p>
|
|
|
|
<h2 id="s4-a-work-in-progress"><a href="index.html#s4-a-work-in-progress">A Work in Progress</a></h2>
|
|
|
|
<p>This is the first time I've ever used this branching structure and I haven't
|
|
hear about other people using it. I'm sure there are some tricks that might
|
|
make things smoother, so if you have any advice I'd love to hear it!</p>
|
|
</article></main><hr class='main-separator' /><footer><nav><a href='https://github.com/sjl/'>GitHub</a> ・ <a href='https://twitter.com/stevelosh/'>Twitter</a> ・ <a href='https://instagram.com/thirtytwobirds/'>Instagram</a> ・ <a href='https://hg.stevelosh.com/.plan/'>.plan</a></nav></footer></body></html> |