ChapterÂ 11.Â Translations

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

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

Note:

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

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

%svn diff -r33733:33734 en_US.ISO8859-1/books/fdp-primer/book.xml

11.6.

How do I find out who else might be translating to the
same language?

The Documentation
Project translations page 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.

If no one is listed on that page as translating for your
language, then send a message to the FreeBSD documentation project mailing list in case someone
else is thinking of doing a translation, but has not
announced it yet.

11.7.

No one else is translating to my language. What do I
do?

Congratulations, you have just started the
“FreeBSD your-language-here
Documentation Translation Project”. Welcome
aboard.

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.

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.

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.

Then pick a document and start translating. It is best
to start with something fairly small—either the FAQ,
or one of the tutorials.

11.8.

I have translated some documentation, where do I send
it?

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.

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).

11.9.

I am the only person working on translating to this
language, how do I submit my translation?

or

We are a translation team, and want to submit
documentation that our members have translated for
us.

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

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

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.

Put swedish-docs.tar.gz somewhere.
If you do not have access to your own webspace (perhaps your
ISP does not let you have any) then you can email
Documentation Engineering Team <doceng@FreeBSD.org>, and arrange to email the files when it is
convenient.

Either way, you should use Bugzilla 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.

Someone (probably the Documentation Project Manager,
currently Documentation Engineering Team <doceng@FreeBSD.org>) will then take your translation and
confirm that it builds. In particular, the following things
will be looked at:

Do all your files use RCS strings (such as
"ID")?

Does make all in the
sv_SE.ISO8859-1 directory work
correctly?

Does make install work
correctly?

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

If there are no problems your translation will be
committed as soon as possible.

11.10.

Can I include language or country specific text in my
translation?

We would prefer that you did not.

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

There is no real reason why that information should not
be in the English (or German, or Spanish, or Japanese, or
…) 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.

If you have country specific information, please submit
it as a change to the English Handbook (using
Bugzilla) and then translate the change back to your
language in the translated Handbook.

Thanks.

11.11.

How should language specific characters be
included?

Non-ASCII characters in the documentation should be
included using SGML entities.

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

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

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

Your translated documents should include their own
$FreeBSD$ line, and change the
FreeBSD Documentation Project line to
The FreeBSD language
Documentation Project.

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