aboutsummaryrefslogtreecommitdiff
path: root/en_US.ISO8859-1/books/fdp-primer/translations/chapter.xml
blob: be0b247ff9965734eac2021ceb8ed83eb7dd2f09 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- Copyright (c) 1999 Nik Clayton, All rights reserved.

     Redistribution and use in source (SGML DocBook) and 'compiled' forms
     (SGML HTML, PDF, PostScript, RTF and so forth) with or without
     modification, are permitted provided that the following conditions
     are met:

      1. Redistributions of source code (SGML DocBook) must retain the above
         copyright notice, this list of conditions and the following
         disclaimer as the first lines of this file unmodified.

      2. Redistributions in compiled form (transformed to other DTDs,
         converted to PDF, PostScript, RTF and other formats) must reproduce
         the above copyright notice, this list of conditions and the
         following disclaimer in the documentation and/or other materials
         provided with the distribution.

     THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
     IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
     OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
     DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
     INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
     (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
     SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
     HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
     STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
     ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
     POSSIBILITY OF SUCH DAMAGE.

     $FreeBSD$
-->
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="translations">
  <title>Translations</title>

  <para>This is the FAQ for people translating the FreeBSD
    documentation (FAQ, Handbook, tutorials, manual pages, and others)
    to different languages.</para>

  <para>It is <emphasis>very</emphasis> heavily based on the
    translation FAQ from the FreeBSD German Documentation Project,
    originally written by Frank Gr&uuml;nder
    <email>elwood@mc5sys.in-berlin.de</email> and translated back to
    English by Bernd Warken <email>bwarken@mayn.de</email>.</para>

  <para>The FAQ is maintained by the &a.doceng;.</para>

  <qandaset>
    <qandaentry>
      <question>
	<para>Why a FAQ?</para>
      </question>

      <answer>
	<para>More and more people are approaching the freebsd-doc
	  mailing list and volunteering to translate FreeBSD
	  documentation to other languages.  This FAQ aims to answer
	  their questions so they can start translating documentation
	  as quickly as possible.</para>
      </answer>
    </qandaentry>

    <qandaentry>
      <question>
	<para>What do <phrase>i18n</phrase> and <phrase>l10n</phrase>
	  mean?</para>
      </question>

      <answer>
	<para><phrase>i18n</phrase> means
	  <phrase>internationalization</phrase> and
	  <phrase>l10n</phrase> means <phrase>localization</phrase>.
	  They are just a convenient shorthand.</para>

	<para><phrase>i18n</phrase> can be read as <quote>i</quote>
	  followed by 18 letters, followed by <quote>n</quote>.
	  Similarly, <phrase>l10n</phrase> is <quote>l</quote>
	  followed by 10 letters, followed by <quote>n</quote>.</para>
      </answer>
    </qandaentry>

    <qandaentry>
      <question>
	<para>Is there a mailing list for translators?</para>
      </question>

      <answer>
	<para>Yes.  Different translation groups have their own
	  mailing lists.  The <link xlink:href="http://www.freebsd.org/docproj/translations.html">list
	    of translation projects</link> has more information about
	  the mailing lists and web sites run by each translation
	  project.</para>
      </answer>
    </qandaentry>

    <qandaentry>
      <question>
	<para>Are more translators needed?</para>
      </question>

      <answer>
	<para>Yes.  The more people work on translation the faster it
	  gets done, and the faster changes to the English
	  documentation are mirrored in the translated
	  documents.</para>

	<para>You do not have to be a professional translator to be
	  able to help.</para>
      </answer>
    </qandaentry>

    <qandaentry>
      <question>
	<para>What languages do I need to know?</para>
      </question>

      <answer>
	<para>Ideally, you will have a good knowledge of written
	  English, and obviously you will need to be fluent in the
	  language you are translating to.</para>

	<para>English is not strictly necessary.  For example, you
	  could do a Hungarian translation of the FAQ from the Spanish
	  translation.</para>
      </answer>
    </qandaentry>

    <qandaentry>
      <question>
	<para>What software do I need to know?</para>
      </question>

      <answer>
	<para>It is strongly recommended that you maintain a local
	  copy of the FreeBSD Subversion repository (at least the
	  documentation part).  This can be done by running:</para>

	<screen>&prompt.user; <userinput>svn checkout https://svn0.us-east.FreeBSD.org/doc/head/ head</userinput></screen>

	<para><link xlink:href="https://svn0.us-east.FreeBSD.org/">svn0.us-east.FreeBSD.org</link>
	is a public <literal>SVN</literal> server.
	Select the closest mirror and verify the mirror server
	certificate from the list of <link xlink:href="&url.books.handbook;/svn-mirrors.html">Subversion
	mirror sites</link>.</para>

	<note>
	  <para>This will require the <package>devel/subversion</package> package to
	    be installed.</para>
	</note>

	<para>You should be comfortable using
	  <application>svn</application>.  This will allow you to see
	  what has changed between different versions of the files
	  that make up the documentation.</para>

	<para>For example, to view the differences between revisions
	  <literal>r33733</literal> and <literal>r33734</literal> of
	  <filename>en_US.ISO8859-1/books/fdp-primer/book.xml</filename>,
	  run:</para>

	<screen>&prompt.user; <userinput>svn diff -r33733:33734 en_US.ISO8859-1/books/fdp-primer/book.xml</userinput></screen>
      </answer>
    </qandaentry>

    <qandaentry>
      <question>
	<para>How do I find out who else might be translating to the
	  same language?</para>
      </question>

      <answer>
	<para>The <link xlink:href="http://www.FreeBSD.org/docproj/translations.html">Documentation
	    Project translations page</link> lists the translation
	  efforts that are currently known about.  If others are
	  already working on translating documentation to your
	  language, please do not duplicate their efforts.  Instead,
	  contact them to see how you can help.</para>

	<para>If no one is listed on that page as translating for your
	  language, then send a message to the &a.doc; in case someone
	  else is thinking of doing a translation, but has not
	  announced it yet.</para>
      </answer>
    </qandaentry>

    <qandaentry>
      <question>
	<para>No one else is translating to my language.  What do I
	  do?</para>
      </question>

      <answer>
	<para>Congratulations, you have just started the
	  <quote>FreeBSD <replaceable>your-language-here</replaceable>
	  Documentation Translation Project</quote>.  Welcome
	  aboard.</para>

	<para>First, decide whether or not you have got the time to
	  spare.  Since you are the only person working on your
	  language at the moment it is going to be your responsibility
	  to publicize your work and coordinate any volunteers that
	  might want to help you.</para>

	<para>Write an email to the Documentation Project mailing
	  list, announcing that you are going to translate the
	  documentation, so the Documentation Project translations
	  page can be maintained.</para>

	<para>If there is already someone in your country providing
	  FreeBSD mirroring services you should contact them and ask
	  if you can have some webspace for your project, and possibly
	  an email address or mailing list services.</para>

	<para>Then pick a document and start translating.  It is best
	  to start with something fairly small&mdash;either the FAQ,
	  or one of the tutorials.</para>
      </answer>
    </qandaentry>

    <qandaentry>
      <question>
	<para>I have translated some documentation, where do I send
	  it?</para>
      </question>

      <answer>
	<para>That depends.  If you are already working with a
	  translation team (such as the Japanese team, or the German
	  team) then they will have their own procedures for handling
	  submitted documentation, and these will be outlined on their
	  web pages.</para>

	<para>If you are the only person working on a particular
	  language (or you are responsible for a translation project
	  and want to submit your changes back to the FreeBSD project)
	  then you should send your translation to the FreeBSD project
	  (see the next question).</para>
      </answer>
    </qandaentry>

    <qandaentry>
      <question>
	<para>I am the only person working on translating to this
	  language, how do I submit my translation?</para>

	<para>or</para>

	<para>We are a translation team, and want to submit
	  documentation that our members have translated for
	  us.</para>
      </question>

      <answer>
	<para>First, make sure your translation is organized properly.
	  This means that it should drop into the existing
	  documentation tree and build straight away.</para>

	<para>Currently, the FreeBSD documentation is stored in a top
	  level directory called <filename>head/</filename>.
	  Directories below this are named according to the language
	  code they are written in, as defined in ISO639
	  (<filename>/usr/share/misc/iso639</filename> on a version of
	  FreeBSD newer than 20th January 1999).</para>

	<para>If your language can be encoded in different ways (for
	  example, Chinese) then there should be directories below
	  this, one for each encoding format you have provided.</para>

	<para>Finally, you should have directories for each
	  document.</para>

	<para>For example, a hypothetical Swedish translation might
	  look like:</para>

	<programlisting>head/
    sv_SE.ISO8859-1/
                     Makefile
                     htdocs/
                           docproj/
                     books/
                           faq/
                               Makefile
                               book.xml</programlisting>

	<para><literal>sv_SE.ISO8859-1</literal> is the name of the
	  translation, in
	  <filename>lang.encoding</filename>
	  form.  Note the two Makefiles, which will be used to build
	  the documentation.</para>

	<para>Use &man.tar.1; and &man.gzip.1; to compress up your
	  documentation, and send it to the project.</para>

	<screen>&prompt.user; <userinput>cd doc</userinput>
&prompt.user; <userinput>tar cf swedish-docs.tar sv_SE.ISO8859-1</userinput>
&prompt.user; <userinput>gzip -9 swedish-docs.tar</userinput></screen>

	<para>Put <filename>swedish-docs.tar.gz</filename> somewhere.
	  If you do not have access to your own webspace (perhaps your
	  ISP does not let you have any) then you can email
	  &a.doceng;, and arrange to email the files when it is
	  convenient.</para>

	<para>Either way, you should use &man.send-pr.1; to submit a
	  report indicating that you have submitted the documentation.
	  It would be very helpful if you could get other people to
	  look over your translation and double check it first, since
	  it is unlikely that the person committing it will be fluent
	  in the language.</para>

	<para>Someone (probably the Documentation Project Manager,
	  currently &a.doceng;) will then take your translation and
	  confirm that it builds.  In particular, the following things
	  will be looked at:</para>

	<orderedlist>
	  <listitem>
	    <para>Do all your files use RCS strings (such as
	      "ID")?</para>
	  </listitem>

	  <listitem>
	    <para>Does <command>make all</command> in the
	      <filename>sv_SE.ISO8859-1</filename> directory work
	      correctly?</para>
	  </listitem>

	  <listitem>
	    <para>Does <command>make install</command> work
	      correctly?</para>
	  </listitem>
	</orderedlist>

	<para>If there are any problems then whoever is looking at the
	  submission will get back to you to work them out.</para>

	<para>If there are no problems your translation will be
	  committed as soon as possible.</para>
      </answer>
    </qandaentry>

    <qandaentry>
      <question>
	<para>Can I include language or country specific text in my
	  translation?</para>
      </question>

      <answer>
	<para>We would prefer that you did not.</para>

	<para>For example, suppose that you are translating the
	  Handbook to Korean, and want to include a section about
	  retailers in Korea in your Handbook.</para>

	<para>There is no real reason why that information should not
	  be in the English (or German, or Spanish, or Japanese, or
	  &hellip;) versions as well.  It is feasible that an English
	  speaker in Korea might try to pick up a copy of FreeBSD
	  whilst over there.  It also helps increase FreeBSD's
	  perceived presence around the globe, which is not a bad
	  thing.</para>

	<para>If you have country specific information, please submit
	  it as a change to the English Handbook (using
	  &man.send-pr.1;) and then translate the change back to your
	  language in the translated Handbook.</para>

	<para>Thanks.</para>
      </answer>
    </qandaentry>

    <qandaentry>
      <question>
	<para>How should language specific characters be
	  included?</para>
      </question>

      <answer>
	<para>Non-ASCII characters in the documentation should be
	  included using SGML entities.</para>

	<para>Briefly, these look like an ampersand (&amp;), the name
	  of the entity, and a semi-colon (;).</para>

	<para>The entity names are defined in ISO8879, which is in the
	  ports tree as <package>textproc/iso8879</package>.</para>

	<para>A few examples include:</para>

	<segmentedlist>
	  <segtitle>Entity</segtitle>

	  <segtitle>Appearance</segtitle>

	  <segtitle>Description</segtitle>

	  <seglistitem>
	    <seg>&amp;eacute;</seg>
	    <seg>&eacute;</seg>
	    <seg>Small <quote>e</quote> with an acute accent</seg>
	  </seglistitem>

	  <seglistitem>
	    <seg>&amp;Eacute;</seg>
	    <seg>&Eacute;</seg>
	    <seg>Large <quote>E</quote> with an acute accent</seg>
	  </seglistitem>

	  <seglistitem>
	    <seg>&amp;uuml;</seg>
	    <seg>&uuml;</seg>
	    <seg>Small <quote>u</quote> with an umlaut</seg>
	  </seglistitem>
	</segmentedlist>

	<para>After you have installed the iso8879 port, the files in
	  <filename>/usr/local/share/xml/iso8879</filename> contain
	  the complete list.</para>
      </answer>
    </qandaentry>

    <qandaentry>
      <question>
	<para>Addressing the reader</para>
      </question>

      <answer>
	<para>In the English documents, the reader is addressed as
	  <quote>you</quote>, there is no formal/informal distinction
	  as there is in some languages.</para>

	<para>If you are translating to a language which does
	  distinguish, use whichever form is typically used in other
	  technical documentation in your language.  If in doubt, use
	  a mildly polite form.</para>
      </answer>
    </qandaentry>

    <qandaentry>
      <question>
	<para>Do I need to include any additional information in my
	  translations?</para>
      </question>

      <answer>
	<para>Yes.</para>

	<para>The header of the English version of each document will
	  look something like this:</para>

	<programlisting>&lt;!--
     The FreeBSD Documentation Project

     &dollar;FreeBSD: head/en_US.ISO8859-1/books/faq/book.xml 38674 2012-04-14 13:52:52Z &dollar;
--&gt;</programlisting>

	<para>The exact boilerplate may change, but it will always
	  include a &dollar;FreeBSD&dollar; line and the phrase
	  <literal>The FreeBSD Documentation Project</literal>.
	  Note that the &dollar;FreeBSD part is expanded automatically
	  by Subversion, so it should be empty (just
	  <literal>&dollar;FreeBSD&dollar;</literal>) for new
	  files.</para>

	<para>Your translated documents should include their own
	  &dollar;FreeBSD&dollar; line, and change the
	  <literal>FreeBSD Documentation Project</literal> line to
	  <literal>The FreeBSD language
	    Documentation Project</literal>.</para>

	<para>In addition, you should add a third line which indicates
	  which revision of the English text this is based on.</para>

	<para>So, the Spanish version of this file might start:</para>

	<programlisting>&lt;!--
     The FreeBSD Spanish Documentation Project

     &dollar;FreeBSD: head/es_ES.ISO8859-1/books/faq/book.xml 38826 2012-05-17 19:12:14Z hrs &dollar;
     Original revision: r38674
--&gt;</programlisting>
      </answer>
    </qandaentry>
  </qandaset>
</chapter>