|Audacity and its main website 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 with a preceding underscore:
_("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.
Avoid writing an empty translatable string because they will create problems for gettext. This is wrong:
and this is correct:
Occasionally, code functions or technical expressions with a specific meaning may appear in error messages that require translation. It is best that programmers avoid including such expressions in text for translation, but where such cases exist, leave the function or expression untranslated. For example, in:
_("Truncating to mMaxSamples")
only translate "Truncating to".
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 website. 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 website (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 website, change directory into the "locale" directory of the website sources, and run
To see the changes in a .pot file without getting distracted by the changing C++ line numbers, diff the file with a regular expression to exclude those lines, like this one:
diff -u audacity.pot audacity.pot.new -I '^#:.*.cpp:[0-9]*' -I '^"POT-Creation-Date'
POTFILES.in needs updating before regenerating audacity.pot, if there are new files in the source tree.
for path in lib-src/FileDialog lib-src/mod* include src ; do find $path -name \*.h -o -name \*.cpp -o -name \*.mm ; done | LANG=c sort >locale/POTFILES.in
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 website, 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.
Some more useful commands
To see all messages requiring translation, written as a .po file:
msgattrib -o out.po --untranslated yourfile.po
Or you can omit the output file to write results to standard out.
To check completeness of a translation against a template file, writing messages to standard error:
msgcmp yourfile.po audacity.pot
Type any of these commands with only the --help option to learn more, or consult: https://www.gnu.org/software/gettext/manual/gettext.html#Manipulating
- the latest .po file for your language (the existing translation) for the Audacity software or website
- the latest .pot file (the current strings in the source code) for the Audacity software or website. If the .pot file appears 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 and testing 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 the original strings 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. In Poedit, unchanged strings are in black at the bottom of the window.
- Save your translation work regularly. The save will produce the .po file which you will submit, and a .mo file which in the case of translating the Audacity software you can use to test out your translation in the latest development build. To test, exit Audacity, rename your .mo file to Audacity.mo, navigate to the "Languages" folder, open the folder for your language and replace the existing Audacity.mo file with your new one. Then restart Audacity.
Submitting your translation
Subscribe to the audacity-translation mailing list, zip up the translated .po file(s) and attach to a message to the list. A member of Audacity Team will then commit the file to SVN for future Audacity release (or for the website) and will send a message back to say this has been done.
Adding and translating new languages
Occasionally a particular language won't yet have a translation, so won't have a .po file. In that case the developers will add the language to the software or website code using the steps below, then a translator would follow the steps as for updating existing translations with the difference that they would download and translate the latest audacity.pot or audacity_website.pot, change the extension to .po, then translate that.
These are the steps for developers to add a new language to the software or website.
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
- 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 Manual, noting if this depends on wxwidgets or not.