Setting up a document with Transifex

From FedoraProject

(Difference between revisions)
Jump to: navigation, search
(Create page)
 
m (Update to correct Transifex URLs, use https, new help center URLs.)
(17 intermediate revisions by 5 users not shown)
Line 1: Line 1:
 
==Introduction==
 
==Introduction==
  
The Fedora Project uses '''Transifex''', an open source translation platform, to power the translation of software and documentation. All translations are hosted at [https://www.transifex.net/ 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.
+
The Fedora Project uses '''Transifex''', an open source translation platform, to power the translation of software and documentation. All translations are hosted at [https://www.transifex.com/ Transifex.com], 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:
 
Documentation maintainers are responsible for the following:
* pushing changes to their guide or other document to Transifex.net
+
* pushing changes to their guide or other document to Transifex.com
 
* pulling updated translations back to their git repository
 
* pulling updated translations back to their git repository
 
* publishing the translations to http://docs.fedoraproject.org
 
* publishing the translations to http://docs.fedoraproject.org
Line 10: Line 10:
 
This page explains how to set up Transifex for use with your document.
 
This page explains how to set up Transifex for use with your document.
  
==Step 1: Create an account on Transifex.net==
+
==Step 1: Create an Account on Transifex.com==
  
Go to https://www.transifex.net/ and click on ''Register'' in the top right hand corner to create an account.
+
Go to https://www.transifex.com/ and click on ''Register'' in the top right hand corner to create an account.
  
==Step 2: Install the Transifex client==
+
==Step 2: Install the Transifex Client==
  
 
To use Transifex with your git repository, you need the <code>transifex-client</code> package installed from the Fedora repositories.
 
To use Transifex with your git repository, you need the <code>transifex-client</code> package installed from the Fedora repositories.
  
==Step 3: Configure transifexrc==
+
==Step 3: Configure .transifexrc==
  
Edit the file ~/.transifexrc, adding your Transifex.net username and password.
+
Edit the file ~/.transifexrc, adding your Transifex.com username and password in the following format:
  
==Step 4: Initialize Transifex in your git repository==
+
<pre>
 +
[https://www.transifex.com]
 +
hostname = https://www.transifex.com
 +
username = <username>
 +
password = <password>
 +
token =
 +
</pre>
 +
 
 +
==Step 4: Initialize Transifex in Your Git Repository==
  
Go to the git repository of your document and change to the current Fedora release branch. Enter the following commands, replacing <code><url></code> with the url of your document's project page on Transifex.net:
+
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 <code><url></code> with the url of your document's project page on Transifex.com:
  
 
<pre>
 
<pre>
Line 30: Line 38:
 
</pre>
 
</pre>
 
<pre>
 
<pre>
tx set --autoremote <url>
+
tx set --auto-remote <url>
 
</pre>
 
</pre>
  
 
This will create a <code>.tx</code> folder in your repository.
 
This will create a <code>.tx</code> folder in your repository.
  
{{admon/tip|I can't find my document on Transifex.net!|Most Fedora documents already have a project page on Transifex.net, but if your document is new you may need to set one up. Ask on the Fedora Docs Project mailing list for help with how to do this.}}
+
{{admon/tip|I can't find my document on Transifex.com!|Most Fedora documents already have a project page on Transifex.com, but if your document is new you may need to set one up. See http://help.transifex.com/intro/projects.html for instructions on creating a new project, or ask on the Fedora Docs Project mailing list for help. When creating a new project on Transifex, choose "en" as the source language for English documentation.}}
  
==Step 5: Map language codes==
+
==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.
+
If you have translation folders already in your repository, you may need to map the language codes to the ones used by Transifex.com, if they are different.
  
To do this, open the file <code>.tx/config</code>. You should see a <code>[main]</code> 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 <code>[main]</code> section, edit the <code>lang_map</code> line to map the language codes in your repository to the ones used on Transifex.net. For example, if your repository uses <code>ro-RO</code> for Romanian and <code>bg-BG</code> for Bulgarian, but Transifex.net uses <code>ro</code> and <code>bg</code> respectively, the <code>lang_map</code> line should look like this:
+
To do this, open the file <code>.tx/config</code>. You should see a <code>[main]</code> 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 <code>[main]</code> section, edit the <code>lang_map</code> line to map the language codes in your repository to the ones used on Transifex.com. For example, if your repository uses <code>ro-RO</code> for Romanian and <code>bg-BG</code> for Bulgarian, but Transifex.com uses <code>ro</code> and <code>bg</code> respectively, the <code>lang_map</code> line should look like this:
  
 
<pre>
 
<pre>
Line 47: Line 55:
 
</pre>
 
</pre>
  
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.
+
The language code used in Transifex.com comes first, followed by the language code used by the folder in your repository. Multiple language mappings are given as a comma-separated list.
  
{{admon/note|Finding currently active Translation Teams|To find out what Translation Teams currently have translations for your document, and to see what language code they use, click on ''All Resources'' under ''Project Releases'' on your document's Transifex.net project page. This will bring up a list of all currently active Translation Teams, with the name of each language followed by its language code in parentheses. You can also see how much of your document each team has translated, and the details of the last submitted translation.}}
+
{{admon/note|Finding currently active Translation Teams|To find out what Translation Teams currently have translations for your document, and to see what language code they use, click on ''All Resources'' under ''Project Releases'' on your document's Transifex.com project page. This will bring up a list of all currently active Translation Teams, with the name of each language followed by its language code in parentheses. You can also see how much of your document each team has translated, and the details of the last submitted translation.}}
 +
 
 +
For your <code>.tx/config</code> file you can simply reuse the following language code mappings, which are currently utilized by a number of Fedora guides tracked by Transifex.com:
 +
 
 +
<pre>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, eu:eu-ES, fa:fa-IR, fi:fi-FI, fr:fr-FR, gl:gl-ES, 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
 +
</pre>
  
 
==Step 6: Edit File Filters==
 
==Step 6: Edit File Filters==
Line 68: Line 81:
 
source_file = pot/Amateur_Radio.pot
 
source_file = pot/Amateur_Radio.pot
 
source_lang = en
 
source_lang = en
 +
type = PO
 
</pre>
 
</pre>
  
==Step 7: Pushing/Pulling==
+
{{admon/important|Add project to the Transifex Fedora Project hub|If you are creating a new project on Transifex, you will need to obtain hosting by the Fedora Project hub so the Fedora translation teams can translate the document. In your Transifex project, go to ''Manage'' > ''Access Control''. Choose ''Outsourced Project'' as the ''Project type'', and select ''Fedora Project'' from the the ''Outsource access to'' options. A Fedora admin will need to approve the hosting. Once the hosting is approved, your project URL will contain https://fedora.transifex.com/ instead of https://www.transifex.com/ and is ready to be translated. }}
  
Your document repository should now be configured for Transifex! Whenever a change is made to your document, use the following commands to push the changes to Transifex.net so that translators can translate them:
+
==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.com, and then push your changes in your document back to Transifex.com so that translators can translate them:
 +
 
 +
To pull updated translations from Transifex.com, run the following command:
 +
 
 +
<pre>
 +
tx pull -a
 +
</pre>
 +
 
 +
To push your changes in your document back to Transifex.com, run the following command:
  
 
<pre>
 
<pre>
 
publican update_pot
 
publican update_pot
tx push
+
</pre>
 +
<pre>
 +
tx push -s
 
</pre>
 
</pre>
  
To pull updated translations from Transifex.net:  
+
If you need to edit a .po file locally, you can push the changes back to Transifex.com:
  
 
<pre>
 
<pre>
tx pull
+
tx push -t
 
</pre>
 
</pre>
  
 
You can use the <code>-l</code> option to specify specific languages to pull, for example if you know that a particular language has new translations available.
 
You can use the <code>-l</code> option to specify specific languages to pull, for example if you know that a particular language has new translations available.
  
{{admon/tip|Translation Notifications|Make sure you select the ''Watch'' button on your document's Transifex.net project page to receive email notifications when new translations are available. The ''Watch'' button is located below the document's title.}}
+
Refer to the wiki page [[Publishing_a_document_with_Publican]] for information on how to publish translated documentation to http://docs.fedoraproject.org.
  
{{admon/tip|Getting more help|Transifex.net has its own comprehensive documentation for <code>transifex-client</code> at http://help.transifex.net/user-guide/client/index.html. You can also post questions to the Docs Project mailing list or ask in the #fedora-docs IRC channel if you get stuck.}}
+
{{admon/tip|Translation Notifications|Make sure you select the ''Watch'' button on your document's Transifex.com project page to receive email notifications when new translations are available. The ''Watch'' button is located below the document's title.}}
 +
 
 +
==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:
 +
 
 +
<pre>
 +
git checkout -b <newbranch>
 +
</pre>
 +
 
 +
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:
 +
 
 +
<pre>
 +
git merge master
 +
</pre>
 +
 
 +
After successful merging, check that the resource configuration in the <code>.tx/config</code> 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:
 +
 
 +
<pre>
 +
tx delete -r <documentation>.<resource>
 +
</pre>
 +
 
 +
For example, if you want to remove the resource Amateur_Radio from the Fedora Release Notes, execute the following command:
 +
 
 +
<pre>
 +
tx delete -r fedora-release-notes.Amateur_Radio
 +
</pre>
 +
 
 +
{{admon/tip|Use the development version|As of September 2011, you need to have the development version of <code>transifex-client</code> installed to use the <code>tx delete</code> command. Refer to http://help.transifex.com/user-guide/client/devel.html#development-version for instructions on how to get the development version.}}
 +
 
 +
Always remember to commit all your changes. After committing them, run the following command to push your new branch to the upstream repository:
 +
 
 +
<pre>
 +
git push origin <newbranch>
 +
</pre>
  
 +
When you are done with all necessary changes, follow the usual procedure with pushing and pulling translations that is described in the previous step.
  
 +
{{admon/tip|Getting more help|Transifex.com has its own comprehensive documentation for <code>transifex-client</code> at http://help.transifex.com/user-guide/client/index.html. You can also post questions to the Docs Project mailing list or ask in the #fedora-docs IRC channel if you get stuck. The L10N Guide has lots of useful information on using Transifex from a translator's perspective: https://fedoraproject.org/wiki/L10N/Guide.}}
  
[[Category:Docs Project]]
+
[[Category:Docs Project process]]

Revision as of 02:40, 9 April 2013

Contents

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.com, 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.com
  • 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.com

Go to https://www.transifex.com/ 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 transifex-client package installed from the Fedora repositories.

Step 3: Configure .transifexrc

Edit the file ~/.transifexrc, adding your Transifex.com username and password in the following format:

[https://www.transifex.com]
hostname = https://www.transifex.com
username = <username>
password = <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 <url> with the url of your document's project page on Transifex.com:

tx init
tx set --auto-remote <url>

This will create a .tx folder in your repository.

Idea.png
I can't find my document on Transifex.com!
Most Fedora documents already have a project page on Transifex.com, but if your document is new you may need to set one up. See http://help.transifex.com/intro/projects.html for instructions on creating a new project, or ask on the Fedora Docs Project mailing list for help. When creating a new project on Transifex, choose "en" as the source language for English documentation.

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.com, if they are different.

To do this, open the file .tx/config. You should see a [main] 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 [main] section, edit the lang_map line to map the language codes in your repository to the ones used on Transifex.com. For example, if your repository uses ro-RO for Romanian and bg-BG for Bulgarian, but Transifex.com uses ro and bg respectively, the lang_map line should look like this:

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

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

Note.png
Finding currently active Translation Teams
To find out what Translation Teams currently have translations for your document, and to see what language code they use, click on All Resources under Project Releases on your document's Transifex.com project page. This will bring up a list of all currently active Translation Teams, with the name of each language followed by its language code in parentheses. You can also see how much of your document each team has translated, and the details of the last submitted translation.

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

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, eu:eu-ES, fa:fa-IR, fi:fi-FI, fr:fr-FR, gl:gl-ES, 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, transifex-client downloads translations and stores them in a translations folder in your repository. For Fedora documentation, transifex-client 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 .tx/config file, edit the file_filter line to give the correct location:

file_filter = <lang>/<resource>.po

Replace <resource> 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 = <lang>/Amateur_Radio.po
source_file = pot/Amateur_Radio.pot
source_lang = en
type = PO
Important.png
Add project to the Transifex Fedora Project hub
If you are creating a new project on Transifex, you will need to obtain hosting by the Fedora Project hub so the Fedora translation teams can translate the document. In your Transifex project, go to Manage > Access Control. Choose Outsourced Project as the Project type, and select Fedora Project from the the Outsource access to options. A Fedora admin will need to approve the hosting. Once the hosting is approved, your project URL will contain https://fedora.transifex.com/ instead of https://www.transifex.com/ and is ready to be translated.

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.com, and then push your changes in your document back to Transifex.com so that translators can translate them:

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

tx pull -a

To push your changes in your document back to Transifex.com, 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.com:

tx push -t

You can use the -l 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.

Idea.png
Translation Notifications
Make sure you select the Watch button on your document's Transifex.com project page to receive email notifications when new translations are available. The Watch button is located below the document's title.

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 <newbranch>

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 .tx/config 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 <documentation>.<resource>

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
Idea.png
Use the development version
As of September 2011, you need to have the development version of transifex-client installed to use the tx delete command. Refer to http://help.transifex.com/user-guide/client/devel.html#development-version for instructions on how to get the development version.

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 <newbranch>

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

Idea.png
Getting more help
Transifex.com has its own comprehensive documentation for transifex-client at http://help.transifex.com/user-guide/client/index.html. You can also post questions to the Docs Project mailing list or ask in the #fedora-docs IRC channel if you get stuck. The L10N Guide has lots of useful information on using Transifex from a translator's perspective: https://fedoraproject.org/wiki/L10N/Guide.