|Audacity and its main web site are localized into many languages using the gettext message catalogue system. This page summarises how the translations are made and updated.
In the source code, strings which are to be translated are written like so:
_("A string to be translated")
Such strings are detected by the 'xgettext' utility.
Strings which are not to be translated are written like so:
wxT("Don't translate this")
The wxT() allows us to build Unicode versions of Audacity.
For more detailed instructions to programmers on how to make sure the code you write is easily translatable, see Writing Translatable Code.
Tools used in translation:
Poedit is a cross-platform editor for the translation files with a wxWidgets-based interface.
KBabel for the KDE desktop environment can also be used to edit .po files for other projects.
A utility to extract the translatable strings from the source code. This is bundled with Poedit.
Updating existing translations
The most common translation exercise in Audacity is updating an existing translation taking into account changes in English strings used in the program or web site. The process is in three parts:
- Extracting all the new English strings from the source code to create a .pot file
- Merging the new English strings into the existing .po file, marking up which ones have changed slightly (called "fuzzy"), and which ones are unchanged
- Translating the new and changed strings in the .po file. Note in the current case (updating an existing translation) we do not translate the .pot file.
Generating the .pot file
The first step is usually done by the Audacity developers, using the .pot files published on the Audacity web site (Audacity .pot file, Audacity website .pot file). However if you wish to generate your own .pot file from the Audacity sources you can do so at the command line:
- For Audacity itself, change directory into the "locale" directory of the sources, and run
- For the web site, change directory into the "locale" directory of the website sources, and run
Updating the .po file with new messages
This may be done as a batch by developers at the start of a string freeze, but is likely to be left to translators most of the time.
If you have the relevant source code, then you can run at the command line:
If you just want to update a single .po file, then you can do so using the msgmerge tool from the gettext tools:
msgmerge -U yourfile.po newmessages.pot
This will update yourfile.po with the new messages for translation from newmessages.pot. This will result in a re-written yourfile.po with the new strings added. Some strings that have slightly changed will be marked up as "fuzzy" translations, that is the old translation will be kept, but flagged up for a human translator to review later on.
For example to update the pt_BR translation of the Audacity web site, you would get the current audacity_website.pot, and run
msgmerge -U pt_BR.po audacity_website.pot
Now you have a .po file with new strings in it, and the actual translation can be done.
* the latest .po file (the existing translation) for the Audacity program or web site (Audacity .po files, Audacity website .po files)
* the latest .pot file (the current strings in the source code) for the Audacity program or web site (Audacity .pot file, Audacity website .pot file). If the .pot files appear in your browser window instead of downloading, right-click over the link and choose "save target as" or "save link as".
- Launch Poedit, click and select your downloaded .po file
- Click and select your downloaded .pot file and click Open
- The "Update summary" will now show lists of the new strings that are in the .pot file but not in the .po file, and the obsolete strings that are in the .po file but no longer in the .pot file
- Click OK and wait for Poedit to add the new strings to your .po file and remove the old ones
Translating the new strings
With the .po file loaded into your favourite po-file editor, you can start to translate.
- Untranslated strings obviously need to be translated as normal. In Poedit they show as blue at the top of the window.
- Some strings may be marked as "fuzzy" translations - these show as gold in Poedit. Fuzzy translations are ones where the English has changed slightly, and so the translation has been kept. It should be reviewed against the modified English version and re-translated where necessary.
- If strings are already translated in the .po file, then they haven't changed, and you should be able to ignore them. These are shown as white in Poedit.
Make sure you save you translation work regularly. When you have an updated .po file ready, send it in so it can be added to CVS for future release or for the web site.
Adding a new language
Sometimes it will be necessary to add a completely new language to the Audacity software or web site which has never previously had a translation. This will be done by developers.
For a new language to appear in the program, it must be supported by the build of wxWidgets that Audacity is built against. The list of currently supported languages can be found in src\common\intl.cpp in the installed wxWidgets source code. Steps:
- Add the new .po file to the locale directory
- Add the new country code to locale/Makefile.in, win/Projects/locale/locale.vcproj and mac/Audacity.xcodeproj/project.pbxproj
- Add the new country code and the name of the language to src/Languages.cpp. Note the language name must use ASCII characters.
- Update the list of available languages on the Changing the current language page of the wiki, noting if this depends on wxwidgets or not.
- Add Audacity to the relevant language Trove on Sourceforge if it exists (these are ordered by the English name of the language, just to be inconvenient).
- Add the new .po file to the htdocs/locale directory
- Add the new country code, full locale name and the name of the language as it will appear in the web site footer to htdocs/include/lang.inc.php