Git translation tutorial
Here is an article written by UncleNight for the translators wanting to get started with contributing using Git and send directly their translation to Github. Thank you UncleNight for the big article!
Note: November 2017 , we moved to Gitlab hosted by Framasoft. https://framagit.org/peppercarrot , this move makes this tutorial obsolete. Archived.
One week before each new episode is finished David sends the beta version of it to P&C translation team mailing-list so translators can start working. Considering the fact we've got dozen of episodes drawn by this moment, and there's more to come, there should be clean and polished workflow to make translations easier.
David creates GitHub repository for translators for every episode being drawn – this way translation team can co-operate working on the same project and files at the same time without breaking the whole thing. What's also good about GitHub and Git version control system is that David can focus on the comic itself without worrying about adding new translations received via e-mail – translators can simply join the project anytime to add translation or suggest a correction.
So I'm going to make a quick explanation about how it works and what steps translator needs to jump right in and make translation/correction.
Theory for Cats: Basics of Version Control System
Version Control System, or VCS, is common name for software which takes care about versioning your files: in a nutshell, it's a time machine. You work on file, change its content and save it once in a while – and each time you save the file, VCS creates kind of checkpoint (gamers smile now) for you to be able to get back to it anytime after. Another key thing about VCS is ability to have several “timelines”: if you ever get interested in checking “what if”, you can always restore some old version of file and change it without losing all the work you've done since that moment. Like going back in time and creating alternate history, but safer. It's called “branching”.
But all that stuff usually matters for those who use VCS mainly for development because, obviously, this is what VCS were created for. In our case, what we need from version control is high-quality level of teamwork within the same project. That's why our choice is Git, one of few VCS available. It's flexible and powerful tool, but still very convenient.
It may sound complicated so far, but VCS concepts are really easy to understand, and even regular cat can start working with it almost instantly. Get your claws ready, we'll be only scratching the surface of Git, but even this is enough for our needs as translators.
Three terms you need to know to start working with Git: working directory, staging area, and commit. Imagine a room you're going to work in. There's stuff thrown here and there, it's quite messy since you work in here – this is your working directory, full of things both related to your work and not. On your table there's a box you place finished work in: once step is done, you put result here. It's staging area, space for work prepared to be saved but not saved yet. And finally, there's a large cabinet in the corner – once you decide that your box is full, you put its contents into one of the drawers, add a sticky note label to the drawer and close it. This is commit – a checkpoint for Git. That cabinet I mentioned is Git project, and each drawer contains what's been added since previous commit.
Knowing that, let's take a closer look at workflow with Git:
- we choose working directory and initiate Git project in there (or copy existing one there);
- we make all the necessary changes to existing files, or add new ones, or even delete some – in other words, just do what's needed;
- while working, we tell Git from time to time to mark files which were changed – this way Git stores them in staging area and monitors if they are changed again;
- when we consider the work finished, we tell Git to make a commit – and in order for us to not forget about what were the changes done, Git asks us to add a commit message – non-empty text with description of work done (yeah, that's the sticky note label I mentioned).
Since any cat knows that now it's really easy process, they definitely will ask about that promised teamwork. Well then, let's go to GitHub. GitHub is a website which serves as a centralized storage for your Git projects – with ability to join other projects, share yours, comment and do all the fun social stuff you already do on the Internet. What you need is to register there – basic free account lets you create open source projects and participate in work of others. Register, if you still haven't.
Now it's time to mention that Git is not just VCS, it's distributed VCS – so lot of people can work on the same project and files at the same time without interrupting each other. How? Easily: each participant has his own copy of project, and their work is synchronized when they need it – and in most cases Git can distinguish work of one person from work of another without getting confused, so conflicts are rare (we'll cover this soon).
In this perspective, GitHub is nothing more than just another place to keep your project. Each project you work on is called GitHub repository, and all you have to do is to sync commits between your computer and repository from time to time.
Now, boring part is over. Let's work!
For Those Who Yawn: Party Time
First of all, let's install Git. Linux users can use their system package manager to install git package (command-line only), Windows and Mac users can have GUI-based GitHub application. I'll quickly run through all the necessary functions of GUI version, and give terminal commands for each of them since command-line 'git' tool works on all operating systems (Windows/Mac users get it installed along with GitHub app).
Note: we're going to go the shortest road – I mean, without creating separate branch for our work. It might be not the best idea from developers point of view (and git dao), but it's the quickest way for translators to proceed with git.
First launch: log in, quick configuration, and dashboard.
Now it's time to add P&C translation project to work on it. Before we do it, go to Deevad page on GitHub – there you can see all his repositories:
If you're “authorized” translator, David probably had already added you to the list of accounts allowed to “push” to main branch (called master) – means syncing changes with it. If not – it's still not a problem, you can create your own copy of repository – to fork it. Find that button and fork repository, so it appears in the list of your repositories. Once you're done with your changes, you can create so-called pull request for repository owner to check your changes and merge them with master branch later.
Now as you have forked new translation repository, it's added into your list and visible from GitHub application. Let's clone it (cloning means creating local copy of repository).
Looks like we're ready to make a translation (finally!) - copy source folder (en in our case) to new one with code of language you're going to translate the episode to. In this test example, I use r'lyehian and hope Cthulhu won't wake up from such a sacrilege.
When you think your work is finished, don't forget to edit README.md file and add your name there.
After it's done, open GitHub app: each file you have changed has been monitored and already placed to staging area. All you need to do now is to commit your changes leaving a comment after it.
It's time to push our changes to GitHub repository by pressing “pull request” button (or just synchronize your commit with server using that “sync changes” button).
The Unix way – using command line git tool
On Mac/Windows you have “Git shell” application installed along with GitHub Desktop. On Linux… well, you've already guessed.
Same steps, but in command line. First thing to do – configuration (this is necessary, git won't let you upload your changes anonymously):
$ git config –-global user.name “<preferably your GitHub account name>”
$ git config –-global user.email <your GitHub account e-mail>
Go to your projects directory and clone repository there:
$ cd Projects
$ git clone https://github.com/Deevad/peppercarrot_ep13_translation.git
or get your repository link from GitHub page
$ git clone https://github.com/<your_account_name>/peppercarrot_ep13_translation.git
if you forked Deevad's repository.
Entering our newly cloned repository:
$ cd peppercarrot_ep13_translation
Creating directory to work on translation:
$ cp -r en/ rlyehian
Here goes our translation work and editing README.md. Alas, CLI tool doesn't automatically add our changes to staging area, so we have to do it on our own:
$ git add rlyehian README.md
Checking repository status to make sure everything is going according to plan:
$ git status
Committing changes (this will open default terminal text editor):
$ git commit
Syncing changes with remote end – getting work of others if there's any:
$ git pull origin master
And finally uploading our changes (requires entering your GitHub account credentials):
$ git push origin master
If you were pushing to your fork, you should go to your GitHub page now and make a pull request from there. Otherwise, David already has your translation.
Last thing, but not the least… Sometimes working together on the same file may result in conflict: in our case, translators often edit README.md at the same time – so two different people have two commits where one file is different. When such a conflict happens, you can open conflict file and see there something like this:
* Elven : SomeElvenelle
* R'lyehian : Cthulhu The Ancient
Don't be scared. Git just merged those files together but tried to not confuse you, so it marked the line from other commit as “HEAD” (because translator to Elven language made his commit before you), and marked your lines with short codename of your commit. So basically what you need to do is to remove those marks and make sure both translators are mentioned. Then, tiny bit of magic: make another commit containing your conflict fix and sync your changes. We're done!