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>
.
The FAQ is maintained by the Documentation Engineering Team <doceng@FreeBSD.org>
.
11.1. | What do i18n and l10n mean? |
i18n means internationalization and l10n means localization. They are just a convenient shorthand. i18n can be read as “i” followed by 18 letters, followed by “n”. Similarly, l10n is “l” followed by 10 letters, followed by “n”. | |
11.2. | Is there a mailing list for translators? |
Yes. Different translation groups have their own
mailing lists. The list
of translation projects has more information about
the mailing lists and web sites run by each translation
project. In addition there is
| |
11.3. | Are more translators needed? |
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. You do not have to be a professional translator to be able to help. | |
11.4. | What languages do I need to know? |
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. English is not strictly necessary. For example, you could do a Hungarian translation of the FAQ from the Spanish translation. | |
11.5. | What software do I need to know? |
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:
svn.FreeBSD.org
is a public Note:This will require the devel/subversion package to be installed. 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
Please see the complete explanation of using Subversion in FreeBSD in the FreeBSD Handbook. | |
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 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 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. Finally, you should have directories for each document. For example, a hypothetical Swedish translation might look like: head/ sv_SE.ISO8859-1/ Makefile htdocs/ docproj/ books/ faq/ Makefile book.xml
Use tar(1) and gzip(1) to compress up your documentation, and send it to the project.
Put 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
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. A few examples include: Entity: é Appearance: é Description: Small “e” with an acute accent Entity: É Appearance: É Description: Large “E” with an acute accent Entity: ü Appearance: ü Description: Small “u” with an umlaut After you have installed the iso8879 port, the files in
| |
11.12. | Addressing the reader |
In the English documents, the reader is addressed as “you”, there is no formal/informal distinction as there is in some languages. 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. | |
11.13. | Do I need to include any additional information in my translations? |
Yes. The header of the English version of each document will look something like this: <!-- The FreeBSD Documentation Project $FreeBSD: head/en_US.ISO8859-1/books/faq/book.xml 38674 2012-04-14 13:52:52Z $ --> The exact boilerplate may change, but it will always
include a $FreeBSD$ line and the phrase
Your translated documents should include their own
$FreeBSD$ line, and change the
In addition, you should add a third line which indicates which revision of the English text this is based on. So, the Spanish version of this file might start: <!-- The FreeBSD Spanish Documentation Project $FreeBSD: head/es_ES.ISO8859-1/books/faq/book.xml 38826 2012-05-17 19:12:14Z hrs $ Original revision: r38674 --> |
All FreeBSD documents are available for download at https://download.freebsd.org/ftp/doc/
Questions that are not answered by the
documentation may be
sent to <freebsd-questions@FreeBSD.org>.
Send questions about this document to <freebsd-doc@FreeBSD.org>.