Translate text in .po files

Localization specialists use professional tools to translate real projects: CAT tools, TMS systems etc. To better understand the .po files structure, we will start with manual translation. After that, we will get acquainted with Transifex, one of the popular translation management systems.

Before you start, download the translation lists to get Russian and Portuguese translations of all texts.

Note

You can build the translated documentation at any time, even if the translation is not finished. This helps you see the intermediate result and understand how gettext works.

Manual translation

Let’s start from translating our texts into Russian:

  1. Open index.po in locale/ru/LC_MESSAGES and find these lines:

    #: ../../index.rst:2
    
    msgid "The Zen of Python"
    
    msgstr ""
    
    • The first line points to the source file and the exact line in it.

    • The second, msgid, is for the source text itself; it also serves as a string ID.

    • The third, msgstr, should contain the translation of the string from msgid.

  2. Put the translation to msgstr like this:

    msgstr "Дзен Питона"
    
  3. Do the same for other strings in index.po and easter-egg.po.

    Note the escape characters in this string:

    msgid "Although never is often better than \\*right\\* now."
    

    Be careful to keep all such characters as well as the reST notation.

    Here is the example of the above string in Russian:

    msgstr "Хотя никогда обычно лучше, чем \\*прямо\\* сейчас."
    

Once you’re done with Russian, repeat the process with index.po in locale/pt_BR/LC_MESSAGES to translate it into Portuguese. For now, do not translate easter-egg.po, we will use Transifex to translate this file.

You can download an archive that contains .po files already translated into Russian and Portuguese (except for the Portuguese version of easter-egg.po).

Using Transifex

Sphinx documentation and Readthedocs describe Transifex integration using the Transifex Client. We will use another option: integration with GitHub via Transifex UI. For this, you will need your own copy of the demo repository on GitHub. The easiest way is to use the sphinx-intl-demo repository as a template. Note that easter-egg.po in locale/pt_br/LC_MESSAGES is intentionally left untranslated.

Use this template -> Create a new repository

Creating a new repository from a template

Now you are ready to integrate Transifex into your translation process.

Create an account and organization

When creating an account, Transifex invites you to create an Open Source organization or join an existing organization. For our demo project, we’ll need a new organization.

Note

It doesn’t matter if you actually work for an organization or own one. On Transifex, organization is just a way to organize your projects.

In short, a user can be an administrator of an organization that owns some projects, and each project includes resources. Learn more about Transifex organizations, projects and resources.

Create a project

When you are done with the account and organization, Transifex invites you to create a project. For our demo project, specify the project settings as follows:

  • Project name: sphinx-intl-demo (choose another name if you want).

  • URL to open source license: specify the path to the license file in your GitHub repository. It should be something like this: https://github.com/<your_account>/sphinx-intl-demo/blob/main/LICENSE

  • Project type: File based.

  • Source language: English.

  • Target languages: Russian, Portuguese (Brazil).

transifex project settings

Adding a new project

Click Create project to finish adding a project.

Integrate Transifex and GitHub

Integrate your Transifex and GitHub accounts as described in the Transifex documentation:

  1. Go to your organization settings -> Integrations.

  2. In the GitHub integration box, click Authorize and then Install the Transifex app.

    Manage Integrations page

    Authorizing GitHub

  3. From the Select repositories drop-down menu, select your demo repository, and then click Install.

  4. Confirm your GitHub password. The Transifex Integration is now installed on your GitHub account.

  5. Get back to Transifex and go to your organization settings -> Integrations.

  6. In the Github integration box, click Authorize and then authorize Transifex.

  7. If Transifex requires some permissions, click Authorize Transifex Integration.

  8. Finish integration by clicking your GitHub account name in the list of available installations.

    GitHub Authorization

    Final step of integration

Your demo repository should now be authorized on Transifex.

Translate files in Transifex Editor

To translate easter-egg.po into Portuguese:

  1. Go to Transifex Editor by clicking Editor at the top of the page.

  2. From the target language drop-down menu, select Portuguese (Brazil).

    target language selector

    Selecting target language

  3. In the Resource Overview list, click zen…easter-egg.pot(main). Transifex Editor opens.

  4. In the strings list on the left, click Easter Egg. Put the translation for this string (Ovo de Páscoa) into the translation area on the right.

    Strings to translate, translation area

    Transifex Editor

    Click Save Translation.

  5. Repeat for two other strings.

  6. Select all the translated strings by clicking the grouping checkbox on the left. In the Bulk actions panel on the right, select Reviewed from the Mark as drop-down menu, and then click Apply.

    Bulk actions

    Applying Reviewed status to all strings

All the strings in easter-egg are now translated and reviewed.

Learn more about Transifex Editor in the documentation.

Merge pull request on GitHub

Once one of our resources is fully translated and reviewed, Transifex automatically sends it to GitHub by creating a pull request. You can find the information about it on the Project Integrations page.

To merge the pull request:

  1. On GitHub, go to your demo repository Pull requests.

    Pull requests page on GitHub

    Pull request from Transifex

  2. Click the pull request name. The format of pull request names from Transifex is Transifex '<path to the source>' in '<language code>'.

  3. On the Files changed tab, check that all the translated strings are correct.

  4. On the Conversation tab, click Merge pull request, then Confirm merge.

  5. After the pull request is merged, you can delete the branch.

    Pull request successfully merged and closed

    Deleting branch

Now all the texts in .po files are translated.

You can pull the newly translated .po file from GitHub (by using git pull) to build your documentation locally.