Difference between revisions of "Making Audacity Translatable"

From Audacity Wiki
Jump to: navigation, search
(Extra ])
m (+deprecated)
 
(6 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 +
{{deprecated|https://github.com/audacity/audacity/wiki/Strings-&-translatable-code}}
 +
 
{{intro|1=Some guidelines for developers to make Audacity source code translatable.|2=}}
 
{{intro|1=Some guidelines for developers to make Audacity source code translatable.|2=}}
  
 
'''Useful Links:'''
 
'''Useful Links:'''
 
* [https://techbase.kde.org/Development/Tutorials/Localization/i18n_Mistakes KDE i18n Guidelines]
 
* [https://techbase.kde.org/Development/Tutorials/Localization/i18n_Mistakes KDE i18n Guidelines]
 +
* [[Translating_Audacity/Writing_Translatable_Code]]
  
  
  
Some languages prefer other punctuation conventions, such as «these» quotes, or such as leaving a space left of a colon  -- therefore,
+
Some languages prefer other '''punctuation conventions''', such as «these» quotes, or such as leaving a space left of a colon  -- Therefore:
 
{{hint|
 
{{hint|
 
* Use _() even for a format like _("%s: %s") that contains only % slots and punctuation.}}
 
* Use _() even for a format like _("%s: %s") that contains only % slots and punctuation.}}
  
Some languages vary words contextually, for gender agreement or case, though this happens very little in English -- therefore, avoid putting small isolated words into _() which you then substitute into a longer string.  Instead,
+
Some languages vary words contextually, such as for '''gender agreement or case''', though this happens very little in English -- Therefore:
 
{{hint|
 
{{hint|
* Make longer phrases in _() containing words to be translated in context.   
+
* Avoid putting small isolated words into _() which you then substitute into a longer string.
 +
** Instead make longer phrases in _() containing words to be translated in context.   
 
** Do this even at the cost of repetitious code that defines more strings, varying only the short word inside a longer phrase}}
 
** Do this even at the cost of repetitious code that defines more strings, varying only the short word inside a longer phrase}}
  
Some languages prefer different word order, such a Japanese with verbs last and postpositions rather than prepositions. -- Therefore,
+
Some languages prefer different '''word order''', such as Japanese with verbs last and postpositions rather than prepositions. -- Therefore:
 
{{hint|
 
{{hint|
* Avoid composition of user-visible strings using contatentation (+ operator) of many single words and short phrases.   
+
* Avoid composition of user-visible strings using concatenation (+ operator) of many single words and short phrases.   
 
** Use format substitutions instead to put words in place.  Concatenate long phrases and clauses only.}}
 
** Use format substitutions instead to put words in place.  Concatenate long phrases and clauses only.}}
  
Line 25: Line 29:
 
  AudacityMessageBox( wxString::Format( _("Could not open file: %s"), fileName )); // right
 
  AudacityMessageBox( wxString::Format( _("Could not open file: %s"), fileName )); // right
  
Some languages have more than two number forms of nouns (singular and plural); most of the Slavics have complicated case-agreement rules for various numerals, and Arabic has a dual.  -- Therefore  
+
Some languages have '''more than two number forms of nouns''' (singular and plural); most of the Slavics have complicated case-agreement rules for various numerals, and Arabic has a dual.  -- Therefore:
 
{{hint|
 
{{hint|
* Use the wxPLURAL macro, which cooperates with the message catalog system, so that a language can provide more than two translations as appropriate, and the run-time lookup chooses the right one according to a number.}}
+
* Use the '''wxPLURAL''' macro, which cooperates with the message catalog system, so that a language can provide more than two translations as appropriate, and the run-time lookup chooses the right one according to a number.}}
  
 
For example:
 
For example:
Line 38: Line 42:
 
   auto sHours =
 
   auto sHours =
 
     wxString::Format( wxPLURAL("%d hour", "%d hours", iHours), iHours );
 
     wxString::Format( wxPLURAL("%d hour", "%d hours", iHours), iHours );
 +
 +
Note that strings in the wxPLURAL macro must not be prefixed.  The macro inserts wxT().
  
 
{{hint|In general,  
 
{{hint|In general,  
 
* Substitute only names and numbers into translated formats, not results of other translations.   
 
* Substitute only names and numbers into translated formats, not results of other translations.   
  
There remain some difficult cases where that rule must be relaxed.}}
+
But there remain some difficult cases where that rule must be relaxed.}}

Latest revision as of 12:17, 3 September 2021

Warning icon This page has been deprecated. Newer information can be found here: https://github.com/audacity/audacity/wiki/Strings-&-translatable-code
The information on this page are likely out-of-date and will not be updated in the forseeable future. It may be removed at any time.
Some guidelines for developers to make Audacity source code translatable.

Useful Links:


Some languages prefer other punctuation conventions, such as «these» quotes, or such as leaving a space left of a colon -- Therefore:

  • Use _() even for a format like _("%s: %s") that contains only % slots and punctuation.

Some languages vary words contextually, such as for gender agreement or case, though this happens very little in English -- Therefore:

  • Avoid putting small isolated words into _() which you then substitute into a longer string.
    • Instead make longer phrases in _() containing words to be translated in context.
    • Do this even at the cost of repetitious code that defines more strings, varying only the short word inside a longer phrase

Some languages prefer different word order, such as Japanese with verbs last and postpositions rather than prepositions. -- Therefore:

  • Avoid composition of user-visible strings using concatenation (+ operator) of many single words and short phrases.
    • Use format substitutions instead to put words in place. Concatenate long phrases and clauses only.

For example:

AudacityMessageBox(_("Could not open file: ") + fileName); // wrong
AudacityMessageBox( wxString::Format( _("Could not open file: %s"), fileName )); // right

Some languages have more than two number forms of nouns (singular and plural); most of the Slavics have complicated case-agreement rules for various numerals, and Arabic has a dual. -- Therefore:

  • Use the wxPLURAL macro, which cooperates with the message catalog system, so that a language can provide more than two translations as appropriate, and the run-time lookup chooses the right one according to a number.

For example:

 // wrong:
 auto format = iHours == 1 ? _("%d hour") : _("%d hours");
 auto sHours = wxString::Format( format, iHours );

 // right:
 auto sHours =
    wxString::Format( wxPLURAL("%d hour", "%d hours", iHours), iHours );

Note that strings in the wxPLURAL macro must not be prefixed. The macro inserts wxT().


In general,
  • Substitute only names and numbers into translated formats, not results of other translations.
But there remain some difficult cases where that rule must be relaxed.