Translating & Localizing eZ Publish using GIT

“Forking” eZ Publish

Log-in on github, navigate to https://github.com/ezsystems/ezpublish and click the “Fork” button. This will create a fork of eZ Publish on your own account page (yes, this implies you created your github account beforehand. This is free).
Note: the fork will not update itself with changes done in the original repository, this is done by pulling in changes and pushing it to your fork ( how to do this is explained a bit below).

Cloning eZ Publish

We will use command line here. Do not be afraid of this, the git utility is brilliantly done, and will certainly reconcile you with command line. Graphical interfaces exist as well, like TortoiseGIT for windows, but they are not covered in this tutorial and only those using them will be able to assist you.

Using command line, go to the place you want to checkout eZ Publish, for instance the localhost / www folder that your web server points to, to be able to execute eZ Publish directly for testing. Then, take the following (optionally specifying target <folder_name>, and <GitUser> as your github account alias) :

$ git clone git@github.com:<GitUser>/ezpublish.git [<folder_name>]
$ cd [ezpublish|<folder_name>]

Now we need to add ezsystems as an additional read only remote location, so that changes on the official repository can easily be applied to your own fork. In the following code examples we call it ‘upstream’:

$ git remote add upstream git://github.com/ezsystems/ezpublish.git
$ git fetch upstream 

Optionally we make master branch track upstream, making it easier to pull in changes:

$ git config branch.master.remote upstream 

After that keeping your checkout up to date is a matter of:

$ git pull

Creating and working with your localization branch

Creating a branch is easy, and will let you properly isolate the work on localization to an independent part of your local repository. This amongst other gives you the possibility to work on other things than localization, independently (bug-fixes, features). Here is how to create your localization branch:

Checkout

If you haven't created your localization branch yet:

$ git checkout -b localization upstream/master

If you already have the branch, but only remotely in your fork:

$ git checkout -b localization origin/localization 

And specify that it should track upstream/master:

$ git config branch.localization.remote upstream/master

If you have the branch locally already (check with “$ git branch”):

$ git checkout localization

Start localizing

Once you are all set, you can effectively start localizing eZ Publish.

Installing eZ Publish

Firstly, you will have to install eZ Publish. This helps visually see the changes you are making. As for any eZ Publish installation, point your browser to the path where you stored your git repository and the wizard will kick-in. The URL could look like http://localhost/www/ezpublish-4.4. Then follow the steps of the installation wizard. You will be prompted for language choice during the wizard : the main one, and as many secondary ones as you want. We recommend to choose, as the main one, the language towards which you want to translate or localize.

Installing the translation tools

Check the following page : http://projects.ez.no/ezpublish_translation under “Start translating”. Download and install linguist, the preferred tool for editing translation.ts files, the files used for translations in eZ Publish.

Prior to translating

Always repatriate possible changes from others before starting working on localization. You can do so by running the following command :

$ git pull 

Then open the administration interface, which shows most of the strings to be translated. This can help visually track the untranslated strings.

Translating, localizing

Let us imagine you are working on the French (France) translation. Using linguist, you will open the following file :

<ezpublish-root>/share/translations/fre-FR/translation.ts

and start making the changes. After having saved them, to test them in your eZ Publish instance, if they are part of the graphical user interface (administration interface for instance), click the “Clear” button on the right-hand vertical toolbar, right under the “Clear cache” entry. This will clear the translation cache, and show your the newly translated strings.

Localization is a community effort, we recommend to announce that you are are working on a specific translation in the forums, so that others can synchronize with you. Also, these forums are helpful to discuss potentially difficult points. In our example, the forum would be : http://share.ez.no/forums/translation/french

Sharing your changes

Regularly, share your changes with the rest of the Localization team. You can do so by following the three “Commit”, “Push”, “Pull request” below.

Commit

If you have added any new files, use “$ git add <file>” to stage it for commit. You can, at any moment, see the list of your changes by running :

$ git status

The output of this command is pretty explanatory.

You then have to commit the changes. You can do so, still from the command line, and after having checked that only the necessary files were modified (cf 'git status' above), and that new files, if any, were added (cf 'git add <file>' above) :

$ git commit -am "localization: updated esl-ES translation.ts" 

It is important to add a message to your commit : this informs other members of the Localization team of what you worked on. Other examples of commit messages could be :

• "localization: update ara-SA locale file"
• "localization: update esl-ES translation.ts and ara-SA locale"

As you can see, all commit messages are prefixed by "localization:", which helps tracking all localization-related activity. We recommend to follow this pattern. Then, when updating a translation, we recommend to mention the full locale code ("esl-ES"), followed by "translation.ts". If updating a locale file, please also mention full locale code ("ara-SA" for instance), followed by "locale". And if you update both or several of those, please have as many corresponding entries, following the naming pattern.

Push

When you feel confident that you want to share your work with the world, you will want to push. It is recommended to do this quite often (along with pull requests, see further below), at least every time you have finished working on a self-contained set of changes. This allows for a smoother collaboration within the Localization team, where translators of a given language most of the time are working on the same file.

Here is how you can push your localization branch :

$ git pull
$ git push origin localization

When this is done, git will respond with something like “Your branch is ahead of 'upstream/master' by 1 commit.” basically giving you an idea on how many differences there are between your topic branch and the branch you track (master). This is also shown when you use “$ git status”.
You may also see statuses like “Your branch .. is ahead .. with 1 commits and behind by 50 commits” meaning you have 1 commit in your topic branch and 50 new commits in master since you last pulled in changes.

Pull Request

When you are confident that your contribution is ready for inclusion in eZ Publish, then all you need to do is click on “Pull request” in the Github GUI on the specific topic branch as selected using the “Switch Branches” drop-down. As said above, it is recommended to do this quite often, at least every time you have finished working on a self-contained set of changes. This allows for a smoother collaboration within the Localization team, where translators of a given language most of the time are working on the same file.