Mercurial > mplayer.hg
annotate DOCS/tech/translations.txt @ 29864:4e79bdef6176
synced with r29885
author | ptt |
---|---|
date | Thu, 12 Nov 2009 17:04:41 +0000 |
parents | 6c9312893275 |
children | 8b541e3d05c1 |
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 | |
26657 | 37 0) homepage |
11809 | 38 1) console messages (help/help_mp-XX.h) |
39 2) man page | |
40 3) XML documentation | |
41 | |
26656 | 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. | |
11809 | 46 |
26656 | 47 Now on to some more detailed instructions... |
26654 | 48 |
26655
733f7ac7a855
Move some blocks around for better text structuring.
diego
parents:
26654
diff
changeset
|
49 general: |
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 |
733f7ac7a855
Move some blocks around for better text structuring.
diego
parents:
26654
diff
changeset
|
52 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
|
53 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
|
54 will result in breaking console messages and HTML. |
733f7ac7a855
Move some blocks around for better text structuring.
diego
parents:
26654
diff
changeset
|
55 |
733f7ac7a855
Move some blocks around for better text structuring.
diego
parents:
26654
diff
changeset
|
56 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
|
57 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
|
58 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
|
59 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
|
60 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
|
61 update into the English version first. |
733f7ac7a855
Move some blocks around for better text structuring.
diego
parents:
26654
diff
changeset
|
62 |
733f7ac7a855
Move some blocks around for better text structuring.
diego
parents:
26654
diff
changeset
|
63 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
|
64 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
|
65 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
|
66 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
|
67 file it is equivalent to. |
733f7ac7a855
Move some blocks around for better text structuring.
diego
parents:
26654
diff
changeset
|
68 |
733f7ac7a855
Move some blocks around for better text structuring.
diego
parents:
26654
diff
changeset
|
69 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
|
70 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
|
71 tag as it is. |
733f7ac7a855
Move some blocks around for better text structuring.
diego
parents:
26654
diff
changeset
|
72 |
733f7ac7a855
Move some blocks around for better text structuring.
diego
parents:
26654
diff
changeset
|
73 |
26657 | 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 | |
26654 | 90 console messages: |
91 ~~~~~~~~~~~~~~~~~ | |
92 | |
19657 | 93 You can find the latest versions of the help_mp-XX.h files in Subversion or |
11809 | 94 here: |
95 | |
18750 | 96 http://svn.mplayerhq.hu/mplayer/trunk/help/ |
11809 | 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 | |
18539 | 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 | |
11809 | 107 |
26652
41f5023fe2bd
more complete mphelp_check.py command lines, typo, clarifications
diego
parents:
23180
diff
changeset
|
108 TOOLS/mphelp_check.py help/help_mp-en.h help/help_mp-XX.h |
18539 | 109 |
110 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
|
111 Adding the -missing option to the command line as in |
11809 | 112 |
26652
41f5023fe2bd
more complete mphelp_check.py command lines, typo, clarifications
diego
parents:
23180
diff
changeset
|
113 TOOLS/mphelp_check.py -missing help/help_mp-en.h help/help_mp-XX.h |
18539 | 114 |
115 will additionally print untranslated messages to the screen. | |
11809 | 116 |
12091
c67c28e4992e
How to handle incomplete translations of message files.
diego
parents:
11809
diff
changeset
|
117 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
|
118 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
|
119 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
|
120 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
|
121 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
|
122 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
|
123 missing messages, which eases further translation. |
c67c28e4992e
How to handle incomplete translations of message files.
diego
parents:
11809
diff
changeset
|
124 |
16791
fe601b7b10c8
Add a note about the "synce with 1.XXX" line that should be in every
diego
parents:
16120
diff
changeset
|
125 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
|
126 |
19704
338961243006
Some more CVS --> Subversion changes, explain what to do with the sync tag
diego
parents:
19658
diff
changeset
|
127 /* 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
|
128 |
fe601b7b10c8
Add a note about the "synce with 1.XXX" line that should be in every
diego
parents:
16120
diff
changeset
|
129 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
|
130 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
|
131 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
|
132 |
26654 | 133 |
134 XML documentation: | |
135 ~~~~~~~~~~~~~~~~~~ | |
136 | |
20025 | 137 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
|
138 documentation still builds by running 'make' in the DOCS/xml/ subdirectory. |