From Instantbird Wiki
- this tutorial (you may skip part of it if you are already familiar with mercurial or localizing Mozilla applications)
- the Translation FAQ.
- A good text editor of your choice
- TortoiseHg (recommended for beginners using Windows)
- The command line tool ("experts" only)
- A repository for your locale and access to it
The next part of the tutorial explains how to translate Instantbird using Mercurial with TortoiseHg because we feel it's the easiest way to do translation for Instantbird at the moment. We are thinking about providing a better tool available online for everyone but it's not available currently. If you want to translate using a different OS than Windows, you will need to read the command line tool documentation and to transpose this tutorial steps to the corresponding commands.
If you are already familiar with using the command line version of hg, you can also read Instantbird:Creating_a_new_localization_(Mercurial).
You can download TortoiseHg from here. Be careful to download the latest version appropriate for your operating system (64-bit vs. 32-bit).
Since the installation of TortoiseHg is very straightforward (the installer has few options) and works on Windows XP, Vista & 7, we won't describe here the installation process. If someone wants to write on another page an installation how to and to link it there, he is welcome.
A repository for your locale and access to it
To start translating, you need us to setup some basic files for your language and to give you write access to those files. There are two different situations there. Either someone has already requested files for your locale, and is therefore responsible for them, or no one has. To check this, look on the Locale Managers page. If there is no entry for your locale (or if it is empty), then there is currently no one responsible for your locale.
In this case, contact us on IRC or by email for us to setup an environment allowing you to translate. You will become responsible for your locale translation from now on. Someone on the Instantbird team might decide to give the responsibility from to another if it seems needed.
If there is already a locale manager for your localization, you will need to contact the locale manager responsible to know if you can be of any help and about how the team on your locale works. It's your locale manager's responsibility to decide who gets access to write on the language files and who does not. You will find every information you need to contact him on Locales Managers page.
After the installation of Tortoise HG on your computer, a new entry in your explorer's context menu (i.e. "right click" menu) has been added. It is called "TortoiseHg" and will contain everything you need to send us your work on the locale files and to retrieve them. Here is an example of what it might contain:
Configuring Tortoise HG
First, go into the "TortoiseHg" contextual menu and then click on "Global Settings." Then choose the "Commit" tab. In the "Username" field, enter a username of the form "Firstname Lastname <valid-email-address>". This part is very important since some automated process are going to send you feedback by email and it is going to need a valid username to do so.
Getting files for your locale
To start this, you will need to wait for the repository of your locale to be ready. You can check the status in the table on the Locale Managers page. If there is no entry for your locale or it is not marked "ready", you will have to wait before performing this step. If you loose the files of your locale or if they get corrupted in the future, you will always be able to perform this step another time to get a fresh and clean copy of them.
First, create a new directory which will contain your work. This directory will contain all the files necessary for localization. Then, right click on the folder, use the "TortoiseHg" contextual menu and the choose "Clone..." menu item. The following window opens:
Fill the "Source Path:" field as described in the windows replacing <yourlocalehere> by the correct locale identifier for your language (eg: fr). Once this is done, press the "Clone" button. A new window opens containing information about how the operation is proceeding. If everything goes well, the window should contain "[command completed successfully]" at the end of its output. You can then click on the "Close" button that is now available. (Or you can also close the window by clicking on "Cancel" or by using the cross on the window's border.)
If TortoiseHh is working as expected, a green icon containing a check is now showing on the folder you just created and a lot of files have appeared in it, all of which have the same check (except the ".hg" folder located in the root of the folder you created). Here is a look of my folder with the "green check" on it:
It is time to explain the meaning of this check. It tells you "this folder / file and what it contains is exactly identical to the one on the Instantbird server." Be careful though, it only display status for known files inside each folder. That means that when you create a new file and you want this file to be transferred to us (and thus taken into account in the status), you will need to ask TortoiseHg to track this file, this will be covered later on this tutorial.
The different status
Using this table, you should never be surprised by the meaning of a particular icon on a file / folder:
You can now edit the translation files with your favorite text editor to create the best translation possible. We will give you a few tips about how to make your work better for everyone.
First, we strongly advise you to work coherently. You should work in a step by step fashion. Just think: "I'm going to translate this folder first" and then go to the first file, translate it, and "Commit" your modification using TortoiseHg (we will explain how to do that later) with a clear change message and then move to the next file. When you have multiple corrections to do to different files, i.e. a misspelling in many files, try to group modifications together and to "Commit" on TortoiseHg between each "group correction."
About creating / removing / renaming files
When you create a new file, you are advised to right clicking on it, and use the "TortoiseHg" contextual menu to click on the "Add Files..." entry. You will save time and prevent errors by doing so.
In the same frame of mind, you should rename and remove files using the corresponding entries of the "TortoiseHg" contextual menu. Note that renaming or removing files using the Windows explorer window (and not using the contextual menu) will not allow TortoiseHg to track any changes!
Getting us your changes and checking your job
Creating a language pack for Instantbird is a tough process for a lot of people. That is why we automated the creation process. When you send us your changes, a new language pack including them is automatically produced if possible. If it successful, a mail will be sent to you containing a link to download the produced language pack. If it failed for some reason, then a mail will be sent to you explaining why the creation process of the language pack failed and what needs to be fixed.
The steps in the next sections should be done in their specified order to ensure the changes you make are properly sent to us.
Save your changes
First of all, you MUST "Commit" your changes using TortoiseHg to be sure nothing will be lost. As you have seen before, we are greatly advising you to save often and to work in an organized manner. The reason for that is that each time you "Commit," you create something like a "restoring point" (which you can view by choosing the "Repository Explorer" from the context menu).
We won't only receive how your files look when you send us your changes but each of the save points in the middle of the process too. Each of those points is going to have an associated message, of your choice, which allows everyone to know what has changed. This is a very powerful tool for us and is also used to keep track of the Instantbird code itself.
So, how do you "Commit"? That is very simple. Just right click anywhere in your work folder we created in the "Getting Started" section. Use the "ToirtoiseHg" contextual menu, you will find a "Hg Commit..." entry. After clicking on it, you will now see the following window:
In the "File changes area," you'll find a list of all files that have been locally added / modified. Where the preceding characters identifies what about the file has changed: "M" means "Modified," "A" means "Added," "R" stands for "Removed" and a "!" means that the files has been removed or added but that it has not been done using TortoiseHg, so TortoiseHg doesn't know what it should do.
If the check box is checked, then the modifications to that file will be saved. Otherwise the modifications will be ignored. In the case of a name preceded by a "!", if the file has been removed, checking the box is going to tell our server to remove the file to. If it is a new file, it's going to be added on the server. Before finalizing the "Commit", ensure that every check box in this list has the correct state, generally they should all be checked.
When a file is selected in the "File change area," then the modifications in it are displayed in the "Modification area". A line marked by a "-" in red color means that that line has been removed from the file while a line marked by a "+" in green color has been added in the file. That presentation might look a bit hard to read at first, but it will get easier with time. If you have the courage to, and we strongly advise you to find it, you should check every modification of every files one last time before validating in this window.
Do not forget to enter a very clear and self explanatory message about what you changed in the "Change message area".
Once all those things are done, you can "Commit" your changes (by clicking on the "Commit" button as described in the image above). When you have "Committed" a change, you can undo it, but you won't be able to do so anymore after another change has been "Committed." And whatever happens, NEVER, and i mean NEVER undo a change you have "Comitted" if you have sent it to us.
Retrieve recent changes from our servers
Before sending us your changes, you have to ensure you have the latest version of each file on your side. To do so, use the "TortoiseHg" contextual menu and click on "Synchronize." A new window looking like this one is going to pop:
There is two buttons that are interesting us at this stage:
Click on "Incoming." This won't change any files, but it's going to tell you which changes on the server side are going to be downloaded to your computer if you click on "Pull." If it tells you "no changes found" as on the image above, then you can simply skip this step and go to the next section "Send to us the changes you saved" right now.
Otherwise, click on the "Pull" button. That will download the recent changes made on the server that you don't have on your computer at that time. Now there are several different situations that might occur. One of which is: you just synchronized to the server to get all recent modifications before starting to work. This will get rid of possible later issues with those changes and clicking on the "update to branch to branch tip" button that has now appeared won't report an error and you are done. Otherwise, you will have to "merge" your local changes with our changes before you can send to us a clean copy of what you did.
If merge is needed, then you will see in red in the window after clicking on "update to branch tip" the message "abort: crosses branches (use 'hg merge' or 'hg update -C')". Close the synchronize window and click on "View Changelog" of the "TortoiseHg" contextual menu. The following window (or one likes it) is going to pop:
The window presents you with all the changes that were made on the locale until now including yours and the one that you just retrieved. Just like in the above example, in your window you will see "path" of changes diverge to get into two directions at the end (there might be more complicated things under but we don't care too much about this). Right click on the revision marked "tip" (e.g: rev 8 "Test" in the above example) and click on "merge with" in the contextual menu that is now open. A new window opens letting you know with with which revision the one you just selected is going to be merged. Your last save (commit) should be displayed as "Current revision (local)" in the window. If it's the case, click on "Merge" otherwise ask someone that knows Mercurial better about your situation or deal with the situation if you know about it.
Now, two possible things can occur. If everything is perfect and the command applies without problem and you can close the window that tells you it was successfully applied and click on the "Commit" button. Enter as save message "Merge" and "Commit" your changes. Close everything and you are done. IF you now look at the Changelog again, you should now see the two "paths" of changes merging together. If it is the case, just get to the next step, otherwise start again with the merge (the paragraph before the previous image).
The other possibility, that is going to happen in very rare moments if your team is working in an organized fashion (and probably never if you are alone translating) is that someone has, on the server side, modified something you have modified too and has not done the same change as you have. In this special scenario, you will need to tell exactly what is the correct change between the two or to propose a new version that contains part of the three that you have already (meaning yours, the one on our servers, and the previous situation). Here is what the tool that allow you to do so looks like:
The window is presented in 4 parts. The 3 upper frames present you the different version of the file that have a conflict in the following order from left to right:
- A (base): the old version of the file (before your modifications and the server side modifications)
- B (local): your version of the file
- C (other): the server's version of the file
and the frame at the bottom present you the version that will be sent to the server when you are finished with indicating what is the correct version.
This tool is going to present you each file to merge one by one. Each time you have finished with one, you save and close it and it will pop with the next one.
Let's review the important buttons of the UI:
- The floppy: save changes. You can also hit CTRL + S.
- The simple up arrow: go to the previous merge mark (it might not be a conflict)
- The single down arrow: go to the next merge mark (it might not be a conflict)
- The double up arrow: go to the previous conflict
- The double down arrow: go to the next conflict
- A/B/C: indicate how the difference has been solve. When you click on it, add the part of the file that is related to the current conflict in the resulting file using the selected version. You can click on more than one of them, then the different versions are going to be inserted in the resulting file in the specified order. Once you have selected a version, you can change it yourself since the bottom frame is editable. Once the resulting file looks fine to you, save and then close.
Send to us the changes you saved
Go to the "Synchronize" window using the "TortoiseHg" contextual menu. Always check that nothing needs to be updated from the server by clicking on the incoming button. Especially, do it anew if you just merge two revisions. Someone might have sent us changes while you were merging. Once it's OK, click on the "Push" button. Enter your user name and password when prompted to and you are done! Thank you for contributing to Instantbird!
If you feel something is missing in this tutorial, or simply need some more info, first check if it is explained in the Translation FAQ, and then get in touch with us. For example, come talk with us on IRC at #instantbird. (More information about IRC is available.)