Difference between revisions of "Translating Audacity"

From Audacity Wiki
Jump to: navigation, search
(Updating Translations: step by step instructions for doing translation updates (as I see it))
(added Poedit instructions and few links + tidy)
Line 1: Line 1:
Audacity is localized into many languages.
+
{{Introrel|Audacity and its [http://audacity.sourceforge.net/ main web site] are localized into many languages using the [http://www.gnu.org/software/gettext/ gettext] message catalogue system. This page summarises how the translations are made and updated.||[[Editing audacity.sourceforge.net]]}}
 
+
 
 
==Source Code==
 
==Source Code==
  
Line 9: Line 9:
 
Such strings are detected by the 'xgettext' utility.
 
Such strings are detected by the 'xgettext' utility.
  
Strings which are not to be translated are written like so:
+
Strings which are '''not''' to be translated are written like so:
  
 
   wxT("Don't translate this")
 
   wxT("Don't translate this")
Line 21: Line 21:
 
   wxString(_("The file " )) + filename + _("could not be found.")
 
   wxString(_("The file " )) + filename + _("could not be found.")
  
Use instead:
+
use instead:
  
 
   wxString::Format(_("The file %s could not be found"), filename.c_str )
 
   wxString::Format(_("The file %s could not be found"), filename.c_str )
Line 27: Line 27:
 
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 text.  The html tags are not to be translated. In addition in places these embedded html strings have hyperlinks in wiki syntax, like so:
+
Some parts of the source code contain html text.  Do not translate the html tags. Also in places, these embedded html strings have hyperlinks in Wiki syntax, like so:
  
 
   <nowiki>[[export|Exporting to MP3]]</nowiki>
 
   <nowiki>[[export|Exporting to MP3]]</nowiki>
  
In the .po file, translators should translate the second part, but '''not''' the first part.
+
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 contain keyboard shortcuts, like so:
 +
  _("&Loop Play\tShift+Spacebar") 
  
== Updating Translations ==
+
In the .po file, translators should translate only the first part before the "\t", and not the second part (the shortcut itself). Unfortunately, translating the shortcuts themselves prevents them working when Audacity is initialised in that language. The ampersand (&) in the first part precedes the key which activates the menu item.   
The most common translation exercise in Audacity development is updating an existing translation for changes in the program or website resulting in new or revised English text to translate. The process is in three parts:
+
 
# Extracting all the new English strings from the Audacity source code to create a '''.pot''' file
+
 
# Merging the new English strings into the existing '''.po''' file, marking up which ones have changed slightly, and which ones are unchanged.
+
==Tools==
# Updating the '''.po''' files with new and amended translations.
+
 
 +
Tools used in translation:
 +
===Poedit===
 +
[http://www.poedit.net/index.php Poedit] is a cross-platform editor for the translation files with a wxWidgets-based interface.
 +
===KBabel===
 +
[http://i18n.kde.org/tools/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.
 +
{{Hint|'''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:
 +
# 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 ===
 
=== Generating the '''.pot''' file ===
The first step is usually done by the Audacity developers, with the .pot files published on the Audacity website ([http://audacity.sourceforge.net/locale/audacity.pot Audacity .pot file], [http://audacity.sourceforge.net/locale/audacity_website.pot Audacity Website .pot file]).
+
The first step is usually done by the Audacity developers, using the .pot files published on the Audacity web site ([http://audacity.sourceforge.net/locale/audacity.pot Audacity .pot file], [http://audacity.sourceforge.net/locale/audacity_website.pot Audacity website .pot file]).
However if you wish to generate your own pot file from the Audacity sources you can do so:
+
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 Audacity itself, change directory into the "locale" directory of the sources, and run  
 
   make audacity.pot
 
   make audacity.pot
* For the website, change directory into the locale directory of the website sources, and run  
+
* For the web site, change directory into the "locale" directory of the website sources, and run  
 
   make audacity_website.pot
 
   make audacity_website.pot
  
 
=== Updating the '''.po''' file with new messages ===
 
=== Updating the '''.po''' file with new messages ===
This may be block done 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  
+
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.  
make updatepo
+
 
 +
====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:
 
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
 
   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.
+
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
+
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
 
   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.
 
Now you have a '''.po''' file with new strings in it, and the actual translation can be done.
 +
 +
==== Poedit====
 +
# Download:<br>* the latest .po file (the existing translation) for the Audacity program or web site ([http://audacity.cvs.sourceforge.net/audacity/audacity-src/locale/ Audacity .po files], [http://audacity.cvs.sourceforge.net/audacity/htdocs/locale/ Audacity website .po files])<br>* the latest .pot file (the current strings in the source code) for the Audacity program or web site ([http://audacity.sourceforge.net/locale/audacity.pot Audacity .pot file], [http://audacity.sourceforge.net/locale/audacity_website.pot Audacity website .pot file])
 +
# Launch Poedit, click {{menu|File > Open...}} and select your downloaded '''.po''' file
 +
# Click {{menu|Catalog > Update from POT file...}} 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 ===
 
=== Translating the new strings ===
You can now load the '''.po''' file into your favourite po-file editor, and start to translate.
+
With the '''.po''' file loaded into your favourite po-file editor, you can start to translate.
* If strings are already translated in the '''.po''' file, then they haven't changed, and you should be able to ignore them.
+
* Untranslated strings obviously need to be translated as normal. In Poedit they show as blue at the top of the window.  
* If strings are marked as Fuzzy translations, then they need to be reviewed against the modified English version to see if the translation is still valid.
+
* 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.  
* Untranslated strings obviously need to be translated as normal.
+
* 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.   
Once you have a new translated '''.po''' file, send it in for inclusion in Audacity.
 
 
 
==Tools==
 
 
 
Tools used in translation:
 
===poEdit===
 
This is a wxWidgets based editor for the translation files.
 
===Kbabel===
 
The translation tool from 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 codeThis is bundled with poEdit.
 
  
Note that under windows there is a bug in xgettext, and that in order to get it to detect all strings inside the '_()' brackets, you must use the option "-k_".
+
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.
  
  
 
[[Category:Internationalization]][[Category:For Developers]]
 
[[Category:Internationalization]][[Category:For Developers]]

Revision as of 09:16, 16 November 2008

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.

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 text. 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 contain keyboard shortcuts, like so:

 _("&Loop Play\tShift+Spacebar")  

In the .po file, translators should translate only the first part before the "\t", and not the second part (the shortcut itself). Unfortunately, translating the shortcuts themselves prevents them working when Audacity is initialised in that language. The ampersand (&) in the first part precedes the key which activates the menu item.


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)
  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.