Difference between revisions of "Editing audacityteam.org"

From Audacity Wiki
Jump to: navigation, search
m (Updating a translation: add note on revert-po target in makefile)
m (Editing the website: typo)
Line 14: Line 14:
  
 
== Editing the website ==
 
== Editing the website ==
Audacity keeps the web site's PHP source in CVS. So to edit the web site you need to check out a working copy of the source from the ''htdocs'' module in CVS. You can then edit the relevant page, and commit you changes back to CVS. At this point, nothing has changed on the web server, but the new version of the site has been stored in CVS.
+
Audacity keeps the web site's PHP source in CVS. So to edit the web site you need to check out a working copy of the source from the ''htdocs'' module in CVS. You can then edit the relevant page, and commit your changes back to CVS. At this point, nothing has changed on the web server, but the new version of the site has been stored in CVS.
 
 
  
 
== Updating the web server from CVS ==
 
== Updating the web server from CVS ==

Revision as of 20:16, 25 June 2009

This page describes the process in place to make changes to the main Audacity website on http://audacity.sourceforge.net/. This process requires that you have a SourceForge account and are listed as a developer on the Audacity project.


How the site works

In order to make the site available in many languages, we use PHP and the GNU gettext tools to deliver one set of pages translated into many languages. This makes it possible to update all language versions of the web site with minimal effort. Text that has not yet been translated into a given language will appear in English until the translation is updated.

The site has a single set of PHP pages which contain the English version of the pages. All text that appears on the screen is stored as PHP strings (rather than using included HTML) and output using =, echo and similar. These strings are marked for translation by enclosing them in brackets preceded by an underscore.

_('some text');

When the pages are altered, xgettext is used to go through all the .php pages on the site and construct a message catalogue of all the strings marked as needing translation. Duplicates and known standard strings (dates and so on) are removed at this point to create audacity_website.pot, which is the translation template. A copy of this template exists for every language the web site is translated into, named after the ISO language code with a .po extension (so fr.po, de.po).... These contain all the strings marked for translation and the translation into that language of the string. These files are maintained and updated by the team of Audacity translators for each language.

Once translations have been obtained, they are compiled using msgfmt to create message catalogue files (*.mo files) for each language. Localized pages are served automatically based on the Accept-Language header sent by the user's web browser, or can be selected manually using language links in the page footer (this method also sets a cookie that serves future pages in that language). When the page is is sent to the visitor, the web server reads the relevant .mo file, looks up each string, and sends the translated text to the user instead of the English version.


Editing the website

Audacity keeps the web site's PHP source in CVS. So to edit the web site you need to check out a working copy of the source from the htdocs module in CVS. You can then edit the relevant page, and commit your changes back to CVS. At this point, nothing has changed on the web server, but the new version of the site has been stored in CVS.

Updating the web server from CVS

The copy of the web site that users actually see is located on a web server run by SourceForge in Chicago. In order for changes in CVS to become visible, they need to be transmitted to that server. This process currently only works on *nix-like systems (such as Linux, or Mac OS X if you use the command line tools). Users without a *nix workstation can perform the same steps on the Sourceforge Shell Service by logging in over SSH.

Prerequisites

To update the web site you will need all of the following installed on your system. Note that at this point you are not actually editing anything, so a remote shell login to a system (e.g. the Sourceforge Shell Service, which has all the required tools) is quite sufficient.

  • CVS: Fairly obvious, but importantly your copy of CVS must check out files with CR line endings, as on a Unix system. CVS for Windows does not do this.
  • SSH: Needed as a transport layer for both CVS and RSync.
  • RSync Used to transmit files to and from the SourceForge web server.
  • GNU Make: Used to automate commands in the translation process. Other makes may work but have not been tested.
  • GNU gettext tools: msgfmt and xgettext are needed to generate and compile translations.
  • Python: Audacity uses a customised message merging tool to deal with cases where a string is not translated but a very similar one is. This is written in Python, so your system needs to be able to run .py scripts.

To check out the current web site code, you will need developer CVS over SSH access to SourceForge - to set up this up, see the SourceForge documentation. If you want to update the website on the Sourceforge Shell Service, you will need to set up CVS access for your account on there, which is separate to access from your local computer.

Updating the site

This assumes you already have a working copy of the htdocs CVS module, and are in the top level htdocs folder.

  1. Set the SFUSER environment variable to your username on SourceForge, so the scripts know who to try and log in as. In the default bash shell, do something like export SFUSER=richardash1981
  2. Run make pull to download files that aren't under CVS control from the web server into your working copy. This may overwrite changes to your working copy, but that doesn't matter, because you should have already committed them to CVS (if you want to check what will happen, run make pretend-pull first).
  3. Bring your CVS working copy up to date without extraneous directories by running cvs up -P -d (you will need the password for your SSH key).
  4. Check the output to ensure that all version controlled files are in sync with CVS. In general if they are not, then the CVS version is the correct one, so conflicting or modified files can be deleted and re-checked out (this is where subversion's revert command would be used, but CVS doesn't have one).
  5. If the .po files get into a mess, then you can delete all local changes to the .po files and get the CVS copies by doing make revert-po. This is just a short-cut to deleting them all and updating the directory from CVS.
  6. Run make pretend-push to see a list of altered files that will be uploaded to the SourceForge server (you will need the password for your SSH key). If this isn't what you expected, then check what is going now. No files are actually changed at this point.
  7. Run make to create first audacity_website.pot, then update the .po files with the new strings, then compile all the .po files into .mo files. This can take a while and be quite CPU intensive.
  8. Run make pretend-push again. You should see that as well as the files you saw last time, locale/audacity_website.pot and all the .mo files (in the individual language folders in locale) are scheduled to be uploaded to the server. No .po files will be uploaded because the rsync command ignores them (they are not needed on the web server).
  9. Finally run make push to upload the files.

Adding new web site translations

This consists of three operations - merging strings with the new .po file to bring it up to date, compiling it to generate .mo files for the web site, and committing the new translation to CVS.

Prerequisites

The same tools and checked out copy of the htdocs CVS module are needed as for updating the site from CVS above.

Updating a translation

This assumes you already have a working copy of the htdocs CVS module, and are in the top level htdocs folder.

  1. Set the SFUSER environment variable to your username on SourceForge, so the scripts know who to try and log in as.
  2. Run make pull to download files that aren't under CVS control from the web server into your working copy. This may overwrite changes to your working copy, but that doesn't matter provided that you have committed them to CVS.
  3. Bring your CVS working copy up to date without extraneous directories by running cvs up -P -d (you will need the password for your SSH key).
  4. Check the output to ensure that all version controlled files are in sync with CVS. In general if they are not, then the CVS version is the correct one, so conflicting or modified files can be deleted and re-checked out (this is where subversion's revert command would be used, but CVS doesn't have one). It is very likely that .po files will have conflicts, and the CVS version should be used. A quick hack to delete all .po files and check out from CVS is to run make revert-po.
  5. Run make pretend-push to see a list of altered files that will be uploaded to the SourceForge server (you will need the password for your SSH key). This should be an empty list, as no files have changed. If not, then something isn't right. No files are actually changed at this point.
  6. Overwrite the relevant language translation with the new .po file you have been sent by the translator.
  7. Run make to generate new translations based on the new file. Any strings that have been altered since the last update by the translator will be merged into the .po file.
  8. Run make pretend-push again. You should see that the relevant language's .mo file, and possibly locale/audacity_website.pot, is scheduled to be uploaded to the server. No .po files will be uploaded because the rsync command ignores them (they are not needed on the web server).
  9. Run make push to upload the files.
  10. Commit the updated .po file to CVS in the normal way.