________________________________________ 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. Experience shows that translations work best when done by teams. Not only can the workload be shared, but there is also the chance to review the translation. So if possible try to find more people to help out with translating. Furthermore, if you take over an unmaintained translation, bring the existing parts up-to-date before translating new ones. Outdated information is worse than missing information. For console messages, GUI localization and the XML documentation, missing parts are automatically replaced by the English versions. 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 Subversion changelogs, which you need to keep the translation up to date, are sent to MPlayer-DOCS. You can subscribe here: http://lists.mplayerhq.hu/mailman/listinfo/mplayer-docs http://lists.mplayerhq.hu/mailman/listinfo/mplayer-translations Send updates and patches to this mailing list or directly to the translation coordination maintainer, see DOCS/tech/MAINTAINERS for details. Translations of MPlayer documentation consist of 3 parts in descending order of importance: 0) homepage 1) console messages and GUI localization (help/help_mp-XX.h) 2) man page 3) XML documentation Not all parts are available in all languages. Keeping existing parts up-to-date should have precedence over adding newly translated content. It is perfectly acceptable to work on only a subset of these parts, but please follow the above order of importance nonetheless. Now on to some more detailed instructions... general: ~~~~~~~~ Please note that the help_mp files and the XML documentation are both encoded in UTF-8. Editing these files in a program which uses a different encoding will result in breaking console messages, GUI localization and HTML. 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 Subversion write access and commit a translation update, use something like "synced with rXXX" as first line of the commit message so that it is possible to tell with a glance at the Subversion log or ViewVC if the translation is outdated and which revision of the English master file it is equivalent to. If you make (spelling/wording/consistency/etc) changes to a file without adapting parts that changed in the English master file, leave the sync tag as it is. homepage: ~~~~~~~~~ Get the homepage from Subversion with svn checkout svn://svn.mplayerhq.hu/homepage/trunk/ homepage or browse the sources online at http://svn.mplayerhq.hu/homepage/trunk/ The homepage uses design template files that are combined with the content files to form the final HTML pages. To build the HTML pages, type 'make' in the root of the homepage source directory. console messages / GUI localization: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ You can find the latest versions of the help_mp-XX.h files in Subversion 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. You are strongly encouraged to use TOOLS/mphelp_check.py, a small tool to check translated files. It will report conflicting definitions, mismatching arguments, extra definitions not present in the master file and (optionally) definitions missing from the translation. Running it as TOOLS/mphelp_check.py help/help_mp-en.h help/help_mp-XX.h will output errors to the screen, just substitute XX with your language code. Adding the -missing option to the command line as in TOOLS/mphelp_check.py -missing help/help_mp-en.h help/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. If no messages are missing, please add a line similar to /* Synced with help_mp-en.h rXXX */ 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. XML documentation: ~~~~~~~~~~~~~~~~~~ If you make changes to the XML documentation, doublecheck that the documentation still builds by running 'make doc'. Place XML files in a new subdirectory named after the language code you are translating for. main.xml is autogenerated, do not translate it. In each translated file after the tag place a note like , where XXX is the revision of corresponding English file (see comment at the top of file).