annotate DOCS/tech/translations.txt @ 18750:5a8e868772f3

fix link to help_mp-XX.h files in svn repo

________________________________________
HOW TO DO A GOOD TRANSLATION FOR MPLAYER
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

We always welcome new translations, but please be aware that
translations are not just one time jobs. They have to be maintained
in order to be useful. Otherwise they quickly get outdated and become
obsolete, useless cruft. That said, we would be happy if you could
maintain a new documentation translation.

Documentation related discussions happen on the MPlayer-DOCS mailing list,
while documentation translation related discussions happen on the
MPlayer-translations mailing list. If you want to maintain a translation
you should subscribe to both, as the English documentation CVS changelogs,
which you need to keep the translation up to date, are sent to MPlayer-DOCS.
You can subscribe here:

http://mplayerhq.hu/mailman/listinfo/mplayer-docs
http://mplayerhq.hu/mailman/listinfo/mplayer-translations

Send updates and patches to this mailing list or directly to the documentation
or console message maintainers, see DOCS/tech/MAINTAINERS for details.

Translations of MPlayer documentation consist of 3 parts in descending
order of importance:

1) console messages (help/help_mp-XX.h)
2) man page
3) XML documentation

Please note that only doing 1) or 1) + 2) is perfectly fine.

You can find the latest versions of the help_mp-XX.h files in CVS or
here:

http://svn.mplayerhq.hu/mplayer/trunk/help/

help_mp-en.h is the master file that you should use as a base for translations.
If you are adopting an already existing translation, please check it from top
to bottom once. Later it should suffice to just translate missing messages.
Additionally, please make sure that your translated messages fit on an 80
character wide display to avoid overflowing output.

TOOLS/mphelp_check.py is a small tool to check translated files. It will report
conflicting arguments, strings not present in the master file and (optionally)
strings missing from the translation. Running it as

  mphelp_check.py help_mp-en.h help_mp-XX.h

will output errors to the screen, just substitute XX with your language code.

  mphelp_check.py -missing help_mp-en.h help_mp-XX.h

will additionally print untranslated messages to the screen.

If you do not translate all messages at once, please do not leave untranslated
messages in your translated file, just leave them out instead. The MPlayer
build system automatically checks for missing messages and uses the English
ones instead. This has the added advantage of providing the latest versions of
the English messages, since English messages in translations may be outdated.
Furthermore, running help_diff.sh on your translated file will immediately show
missing messages, which eases further translation.

If no messages are missing, please add a line similar to

  /* Synced with help_mp-en.h 1.XXX */

to the file header, replacing XXX with the revision of help_mp-en.h that your
translation is in sync with. This way we can easily tell if the translation
is up to date or not.

Translations are for documentation what porting is for code. Many more eyes
see it and get to find mistakes. If you stumble over mistakes, inaccuracies,
clumsy wording, spelling/grammar errors or if you notice that something is
incomplete, please let us know, we'll fix it. Patches are more than welcome,
of course. Do not, however, change the translation first, please get your
update into the English version first.

If you have CVS access and commit a translation update file, use something like
"synced with 1.XXX" as first line of the commit message so that it is possible
to tell with a glance at the cvs log or viewcvs if the translation is outdated
and which revision of the English master file it is equivalent to.