Author: runa Date: 2011-03-02 15:46:57 +0000 (Wed, 02 Mar 2011) New Revision: 24287 Modified: translation/trunk/documentation/howto.txt Log: documenting the workflow for all of our translation projects, work in progress Modified: translation/trunk/documentation/howto.txt =================================================================== --- translation/trunk/documentation/howto.txt 2011-03-02 15:26:23 UTC (rev 24286) +++ translation/trunk/documentation/howto.txt 2011-03-02 15:46:57 UTC (rev 24287) @@ -1,32 +1,338 @@ -## Instructions for helping translate text for Vidalia, TorButton -## and TorCheck -## ( More translation information for Tor related apps will accumulate here ) +# This file documents the translation process for all projects +# currently available in the Tor translation portal: +# +# *. BridgeDB +# *. GetTor +# *. Vidalia Help Files +# *. Vidalia Installer +# *. Vidalia +# *. Orbot +# *. Torbutton-alpha +# *. Torbutton +# *. Torcheck +# *. The Website +# * Tor Manual Pages +# +# ( More translation information for Tor related apps and documentation +# will accumulate here ) -Our translations are handled in one of two places. The Tor Translation Portal -handles all of the translations for Vidalia, Torbutton and TorCheck. The Tor -website itself is currently handled by hand translations using subversion. -------------------------------------------------------------------------- +About Transifex: -For the Tor website, you'll need a Tor SVN account. -If you do not have one and you need one, please run this command with your -desired username in place of 'USERNAME': - htdigest -c passwd.tmp "Tor subversion repository" USERNAME -and send us the contents of passwd.tmp. + All of the translation projects are located here: + https://www.transifex.net/projects/p/torproject/. -------------------------------------------------------------------------- + Transifex is a website that lets users contribute translations + online using their web browser. Users will have to register at + https://www.transifex.net/accounts/register/ before they can start + translating. -For the Portal-based projects, all three check in their respective .po -files into the following subversion urls: + A project may have many files that can be translated. In transifex, + these files are called resources. Transifex lists all sentences or + phrases (called "strings") used by a particular resource, and allows + interested volunteers to translate individual sentences or phrases + as they are able. - https://tor-svn.freehaven.net/svn/translation/trunk/projects/torbutton - https://tor-svn.freehaven.net/svn/translation/trunk/projects/torcheck - https://svn.vidalia-project.net/svn/vidalia/trunk/src/vidalia/i18n/ +The Transifex Client: -The current pootle configuration is checked into subversion as well: + The Transifex Command-line Client enables you to easily manage your + translations within a project without the need of a GUI. You can use + the command line client to easily create new resources, map local + files to translations and synchronize translation projects with your + local repository and vice verca. - https://tor-svn.freehaven.net/svn/translation/trunk/pootle + For more information about the Transifex client, see + http://help.transifex.net/user-guide/client/index.html#user-client + 1. Installing the client + + The Transifex Client can be found on the Python Package Index + (PYPI) under the name transifex-client. So to install it, make sure you + have a recent version of setuptools installed and then issue the + following command: + + $ easy_install -U transifex-client + + This command will install the latest version of transifex-client + and if you have an outdated version it’ll perform an update. + + 2. Init + + After installing the client, you will need to run the command + below to initialize a project and generate your own config file. + You may run this command from anywhere on your filesystem: + + $ tx init + + NOTE: You will be asked to enter the URL of the Transifex + instance you wish to connect to. Make sure it says + "https://www.transifex.net". + + The init command will create the following files for you: + ~/.tx/config and ~/.transifexrc. Each of the translation projects + have their own configuration file, so you can safely delete + ~/.tx/config. The other file, ~/.transifexrc, holds your username + and password for Transifex. + + 3. Set + + The following command is an aggregation of all functions needed + to initialize and setup a new translation resource: + + $ tx set + + For more information and other examples, see + http://help.transifex.net/user-guide/client/index.html + + As an example, here's how you would initialize and set up Orbot + as a new translation resource. + + Check out the Orbot translation directory from SVN: + https://svn.torproject.org/svn/translation/trunk/projects/orbot/. + + Inside the 'po' directory, run the following command to + initialize the new resource: + + ~/translation/projects/orbot/po$ tx init + + Once that is done, you can create the resource 'orbot-strings-pot' + and assign a source file: + + ~/translation/projects/orbot/po$ tx set --source -r torproject.orbot-strings-pot -l en strings.pot + + Once you have created a mapping between a source file and a + resource, you should add more translations to this resource. To + set a specific file as the source and auto-detect translations + for all languages, run the following command: + + ~/translation/projects/orbot/po$ tx set --auto-local -r torproject.orbot-strings-pot '<lang>/strings.po' --source-lang en --source-file strings.pot + + The Transifex client will store this information in the following + file: /translation/projects/orbot/po/.tx/config. + + To check the existing mapping of source files and translations, run the following command: + + ~/translation/projects/orbot/po$ tx status + + When you have assigned all of the source files and added all + existing translations, push the changes up to the Transifex + server (see below for information on how to push local changes). + Remember to commit the .tx/config file to SVN. + + NOTE: you can also initialize and setup new translation resources + on https://www.transifex.net/. + + 4. Push + + The following command sends local changes to the Transifex server: + + $ tx push [-s|--source or -t|--translations] + + If you have added new source files, the corresponding resources + are created on the Transifex server and if you have new + translations those will get pushed as well. This can also be used + to update existing source files or translations on the server + with new strings. Use --help for more information. + + NOTE: All translation resources have been configured to + automatically update the source files from URL. It is not + necessary to push the source files manually. + + 5. Pull + + The following command pdates your local files by pulling the + latest translations from the server as well as new translation + files that were created in the Transifex UI: + + $ tx pull + + By default, this command will check if the modification time of + your local files is more recent than that on the Transifex server + and will not overwrite newer files. Use --help for more + information. + + +BridgeDB: + + # TODO: document the translation workflow for BridgeDB when we have + # figured it out. + +GetTor: + + # TODO: document the translation workflow for GetTor when we have + # figured it out. + +Vidalia Help Files: + + The Transifex configuration file, source files and translations can + be found here: + https://svn.torproject.org/vidalia/vidalia/trunk/src/vidalia/help/content/. + + 1. Pulling Translations from the Transifex Server + + To pull new translations from the server, cd to the 'po' + directory and run 'tx pull'. Remember to commit the changes to + SVN. + + 2. Converting Translations to HTML + + Simply pulling translations from the Transifex server is not + enough. To make use of the translations, you will need to convert + the .po files to .html files. + + You can use the following script to automate the process: + https://svn.torproject.org/vidalia/vidalia/trunk/src/vidalia/help/content/po... + + NOTE: You need to have the package 'po4a' installed before running the script. + + 3. Creating/Updating Translation Template Files + + To create a .pot file from an .html file, run the following command: + + $ po4a-gettextize -f html -m file.html -p file.pot + + You will need to edit the header of the .pot file once it has + been created. Use the header from one of the existing .pot files + in 'po/templates' as a template. Remember to commit the file to + SVN. + + 4. Adding New Translation Resources to Transifex + + To add new translation resources to Transifex, open up + 'po/.tx/config' and create entries for the new resources. Use an + existing entry as a template. Remember to commit the file to SVN. + + 5. Pushing Files to the Transifex Server + + To push new/updated source files or translations to the Transifex + server, cd to the 'po' directory and run 'tx push' with either + '-s' or '-t'. + +Vidalia Installer: + + The Transifex configuration file, source file and translations can + be found here: + https://svn.torproject.org/vidalia/vidalia/trunk/pkg/win32/po/. + + 1. Pulling Translations from the Transifex Server + + To pull new translations from the server, run 'tx pull'. Remember + to commit the changes to SVN. + + 2. Converting Translations + + # TODO: document how to convert translations to a useful format. + + 3. Creating/Updating Translation Template Files + + # TODO: document how to convert from a useful format to .pot + + 4. Adding New Translation Resources to Transifex + + To add new translation resources to Transifex, open up + '.tx/config' and create entries for the new resources. Use an + existing entry as a template. Remember to commit the file to SVN. + + 5. Pushing Files to the Transifex Server + + To push new/updated source files or translations to the Transifex, + simply run 'tx push' with either '-s' or '-t'. + +Vidalia: + + The Transifex configuration file, source file and translations can + be found here: + https://svn.torproject.org/vidalia/vidalia/trunk/src/vidalia/i18n/po/. + + 1. Pulling Translations from the Transifex Server + + To pull new translations from the server, run 'tx pull'. Remember + to commit the changes to SVN. + + 2. Converting Translations + + # TODO: document how to convert translations to a useful format. + + 3. Creating/Updating Translation Template Files + + # TODO: document how to convert from a useful format to .pot + + 4. Adding New Translation Resources to Transifex + + To add new translation resources to Transifex, open up + '.tx/config' and create entries for the new resources. Use an + existing entry as a template. Remember to commit the file to SVN. + + 5. Pushing Files to the Transifex Server + + To push new/updated source files or translations to the + Transifex, simply run 'tx push' with either '-s' or '-t'. + +Orbot: + + The Transifex configuration file, source file and translations can + be found here: + https://svn.torproject.org/svn/translation/trunk/projects/orbot/po/. + + 1. Pulling Translations from the Transifex Server + + To pull new translations from the server, run 'tx pull'. Remember + to commit the changes to SVN. + + 2. Converting Translations to XML + + Simply pulling translations from the Transifex server is not + enough. To make use of the translations, you will need to convert + the .po files to .xml files. + + Start by checking out the following directory: + https://svn.torproject.org/svn/projects/android/trunk/Orbot/. + + You can use the following script to convert translated .po files to .xml files:: + https://svn.torproject.org/vidalia/vidalia/trunk/src/vidalia/help/content/po... + + NOTE: You need to have the package 'po4a' installed before running the script. + + 3. Creating/Updating Translation Template Files + + To create a .pot file from an .xml file, run the following + command: + + $ po4a-gettextize -f xml -m file.xml -p file.pot + + You will need to edit the header of the .pot file once it has + been created. Use the header from one of the existing .pot files + in 'orbot/po/templates' as a template. Remember to commit the + file to SVN. + + 4. Adding New Translation Resources to Transifex + + To add new translation resources to Transifex, open up + '.tx/config' and create entries for the new resources. Use an + existing entry as a template. Remember to commit the file to SVN. + + 5. Pushing Files to the Transifex Server + + To push new/updated source files or translations to the + Transifex, simply run 'tx push' with either '-s' or '-t'. + +Torbutton and Torbutton-alpha: + + The Transifex configuration file, source file and translations can + be found here: + https://svn.torproject.org/svn/translation/trunk/projects/torbutton/ + and here: + https://svn.torproject.org/svn/translation/trunk/projects/torbutton-alpha/. + + 1. Pulling Translations from the Transifex Server + + To pull new translations from the server, run 'tx pull'. Remember + to commit the changes to SVN. + + + + + ---------------------------- TorCheck ------------------------------- TorCheck uses our translation portal to accept translations. Users use