[How-to] Translate projects on Git-based repositories

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

:warning: 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!

:earth_africa: Translation complete!

We'd like to thank you for helping open source become readable for users around the world! :slight_smile:


5 posts were split to a new topic: Problem translating Welcome - Git command not found

Thank you very much for the guide!
But… there is no ubuntu-mate-welcome.pot in po/

1 Like

Changes happen very quickly - one of the translators had accidentally deleted it. It’ll be back in the main repository in a few hours.

I can’t push the files. When I type “git push” and my password I get this output:

Password for ‘https://[email protected]’:
remote: Unauthorized
fatal: Authentication failed for ‘https://[email protected]/ubuntu-mate/ubuntu-mate-welcome.git/

It looks like you’re trying to push to the actual Ubuntu MATE repository, which is read-only.

Quick way to push to your fork:

git push https://[email protected]/Guxy/ubuntu-mate-welcome.git

If you wanted to set your origin so git push works in future, you can type:

git remote set-url origin https://[email protected]/Guxy/ubuntu-mate-welcome.git

It worked! Thank you so much! Maybe the issue is because I’m working with 14.04 version.

1 Like

Glad to hear. :thumbsup:   It could have happened by accident - like cloning the wrong repository, which set up the wrong pull/push targets.