This guide will step you through how to set up and use the tools for translating Git-based repositories to other languages, even if you're entirely new to how this works.
1. Before you start...
1a. Install Poedit
poedit
is the tool great for working with pot
and po
files.
From the terminal:
sudo apt-get install poedit
Alternately, Poedit is available from the Software Boutique under the Programming category.
Or, poedit
can be found in your desired software centre or package manager.
1b. Install Git
Git is a decentralized version control system and how many changes in open source projects are tracked.
sudo apt-get install git
1c. Register with BitBucket / GitHub
Ubuntu MATE's repositories are hosted on BitBucket, others like the MATE Desktop use GitHub.
You will need to create an account for the relevant service if you don't have one already.
2. Preparing your fork
First, you will need to create your own copy ("fork") of the repository to work with. Later when you make your changes, you will push your translations back to your fork on your copy of the online repository and issue a "pull request" for the maintainer to review and pull in your changes later.
2a. Creating the fork for the first time.
Navigate to the repository you'd like to translate and click Fork.
Example in BitBucket:
This only needs to be done once. Inside your new repository, click Clone. This box will appear:
As Git is decentralized, the clone is what is stored on your local computer. Open the terminal and navigate to where you'd like to store the clone, then paste your clone
command. For example:
git clone https://[email protected]/xxxxx/ubuntu-mate-welcome.git
2b. Updating your repository (if necessary)
A lot of changes can happen quite quickly. Bug fixes, typos... to update your copy, merge these changes from upstream:
git pull <main URL> master
For example, for Ubuntu MATE Welcome:
git pull https://bitbucket.org/ubuntu-mate/ubuntu-mate-welcome.git master
Why keep the latest changes?
This ensures you have the latest strings needed for translation, as you could potentially:
- Translate work that has already been done.
- Translate strings that are no longer used, which could result in your contribution being rejected.
- Be missing new strings or updates to translations.
3. Translating with Poedit
Open the directory containing the repository clone and navigate to the po/
folders.
Choose a page folder you'd like to translate. Inside you will find:
- A
.po
file for each language code - These may be complete or partial translations. - A
.pot
file - This is the template for new languages.
To translate to a new language, select Create New Translation at the bottom:
For Ubuntu 14.04 users using an older version of Poedit (1.5.4):
- Click File → New Catalog from POT file...
- Navigate to the pot files inside every folder and select it
- Edit the "Project name and version" and "Language"
- Save it as a po file.
Thank you to @s585448 for the info.
Choose your language, specifying the language and country.
Now you can begin translating!
When you've finished, save the file. The default directory to save to is usually correct, which contains the .pot
template and all the .po
files for each language for that page.
Repeat the process for as many pages as you can.
Updating Translations
As the application updates, some of the strings may be no longer used or new strings are wanting translation. On occasions, these files may be already be updated as part of the development.
Providing your repository is up-to-date, use the Catalogue → Update from POT file option to update them.
4. Submitting your contribution
Commit your changes
Open the directory containing the repository in a terminal.
Check the files that have been modified.
git status
If you are happy with the files you have modified, type:
git add *
Commit them by writing a message.
git commit -m "Translated to French"
Now push your changes to your fork online.
git push
You may need to enter your username and password at this point.
Creating a pull request
Navigate to your fork online, either BitBucket or GitHub.
The following is steps for BitBucket repositories.
Click on Create pull request.
Give your changes a quick description and click Create pull request to finish.
The maintainer will review your translation changes, you'll get an email as a notification. Once approved, your efforts will be featured in the next update of that package!
Translation complete!
We'd like to thank you for helping open source become readable for users around the world!