DOCS/tech/translations.txt

   1 ________________________________________
   2 HOW TO DO A GOOD TRANSLATION FOR MPLAYER
   3 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   4
   5 We always welcome new translations, but please be aware that
   6 translations are not just one time jobs. They have to be maintained
   7 in order to be useful. Otherwise they quickly get outdated and become
   8 obsolete, useless cruft. That said, we would be happy if you could
   9 maintain a new documentation translation.
  10
  11 Experience shows that translations work best when done by teams. Not only
  12 can the workload be shared, but there is also the chance to review the
  13 translation. So if possible try to find more people to help out with
  14 translating.
  15
  16 Furthermore, if you take over an unmaintained translation, bring the existing
  17 parts up-to-date before translating new ones.  Outdated information is worse
  18 than missing information. For console messages and the XML documentation,
  19 missing parts are automatically replaced by the English versions.
  20
  21 Documentation related discussions happen on the MPlayer-DOCS mailing list,
  22 while documentation translation related discussions happen on the
  23 MPlayer-translations mailing list. If you want to maintain a translation
  24 you should subscribe to both, as the English documentation Subversion
  25 changelogs, which you need to keep the translation up to date, are sent
  26 to MPlayer-DOCS. You can subscribe here:
  27
  28 http://lists.mplayerhq.hu/mailman/listinfo/mplayer-docs
  29 http://lists.mplayerhq.hu/mailman/listinfo/mplayer-translations
  30
  31 Send updates and patches to this mailing list or directly to the translation
  32 coordination maintainer, see DOCS/tech/MAINTAINERS for details.
  33
  34 Translations of MPlayer documentation consist of 3 parts in descending
  35 order of importance:
  36
  37 0) homepage
  38 1) console messages (help/help_mp-XX.h)
  39 2) man page
  40 3) XML documentation
  41
  42 Not all parts are available in all languages. Keeping existing parts up-to-date
  43 should have precedence over adding newly translated content. It is perfectly
  44 acceptable to work on only a subset of these parts, but please follow the above
  45 order of importance nonetheless.
  46
  47 Now on to some more detailed instructions...
  48
  49 general:
  50 ~~~~~~~~
  51
  52 Please note that the help_mp files and the XML documentation are both encoded
  53 in UTF-8. Editing these files in a program which uses a different encoding
  54 will result in breaking console messages and HTML.
  55
  56 Translations are for documentation what porting is for code. Many more eyes
  57 see it and get to find mistakes. If you stumble over mistakes, inaccuracies,
  58 clumsy wording, spelling/grammar errors or if you notice that something is
  59 incomplete, please let us know, we'll fix it. Patches are more than welcome,
  60 of course. Do not, however, change the translation first, please get your
  61 update into the English version first.
  62
  63 If you have Subversion write access and commit a translation update, use
  64 something like "synced with rXXX" as first line of the commit message so
  65 that it is possible to tell with a glance at the Subversion log or ViewVC
  66 if the translation is outdated and which revision of the English master
  67 file it is equivalent to.
  68
  69 If you make (spelling/wording/consistency/etc) changes to a file without
  70 adapting parts that changed in the English master file, leave the sync
  71 tag as it is.
  72
  73
  74 homepage:
  75 ~~~~~~~~~
  76
  77 Get the homepage from Subversion with
  78
  79   svn checkout svn://svn.mplayerhq.hu/homepage/trunk/ homepage
  80
  81 or browse the sources online at
  82
  83 http://svn.mplayerhq.hu/homepage/trunk/
  84
  85 The homepage uses design template files that are combined with the content
  86 files to form the final HTML pages. To build the HTML pages, type 'make' in
  87 the root of the homepage source directory.
  88
  89
  90 console messages:
  91 ~~~~~~~~~~~~~~~~~
  92
  93 You can find the latest versions of the help_mp-XX.h files in Subversion or
  94 here:
  95
  96 http://svn.mplayerhq.hu/mplayer/trunk/help/
  97
  98 help_mp-en.h is the master file that you should use as a base for translations.
  99 If you are adopting an already existing translation, please check it from top
 100 to bottom once. Later it should suffice to just translate missing messages.
 101 Additionally, please make sure that your translated messages fit on an 80
 102 character wide display to avoid overflowing output.
 103
 104 TOOLS/mphelp_check.py is a small tool to check translated files. It will report
 105 conflicting arguments, strings not present in the master file and (optionally)
 106 strings missing from the translation. Running it as
 107
 108   TOOLS/mphelp_check.py help/help_mp-en.h help/help_mp-XX.h
 109
 110 will output errors to the screen, just substitute XX with your language code.
 111 Adding the -missing option to the command line as in
 112
 113   TOOLS/mphelp_check.py -missing help/help_mp-en.h help/help_mp-XX.h
 114
 115 will additionally print untranslated messages to the screen.
 116
 117 If you do not translate all messages at once, please do not leave untranslated
 118 messages in your translated file, just leave them out instead. The MPlayer
 119 build system automatically checks for missing messages and uses the English
 120 ones instead. This has the added advantage of providing the latest versions of
 121 the English messages, since English messages in translations may be outdated.
 122 Furthermore, running help_diff.sh on your translated file will immediately show
 123 missing messages, which eases further translation.
 124
 125 If no messages are missing, please add a line similar to
 126
 127   /* Synced with help_mp-en.h rXXX */
 128
 129 to the file header, replacing XXX with the revision of help_mp-en.h that your
 130 translation is in sync with. This way we can easily tell if the translation
 131 is up to date or not.
 132
 133
 134 XML documentation:
 135 ~~~~~~~~~~~~~~~~~~
 136
 137 If you make changes to the XML documentation, doublecheck that the
 138 documentation still builds by running 'make' in the DOCS/xml/ subdirectory.