Mercurial > mplayer.hg
annotate DOCS/tech/translations.txt @ 26655:733f7ac7a855
Move some blocks around for better text structuring.
author | diego |
---|---|
date | Thu, 08 May 2008 00:04:27 +0000 |
parents | 12da50bb6292 |
children | ceb7404032e2 |
rev | line source |
---|---|
11809 | 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 | |
26655
733f7ac7a855
Move some blocks around for better text structuring.
diego
parents:
26654
diff
changeset
|
11 Experience shows that translations work best when done by teams. Not only |
733f7ac7a855
Move some blocks around for better text structuring.
diego
parents:
26654
diff
changeset
|
12 can the workload be shared, but there is also the chance to review the |
733f7ac7a855
Move some blocks around for better text structuring.
diego
parents:
26654
diff
changeset
|
13 translation. So if possible try to find more people to help out with |
733f7ac7a855
Move some blocks around for better text structuring.
diego
parents:
26654
diff
changeset
|
14 translating. |
733f7ac7a855
Move some blocks around for better text structuring.
diego
parents:
26654
diff
changeset
|
15 |
733f7ac7a855
Move some blocks around for better text structuring.
diego
parents:
26654
diff
changeset
|
16 Furthermore, if you take over an unmaintained translation, bring the existing |
733f7ac7a855
Move some blocks around for better text structuring.
diego
parents:
26654
diff
changeset
|
17 parts up-to-date before translating new ones. Outdated information is worse |
733f7ac7a855
Move some blocks around for better text structuring.
diego
parents:
26654
diff
changeset
|
18 than missing information. For console messages and the XML documentation, |
733f7ac7a855
Move some blocks around for better text structuring.
diego
parents:
26654
diff
changeset
|
19 missing parts are automatically replaced by the English versions. |
733f7ac7a855
Move some blocks around for better text structuring.
diego
parents:
26654
diff
changeset
|
20 |
16120
cc8e5b36f1ed
Mention the MPlayer-translations mailing list and explain the difference
diego
parents:
14558
diff
changeset
|
21 Documentation related discussions happen on the MPlayer-DOCS mailing list, |
cc8e5b36f1ed
Mention the MPlayer-translations mailing list and explain the difference
diego
parents:
14558
diff
changeset
|
22 while documentation translation related discussions happen on the |
cc8e5b36f1ed
Mention the MPlayer-translations mailing list and explain the difference
diego
parents:
14558
diff
changeset
|
23 MPlayer-translations mailing list. If you want to maintain a translation |
19657 | 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: | |
11809 | 27 |
20232 | 28 http://lists.mplayerhq.hu/mailman/listinfo/mplayer-docs |
29 http://lists.mplayerhq.hu/mailman/listinfo/mplayer-translations | |
11809 | 30 |
23180 | 31 Send updates and patches to this mailing list or directly to the translation |
32 coordination maintainer, see DOCS/tech/MAINTAINERS for details. | |
11809 | 33 |
34 Translations of MPlayer documentation consist of 3 parts in descending | |
35 order of importance: | |
36 | |
37 1) console messages (help/help_mp-XX.h) | |
38 2) man page | |
39 3) XML documentation | |
40 | |
41 Please note that only doing 1) or 1) + 2) is perfectly fine. | |
42 | |
26654 | 43 |
26655
733f7ac7a855
Move some blocks around for better text structuring.
diego
parents:
26654
diff
changeset
|
44 general: |
733f7ac7a855
Move some blocks around for better text structuring.
diego
parents:
26654
diff
changeset
|
45 ~~~~~~~~ |
733f7ac7a855
Move some blocks around for better text structuring.
diego
parents:
26654
diff
changeset
|
46 |
733f7ac7a855
Move some blocks around for better text structuring.
diego
parents:
26654
diff
changeset
|
47 Please note that the help_mp files and the XML documentation are both encoded |
733f7ac7a855
Move some blocks around for better text structuring.
diego
parents:
26654
diff
changeset
|
48 in UTF-8. Editing these files in a program which uses a different encoding |
733f7ac7a855
Move some blocks around for better text structuring.
diego
parents:
26654
diff
changeset
|
49 will result in breaking console messages and HTML. |
733f7ac7a855
Move some blocks around for better text structuring.
diego
parents:
26654
diff
changeset
|
50 |
733f7ac7a855
Move some blocks around for better text structuring.
diego
parents:
26654
diff
changeset
|
51 Translations are for documentation what porting is for code. Many more eyes |
733f7ac7a855
Move some blocks around for better text structuring.
diego
parents:
26654
diff
changeset
|
52 see it and get to find mistakes. If you stumble over mistakes, inaccuracies, |
733f7ac7a855
Move some blocks around for better text structuring.
diego
parents:
26654
diff
changeset
|
53 clumsy wording, spelling/grammar errors or if you notice that something is |
733f7ac7a855
Move some blocks around for better text structuring.
diego
parents:
26654
diff
changeset
|
54 incomplete, please let us know, we'll fix it. Patches are more than welcome, |
733f7ac7a855
Move some blocks around for better text structuring.
diego
parents:
26654
diff
changeset
|
55 of course. Do not, however, change the translation first, please get your |
733f7ac7a855
Move some blocks around for better text structuring.
diego
parents:
26654
diff
changeset
|
56 update into the English version first. |
733f7ac7a855
Move some blocks around for better text structuring.
diego
parents:
26654
diff
changeset
|
57 |
733f7ac7a855
Move some blocks around for better text structuring.
diego
parents:
26654
diff
changeset
|
58 If you have Subversion write access and commit a translation update, use |
733f7ac7a855
Move some blocks around for better text structuring.
diego
parents:
26654
diff
changeset
|
59 something like "synced with rXXX" as first line of the commit message so |
733f7ac7a855
Move some blocks around for better text structuring.
diego
parents:
26654
diff
changeset
|
60 that it is possible to tell with a glance at the Subversion log or ViewVC |
733f7ac7a855
Move some blocks around for better text structuring.
diego
parents:
26654
diff
changeset
|
61 if the translation is outdated and which revision of the English master |
733f7ac7a855
Move some blocks around for better text structuring.
diego
parents:
26654
diff
changeset
|
62 file it is equivalent to. |
733f7ac7a855
Move some blocks around for better text structuring.
diego
parents:
26654
diff
changeset
|
63 |
733f7ac7a855
Move some blocks around for better text structuring.
diego
parents:
26654
diff
changeset
|
64 If you make (spelling/wording/consistency/etc) changes to a file without |
733f7ac7a855
Move some blocks around for better text structuring.
diego
parents:
26654
diff
changeset
|
65 adapting parts that changed in the English master file, leave the sync |
733f7ac7a855
Move some blocks around for better text structuring.
diego
parents:
26654
diff
changeset
|
66 tag as it is. |
733f7ac7a855
Move some blocks around for better text structuring.
diego
parents:
26654
diff
changeset
|
67 |
733f7ac7a855
Move some blocks around for better text structuring.
diego
parents:
26654
diff
changeset
|
68 |
26654 | 69 console messages: |
70 ~~~~~~~~~~~~~~~~~ | |
71 | |
19657 | 72 You can find the latest versions of the help_mp-XX.h files in Subversion or |
11809 | 73 here: |
74 | |
18750 | 75 http://svn.mplayerhq.hu/mplayer/trunk/help/ |
11809 | 76 |
77 help_mp-en.h is the master file that you should use as a base for translations. | |
78 If you are adopting an already existing translation, please check it from top | |
18539 | 79 to bottom once. Later it should suffice to just translate missing messages. |
80 Additionally, please make sure that your translated messages fit on an 80 | |
81 character wide display to avoid overflowing output. | |
82 | |
83 TOOLS/mphelp_check.py is a small tool to check translated files. It will report | |
84 conflicting arguments, strings not present in the master file and (optionally) | |
85 strings missing from the translation. Running it as | |
11809 | 86 |
26652
41f5023fe2bd
more complete mphelp_check.py command lines, typo, clarifications
diego
parents:
23180
diff
changeset
|
87 TOOLS/mphelp_check.py help/help_mp-en.h help/help_mp-XX.h |
18539 | 88 |
89 will output errors to the screen, just substitute XX with your language code. | |
26652
41f5023fe2bd
more complete mphelp_check.py command lines, typo, clarifications
diego
parents:
23180
diff
changeset
|
90 Adding the -missing option to the command line as in |
11809 | 91 |
26652
41f5023fe2bd
more complete mphelp_check.py command lines, typo, clarifications
diego
parents:
23180
diff
changeset
|
92 TOOLS/mphelp_check.py -missing help/help_mp-en.h help/help_mp-XX.h |
18539 | 93 |
94 will additionally print untranslated messages to the screen. | |
11809 | 95 |
12091
c67c28e4992e
How to handle incomplete translations of message files.
diego
parents:
11809
diff
changeset
|
96 If you do not translate all messages at once, please do not leave untranslated |
c67c28e4992e
How to handle incomplete translations of message files.
diego
parents:
11809
diff
changeset
|
97 messages in your translated file, just leave them out instead. The MPlayer |
c67c28e4992e
How to handle incomplete translations of message files.
diego
parents:
11809
diff
changeset
|
98 build system automatically checks for missing messages and uses the English |
c67c28e4992e
How to handle incomplete translations of message files.
diego
parents:
11809
diff
changeset
|
99 ones instead. This has the added advantage of providing the latest versions of |
c67c28e4992e
How to handle incomplete translations of message files.
diego
parents:
11809
diff
changeset
|
100 the English messages, since English messages in translations may be outdated. |
c67c28e4992e
How to handle incomplete translations of message files.
diego
parents:
11809
diff
changeset
|
101 Furthermore, running help_diff.sh on your translated file will immediately show |
c67c28e4992e
How to handle incomplete translations of message files.
diego
parents:
11809
diff
changeset
|
102 missing messages, which eases further translation. |
c67c28e4992e
How to handle incomplete translations of message files.
diego
parents:
11809
diff
changeset
|
103 |
16791
fe601b7b10c8
Add a note about the "synce with 1.XXX" line that should be in every
diego
parents:
16120
diff
changeset
|
104 If no messages are missing, please add a line similar to |
fe601b7b10c8
Add a note about the "synce with 1.XXX" line that should be in every
diego
parents:
16120
diff
changeset
|
105 |
19704
338961243006
Some more CVS --> Subversion changes, explain what to do with the sync tag
diego
parents:
19658
diff
changeset
|
106 /* Synced with help_mp-en.h rXXX */ |
16791
fe601b7b10c8
Add a note about the "synce with 1.XXX" line that should be in every
diego
parents:
16120
diff
changeset
|
107 |
fe601b7b10c8
Add a note about the "synce with 1.XXX" line that should be in every
diego
parents:
16120
diff
changeset
|
108 to the file header, replacing XXX with the revision of help_mp-en.h that your |
fe601b7b10c8
Add a note about the "synce with 1.XXX" line that should be in every
diego
parents:
16120
diff
changeset
|
109 translation is in sync with. This way we can easily tell if the translation |
fe601b7b10c8
Add a note about the "synce with 1.XXX" line that should be in every
diego
parents:
16120
diff
changeset
|
110 is up to date or not. |
fe601b7b10c8
Add a note about the "synce with 1.XXX" line that should be in every
diego
parents:
16120
diff
changeset
|
111 |
26654 | 112 |
113 XML documentation: | |
114 ~~~~~~~~~~~~~~~~~~ | |
115 | |
20025 | 116 If you make changes to the XML documentation, doublecheck that the |
26652
41f5023fe2bd
more complete mphelp_check.py command lines, typo, clarifications
diego
parents:
23180
diff
changeset
|
117 documentation still builds by running 'make' in the DOCS/xml/ subdirectory. |