Difference between revisions of "Translating Audacity"

From Audacity Wiki
Jump to: navigation, search
(move in hint for treating % strings from translators page on main web site)
m (Source Code: add some examples of long strings and how not to handle them, and clean up the printf explanation (they shouldn't be double % signs))
Line 16: Line 16:
  
 
When strings span several lines we place a '\' at the end of each line, and continue immediately at the start of the next line.  We have tried various other ways of dealing with long strings, but the other ways we've tried either don't work when compiling with Unicode, or defeat detection by xgettext.
 
When strings span several lines we place a '\' at the end of each line, and continue immediately at the start of the next line.  We have tried various other ways of dealing with long strings, but the other ways we've tried either don't work when compiling with Unicode, or defeat detection by xgettext.
 +
 +
So
 +
          _("This is a very long string that is too long to fit on a single line, so we really have\
 +
to do something about it");
 +
is correct, as is just using a long line:
 +
          _("This is a very long string that is too long to fit on a single line, so we really have to do something about it");
 +
However, you mustn't put leading spaces or tabs on the continuation lines, because those extra spaces will be incorporated into the string sent for translation, as well as putting big blanks into the UI. So this is '''''wrong:'''''
 +
          _("This is a very long string that is too long to fit on a single line, so we really have\
 +
            to do something about it");
 +
and you mustn't do it in Audacity.
  
 
To enable translation, rather than write strings like this:
 
To enable translation, rather than write strings like this:
Line 25: Line 35:
 
   wxString::Format(_("The file %s could not be found"), filename.c_str )
 
   wxString::Format(_("The file %s could not be found"), filename.c_str )
  
This gives the translator a complete sentence to work with, rather than the fragments "this file " and "could not be found.", which due to alphabetical sorting could be well separated in the .po file.
+
This gives the translator a complete sentence to work with, rather than the fragments ''"this file "'' and ''"could not be found."'', which due to alphabetical sorting could be well separated in the .po file.
  
 
Some parts of the source code contain '''HTML code.'''  Do not translate the HTML tags. Also in places, these embedded HTML strings have hyperlinks in Wiki syntax, like so:
 
Some parts of the source code contain '''HTML code.'''  Do not translate the HTML tags. Also in places, these embedded HTML strings have hyperlinks in Wiki syntax, like so:
Line 38: Line 48:
 
The ampersand (&) precedes that menu item's keyboard ''access key''. This is shown as underlined in the Audacity menu, and allows Windows and Linux users to access that item without a mouse. Translators are encouraged to choose unique access keys for each translated item in the particular Audacity menu.  
 
The ampersand (&) precedes that menu item's keyboard ''access key''. This is shown as underlined in the Audacity menu, and allows Windows and Linux users to access that item without a mouse. Translators are encouraged to choose unique access keys for each translated item in the particular Audacity menu.  
  
Finally,  you will find many strings like <b>"There were %%d buffer underruns, last near %%lf seconds."</b> The %% signs mark places where numbers or names will be inserted into the string. For example, after inserting values this string might become "There were 4 buffer underruns, last near 3.01 seconds." If you change the order of the %% markers in a string, add "1$" after the percent sign that used to be first, "2$" after the percent sign that used to be second, and so on.  For example:
+
Finally,  you will find many strings like '''"There were %d buffer underruns, last near %lf seconds."''' The '''%d''' and '''%lf''' sequences mark places where numbers or names will be inserted into the string. The letters after the '''%''' sign determine the type of the variable that will be inserted, so it is vital not to change these '''%''' sequences. For example, after inserting values this string might become "There were 4 buffer underruns, last near 3.01 seconds." If you change the order of the '''%''' markers in a string, add '''1$''' after the percent sign that used to be first, '''2$''' after the percent sign that used to be second, and so on.  For example:
  
 
  _("The buffer underrun near %%2$lf seconds was the last of %%1$d.")
 
  _("The buffer underrun near %%2$lf seconds was the last of %%1$d.")
  
 +
This ensures that the correct variable is inserted in the correct place in the string when the text is displayed.
  
 
==Tools==
 
==Tools==

Revision as of 20:52, 30 December 2009

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.
 
Related article(s):

Source Code

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.

When strings span several lines we place a '\' at the end of each line, and continue immediately at the start of the next line. We have tried various other ways of dealing with long strings, but the other ways we've tried either don't work when compiling with Unicode, or defeat detection by xgettext.

So

         _("This is a very long string that is too long to fit on a single line, so we really have\
to do something about it");

is correct, as is just using a long line:

         _("This is a very long string that is too long to fit on a single line, so we really have to do something about it");

However, you mustn't put leading spaces or tabs on the continuation lines, because those extra spaces will be incorporated into the string sent for translation, as well as putting big blanks into the UI. So this is wrong:

         _("This is a very long string that is too long to fit on a single line, so we really have\
           to do something about it");

and you mustn't do it in Audacity.

To enable translation, rather than write strings like this:

 wxString(_("The file " )) + filename + _("could not be found.")

use instead:

 wxString::Format(_("The file %s could not be found"), filename.c_str )

This gives the translator a complete sentence to work with, rather than the fragments "this file " and "could not be found.", which due to alphabetical sorting could be well separated in the .po file.

Some parts of the source code contain HTML code. Do not translate the HTML tags. Also in places, these embedded HTML strings have hyperlinks in Wiki syntax, like so:

 [[export|Exporting to MP3]]

In the .po file, translators should translate the second part after the pipe (|), but not the first part.

Some parts of the program source code denote menu items, like so:

 _("&Loop Play")  

The ampersand (&) precedes that menu item's keyboard access key. This is shown as underlined in the Audacity menu, and allows Windows and Linux users to access that item without a mouse. Translators are encouraged to choose unique access keys for each translated item in the particular Audacity menu.

Finally, you will find many strings like "There were %d buffer underruns, last near %lf seconds." The %d and %lf sequences mark places where numbers or names will be inserted into the string. The letters after the % sign determine the type of the variable that will be inserted, so it is vital not to change these % sequences. For example, after inserting values this string might become "There were 4 buffer underruns, last near 3.01 seconds." If you change the order of the % markers in a string, add 1$ after the percent sign that used to be first, 2$ after the percent sign that used to be second, and so on. For example:

_("The buffer underrun near %%2$lf seconds was the last of %%1$d.")

This ensures that the correct variable is inserted in the correct place in the string when the text is displayed.

Tools

Tools used in translation:

Poedit

Poedit is a cross-platform editor for the translation files with a wxWidgets-based interface.

KBabel

KBabel for the KDE desktop environment can also be used to edit .po files for other projects.

xggettext

A utility to extract the translatable strings from the source code. This is bundled with Poedit.

Note: Under Windows there is a bug in xgettext: in order to get it to detect all strings inside the '_()' brackets, you must use the option "-k_".


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:

  1. Extracting all the new English strings from the source code to create a .pot file
  2. Merging the new English strings into the existing .po file, marking up which ones have changed slightly (called "fuzzy"), and which ones are unchanged
  3. 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
 make audacity.pot
  • For the web site, change directory into the "locale" directory of the website sources, and run
 make audacity_website.pot

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.

Command line

If you have the relevant source code, then you can run at the command line:

 make updatepo

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.

Poedit

  1. Download:
    * 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".
  2. Launch Poedit, click File > Open... and select your downloaded .po file
  3. Click Catalog > Update from POT file... and select your downloaded .pot file and click Open
  4. 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
  5. 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.