Setting up a document with Transifex

Introduction
The Fedora Project uses Transifex, an open source translation platform, to power the translation of software and documentation. All translations are hosted at Transifex.net, which provides a web application allowing translators to write, submit, and manage their translations. Document translations are then pulled into the document's git repository, where they can be built and published to http://docs.fedoraproject.org.

Documentation maintainers are responsible for the following:
 * pushing changes to their guide or other document to Transifex.net
 * pulling updated translations back to their git repository
 * publishing the translations to http://docs.fedoraproject.org

This page explains how to set up Transifex for use with your document.

Step 1: Create an Account on Transifex.net
Go to https://www.transifex.net/ and click on Register in the top right hand corner to create an account.

Step 2: Install the Transifex Client
To use Transifex with your git repository, you need the  package installed from the Fedora repositories.

Step 3: Configure .transifexrc
Edit the file ~/.transifexrc, adding your Transifex.net username and password in the following format:

 hostname = https://www.transifex.net username = password = token =

Step 4: Initialize Transifex in Your Git Repository
Go to the git repository of your document and change to the current Fedora release branch. Alternatively, you can create a new branch specifically for translations by branching the release branch, and then periodically merge updated content from the release branch to the branch with translations. After choosing the approach that is appropriate for you and changing to the branch, enter the following commands, replacing  with the url of your document's project page on Transifex.net:

tx init tx set --auto-remote

This will create a  folder in your repository.

Step 5: Map Language Codes
If you have translation folders already in your repository, you may need to map the language codes to the ones used by Transifex.net, if they are different.

To do this, open the file. You should see a  section which allows you to set configurations for the whole document, followed by sections for the individual files of which your document is comprised (resources, in Transifex terminology). In the  section, edit the   line to map the language codes in your repository to the ones used on Transifex.net. For example, if your repository uses  for Romanian and   for Bulgarian, but Transifex.net uses   and   respectively, the   line should look like this:

lang_map = ro:ro-RO,bg:bg-BG

The language code used in Transifex.net comes first, followed by the language code used by the folder in your repository. Multiple language mappings are given as a comma-separated list.

For your  file you can simply reuse the following language code mappings, which are currently utilized by a number of Fedora guides tracked by Transifex.net:

lang_map = aln:aln-AL, ar:ar-SA, ast:ast-ES, as:as-IN, bal:bal-PK, bg:bg-BG, bn:bn-BD, bn_IN:bn-IN, bs:bs-BA, ca:ca-ES, cs:cs-CZ, da:da-DK, de_CH:de-CH, de:de-DE, el:el-GR, en_GB:en-GB, es:es-ES, et:et-EE, fa:fa-IR, fi:fi-FI, fr:fr-FR, gu:gu-IN, he:he-IL, hi:hi-IN, hr:hr-HR, hu:hu-HU, id:id-ID, is:is-IS, it:it-IT, ja:ja-JP, kn:kn-IN, ko:ko-KR, lt:lt-LT, lv:lv-LV, mai:mai-IN, ml:ml-IN, mr:mr-IN, ms:ms-MY, nb:nb-NO, nds:nds-DE, nl:nl-NL, nn:nn-NO, or:or-IN, pa:pa-IN, pl:pl-PL, pt_BR:pt-BR, pt:pt-PT, ro:ro-RO, ru:ru-RU, si:si-LK, sk:sk-SK, sl:sl-SI, sq:sq-AL, sr:sr-RS, sr@latin:sr-Latn-RS, sv:sv-SE, ta:ta-IN, te:te-IN, tg:tg-TJ, tr:tr-TR, uk:uk-UA, ur:ur-PK, vi:vi-VN, zh_CN:zh-CN, zh_HK:zh-HK, zh_TW:zh-TW

Step 6: Edit File Filters
By default,  downloads translations and stores them in a   folder in your repository. For Fedora documentation,  must be configured to download the translations to the root folder of your repository, with each language having its own folder, so that Publican can find them.

For each resource listed in the  file, edit the   line to give the correct location:

file_filter = / .po

Replace with the name of the resource, which is the second part of the section title shown directly above. For example:

[fedora-release-notes.Amateur_Radio] file_filter = /Amateur_Radio.po source_file = pot/Amateur_Radio.pot source_lang = en

Step 7: Pushing and Pulling Translations
Your document repository should now be configured for Transifex! Whenever a change is made to your document, use the following commands to first pull updated translations from Transifex.net, and then push your changes in your document back to Transifex.net so that translators can translate them:

To pull updated translations from Transifex.net, run the following command:

tx pull -a

To push your changes in your document back to Transifex.net, run the following command:

publican update_pot tx push -s

If you need to edit a .po file locally, you can push the changes back to Transifex.net:

tx push -t

You can use the  option to specify specific languages to pull, for example if you know that a particular language has new translations available.

Refer to the wiki page Publishing_a_document_with_Publican for information on how to publish translated documentation to http://docs.fedoraproject.org.

Step 8: Branching and Updating Translations Before a New Release
First, change to the branch intended for the previous Fedora release. Then create a new branch for the upcoming release and change to the branch:

git checkout -b

Assuming that the content development for the upcoming release happened in the master branch, which is different from the release branch, you should merge the updates from the master branch:

git merge master

After successful merging, check that the resource configuration in the  file is still up-to-date and applies to the current documentation. Especially pay attention to changed, moved or removed chapters in your document. If you need to remove an unused resource, run the following command:

tx delete -r.

For example, if you want to remove the resource Amateur_Radio from the Fedora Release Notes, execute the following command:

tx delete -r fedora-release-notes.Amateur_Radio

Always remember to commit all your changes. After committing them, run the following command to push your new branch to the upstream repository:

git push origin

When you are done with all necessary changes, follow the usual procedure with pushing and pulling translations that is described in the previous step.