TRANSLATORS

   1 Ardour User Interface Translation How-To
   2
   3 Ardour's user interface can be translated into many languages. For this the
   4 application uses gettext engine. It works like this: there is a plain text
   5 editable PO file for every language that contains a number of sequences like: a
   6 line in English, a line in target language and a reference to a line in source
   7 code where original text in English comes from. The build system then creates a
   8 binary version of each PO file with MO file extension and places it in a system
   9 directory where running instance of Ardour will pick and use it.
  10
  11 Ardour has two main PO files to translate: for user interface and for Ardour's
  12 library. Some messages from the library are actually passed to user interface
  13 (various warnings, for example), so ideally you have to translate both. For
  14 example, Russian translations are located here:
  15
  16 gtk2_ardour/po/ru.po
  17 libs/ardour/po/ru.po
  18
  19 There are few supplementation translations that can be found here (again,
  20 showing the case for Russian):
  21
  22 libs/gtkmm2ext/po/ru.po
  23
  24 You might want to translate the appdata file as well which is here to help
  25 distribution's packagers (showing the case for French)
  26
  27 gtk2_ardour/appdata/po/fr.po
  28
  29 Every PO file's name is a two-character code, e.g. 'de' for German, 'es' for
  30 Spanish, and so on. However it's fairly common to have localizations for local
  31 versions of a language, e.g. 'pt_BR' would stand for Brazilian Portuguese, and
  32 'es_MX' would stand for Mexican Spanish. Please refer to ISO language code
  33 table for details.
  34
  35 Here is the best workflow for existing translations.
  36
  37 1. Build Ardour  using './waf' command (this step is actually optional).
  38
  39 2a. If there is no existing translation for your language, run './waf i18n_pot'
  40 which will generate a POT (.pot) file for each of the directories shown
  41 above. For each directory you plan to translate, rename the POT file to end in
  42 .po and then continue with step 3.
  43
  44 2b. If there is an existing translation for your language, run './waf
  45 i18n_po' which will bring it up to date (along with all other PO files)
  46
  47 3. Open the relevant PO file in you PO editor of choice (see below).
  48
  49 4. Open Ardour, find something untranslated, locate this phrase in PO file,
  50 translate.
  51
  52 5. Repeat previous step several times, save the PO file.
  53
  54 6. Run './waf i18n_mo' to regenerate binary MO files and 'sudo ./waf install'
  55 to install them.
  56
  57 7. Restart Ardour to see what your translation looks like and whether it needs
  58 fixes, e.g. has to be shorter.
  59
  60 Note that as of Ardour 4 the translations are only installed when you run
  61 './waf i18n' after './waf' and before 'sudo ./waf install'.
  62
  63 When you are done translating, it's best to get credited for your contribution.
  64 Here is how you can do it:
  65
  66 1. Run 'git commit -a' (assuming you only modified translation files) and
  67 describe the changes you made. Typically the commit message looks like
  68 'Update German translation'. That should be sufficient.
  69
  70 2. Run 'git format-patch origin/master' (assuming you worked on a clone of the
  71 master branch. That should generate a file called something like
  72 '0001-Update-German-translation.patch'.
  73
  74 3. Run 'bzip2 0001-Update-German-translation.patch' to compress the file.
  75
  76 4. File a new bug report at http://tracker.ardour.org and attach the resulted
  77 compressed file and tell either rgareus (Robin Gareus) or las (Paul Davis) on
  78 the project's IRC channel (#ardour at irc.freenode.net) about your patch.
  79
  80 There are some more things you need to know.
  81
  82 1. Where does a phrase come from?
  83
  84 Often when you go through translation hunting for untranslated messages, you
  85 stumble upon things you have no idea where they come from. To assist you there
  86 most advanced PO editors have means to tell you which source code file it comes
  87 from, or, in some cases, even show the context in source code. Ardour has
  88 pretty much meaningful names for source code files, so it should help. If it
  89 doesn't, please ask on IRC for help.
  90
  91 2. Variables
  92
  93 You will often meet things like "%1" or "%2" in the translation files. This is
  94 a variable that should be left intact. Here is an example:
  95
  96 "Cannot load XML for session from %1"
  97
  98 When Ardour runs, this "%1" will be substituted with "Ardour" so that the whole
  99 phrase will be "Cannot load XML for session from Ardour". If Mixbus (an
 100 commercial Ardour's spin-off) runs, this will be "Cannot load XML for session
 101 from Mixbus" instead. You get the idea. So just place this variable in your
 102 translation in a way that makes the phrase sound natural in your language and
 103 make sure you know where the phrase comes from (see above) so that you know how
 104 to translate it correctly.
 105
 106 3. Plural forms
 107
 108 English has two plural forms, but many other languages have three and even four
 109 plural forms. Some parts of Ardour's code respect that, but some not (check for
 110 existing bug reports). A PO editor usually simplifies translating every plural
 111 form by putting every plural form into a dedicated tab.
 112
 113 Not every PO editor can calculate the equation for the plural forms in your
 114 language, but you can look it up in headers of PO files from some application
 115 such a GIMP or Inkscape. Here is an example for Russian:
 116
 117 http://git.gnome.org/browse/gimp/plain/po/ru.po
 118
 119 "Plural-Forms: nplurals=3; plural=(n%10==1 && n%100!=11 ? 0 : n%10>=2 && n"
 120 "%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2); 10<=4 && (n%100<10 || n"
 121 "%100>=20) ? 1 : 2);\n"
 122
 123 4. Special case when translating
 124
 125 4a. slash
 126 If you find something like : "Preferences/GUI", you will want to translate the whole thing.
 127 Example for French : "Préférences/Interface graphique" .
 128
 129 4b. pipe
 130 If you find something like : "Preferences|GUI", you will only want to translate the second part.
 131 Example for French : "Interface graphique".
 132
 133
 134 5. PO editors
 135
 136 It's really up to you which PO editor you choose. These ones are most popular:
 137
 138 poEdit. It works on Linux, Mac and Windows. The user interface is fairly simple.
 139
 140 Lokalize. Part of KDE desktop environment. It's a fairly advanced translation tool.
 141
 142 GTranslator. Usually considered as GNOME translation tool, but has very few
 143 actual GNOME dependencies. Feature-wise it's somewhere between poEdit and
 144 Lokalize.