Strings & translatable code - audacity/audacity GitHub Wiki

Format strings

Format strings are often used in Audacity to insert variables into pre-defined strings. So for example:

   wxString::Format( _("There were %d buffer underruns, last near %f seconds."), underruns, last_underrun )
      //Renders as: There were 2 buffer underruns, last near 14.234 seconds.
  • wxString::Format is wxWidget's implementation of a C++ printf return.
  • _() is for translatable strings (see below)
  • %d and %f are placeholders which get replaced by the parameters (here: underruns, last_underrun)

If you need to switch up the order of the placeholder relative to the order the parameters are listed in, insert a %1$ between the % and letter of the placeholder:

   wxString::Format( _("The buffer underrun near %%2$f seconds was the last of %%1$d.") underruns, last_underrun )

Translatable strings

Audacity uses gettext for translations. Because of this, the following rules apply:

  • Translatable strings look like this: _("Translate me")
  • Untranslatable strings look like this: wxT("do not translate")
  • Strings which should be extracted for translation, but not translated at runtime look like this: XO("extract only")
  • Empty strings must be untranslatable: wxT("")
  • Mark all strings as either translatable or untranslatable, even if it's just _("%s: %s") - some languages have different punctuation conventions.
  • All whitespace within strings gets rendered, both in Audacity and translation software.
  • Long strings may stay as long strings, or be broken up with \. So for example:
      _("this is a very long long string \
that continues here, without any indent, because whitespace get rendered.")
  • Different languages prefer different word orders, so keep strings in one piece using format substitutions. For example:
   wxString::Format( _("Open file %s now?"), fileName );
   /*DONT USE:*/ _("Open file") + filename + _("now?")
  • Use the wxPLURAL macro for for grammatical number (ie singular/plural - some languages do it differently):
   wxString::Format( wxPLURAL("%d hour", "%d hours", iHours), iHours ) 
      //Note: you don't need the _() or wxT() prefixes here, it's built into the macro
   /*DONT USE:*/ iHours == 1 ? _("%d hour") : _("%d hours")

HTML & Wiki Syntax.

Some parts of the code use HTML.

  • Don't mark HTML tags as translatable.
  • Avoid using HTML inside of translatable strings.

Some parts use Wiki syntax for links (ie [[page name|link title]]).

  • Only the link title gets translated.

Menu items

Menu items may have access keys, denoted with an & in the string. For example: _("&Loop Play") renders as Loop Play in the menu when the user is navigating with access keys.

  • It's up to translators which letter becomes the access key, as long as it doesn't conflict with other access keys in the same menu.
  • The Effects menu, the Generate menu and the Analyze menu do not use access keys.
⚠️ **GitHub.com Fallback** ⚠️