Collaborative Document Editing with svk
Pages: 1, 2
Suppose that after some hard work, you have finished the translation. Someone has revised the original text to fix some wording:
Translating documents is really hard work and you deserve a better tool. The tool should be able to tell you which part of the original text is updated, so you could adjust the translation accordingly.
The first line didn't change.
To bring this change to the translated version, use
% svk smerge -C //articles/article-en.txt article-zh.txt Auto-merging (3, 5) //articles/article-en.txt to //articles/article-zh.txt (base //articles/article-en.txt:3). C article-en.txt New merge ticket: 8712955e-75da-0310-a94d-be098d1d806e:/articles/article-en.txt:5 1 conflict found.
The smart merge command finds the last merge point automatically, so you
don't have to worry about those funny revision numbers above. In this case, for
the first time a merge is performed, the merge base is the point at which you copied (or
branched) the original file. Run the
often to update and commit article-en.txt, as catching up with the
original text frequently is easier than doing a huge update some months later.
-C option here means to check what the
command will do. It has found a conflict. Run
-C, which makes modifications to article-zh.txt.
You'll see the content like this:
Figure 1. Conflicts after a merge.
The first line, which you have translated and whose original text has not changed, remains there. The second part, as you can see, now consists of a marker for the conflict, which shows your version with the original text that the translation was based on and, finally, the new version of the original text.
In a document longer than just four lines, svk will merge all the other changes that you haven't translated into the latest version of article-en.txt. This saves a lot of time tracking and copying them.
Now you can proceed to update the translations in the file. It should be relatively easier, since you can read the changes made in the original text while modifying your translation side by side.
Before you can commit the file again, you have to mark the conflicts that svk just found as resolved:
% svk resolved article-zh.txt /home/clkao/articles/article-zh.txt marked as resolved.
Why? Consider that you are using svk the usual way--managing source code. The funny conflict markers won't mean much to any compiler, and committing them will result in an inconsistent state where your software won't build. This is not the case for document translation! If you can't finish updating all those conflicts for now, it's rather convenient to commit the work in progress, leaving the conflicts there for resolution later. In the event that you've set up a Subversion server, other people in the same group translating the same document may be able to finish the merge easily. This makes collaborative translation possible.
Using Merge Tools
A few tools allow interactive merges like the one we did earlier manually. svk supports Emacs (EDiff), meld, and FileMerge.App on Mac OS X. You can easily call them as external merge tools for conflict resolution. We will use Emacs as the example here.
Find the svk-merge-emacs tool under the utils directory in
svk distribution. Also remember to put svk-ediff.el in
emacs lisp directory.
SVKMERGE environment variable controls the external merge
% export SVKMERGE=svk-merge-emacs % svk smerge //articles/article-en.txt article-zh.txt Auto-merging (3, 5) //articles/article-en.txt to //articles/article-zh.txt (base //articles/article-en.txt:3). Started 5427, Try 'kill -USR1 5425' to terminate if things mess up
svk smerge command now waits for the external merge tool.
An Emacs window will pop up in ediff-merge-with-ancestor mode.
$$ to ignore obviously merged chunks, as you likely care only about conflicts. Use the
p keys to
navigate between chunks that need merging. Press
+ to expand a
chunk to combined mode, which consists of the base text:
Figure 2. Merging with Emacs.
Comparing the ancestor and variant B parts by eye is
sometimes tiring. In that case, mark the ancestor text and press
=b to compare it with the revised master text in buffer B:
Figure 3. Viewing detailed changes.
This should give you a clearer idea about what has changed. When you decide
how to reflect the change in your translation, press
a to load the
translated text back into the merging into buffer, then update it.
If the paragraph has had a complete rewrite and is far different from the
old one, press
b to load the new version and translate it from
When you are done with all the chunks, press
q to finish the merge session.
svk smerge will finish the rest of the merge. You
can examine the change you made to article-zh.txt with
Figure 4. The updated translation.
svk commit as usual when you are satisfied with it.
Limitations of svk Translation
svk translation works best if there are markups between sections or paragraphs, as that makes it easier for external merge tools to find corresponding paragraphs.
If the original article moves paragraphs around, you will have to track them manually. You will see in the conflict marker that the moved paragraph becomes empty, and the new location with the moved text will have an empty base and translated text.
Using branch and merge in svk as presented in the article can apply to any other version control system that supports branching and merge tracking and, perhaps, external merge tools.
Translation is an extreme type of article editing. The concepts here can
also apply to conventional editing. Make a branch for the article that you
are proofreading. When the author sends an updated version, you can
smerge the changes painlessly, retaining the modification you made, or
Chia-liang Kao is the original author of svk and the Perl bindings for Subversion.
Return to ONLamp.com