Date: Mon, 28 Jun 1999 20:02:18 +0100 From: Nik Clayton <nik@nothing-going-on.demon.co.uk> To: Joao Carlos Mendes Luis <jonny@jonny.eng.br> Cc: doc@freebsd.org Subject: Re: Starting new translation, hints ? Message-ID: <19990628200217.A696@catkin.nothing-going-on.org> In-Reply-To: <199906271822.PAA04076@roma.coe.ufrj.br>; from Joao Carlos Mendes Luis on Sun, Jun 27, 1999 at 03:22:56PM -0300 References: <199906271822.PAA04076@roma.coe.ufrj.br>
next in thread | previous in thread | raw e-mail | index | archive | help
On Sun, Jun 27, 1999 at 03:22:56PM -0300, Joao Carlos Mendes Luis wrote: > A group in Brazil is working toward a portuguese (brazilian) version > of FreeBSD documents. We are now in the process of FAQ text revision, > as it could be seen at http://www.br.freebsd.org/faq/FAQ.html, for > those who understand portuguese. The next step will be the handbook. > > I'd like to know if there are any known hints on keeping this > translation up to date, following CVS closely, and how to integrate > this to the main FreeBSD sources. These would direct the efforts from > now on. Here's a preliminary FAQ for translators. Let me know if it answers your questions. N FreeBSD Documentation Project Translator's FAQ Preface This is the FAQ for people translating the FreeBSD documentation (FAQ, Handbook, tutorials, man 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 Grnder <elwood@mc5sys.in-berlin.de> and translated back to English by Bernd Warken <bwarken@mayn.de>. In the near future this will be converted to DocBook so that other versions (HTML, Postscript, plain text) can be produced with relative ease. The FAQ maintainer is Nik Clayton <nik@freebsd.org> ------------------------------------------------------------------------ Why a FAQ? 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. ------------------------------------------------------------------------ What does "i18n" and "l10n" mean? "i18n" means "internationalisation" and "l10n" means "localisation". 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". ------------------------------------------------------------------------ Is there a mailing list for translators? Yes, freebsd-translate@ngo.org.uk. Subscribe by sending a message to freebsd-translate-request@ngo.org.uk with the word "subscribe" in the body of the message. You will receive a reply asking you to confirm your subscription (in exactly the same manner as the the FreeBSD lists at freebsd.org). The primary language of the mailing list is English. However, posts in other languages will be accepted. The mailing list is not moderated, but you need to be a member of the list before you can post to it. The mailing list is archived, but they are not currently searchable. Sending the message "help" to majordomo@ngo.org.uk will send back instructions on how to access the archive. It is expected that the mailing list will transfer to freebsd.org and therefore become 'official' in the near future. ------------------------------------------------------------------------ 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. ------------------------------------------------------------------------ What languages do I need to know? Ideally, you will need 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. ------------------------------------------------------------------------ What software do I need to know? It is strongly recommended that you maintain a local copy of the FreeBSD CVS repository (at least the documentation part) either using CTM or CVSup. The "Staying current with FreeBSD" chapter in the Handbook explains how to use these applications. You should be comfortable using CVS. This will allow you to see what has changed between different versions of the files that make up the documentation. [XXX To Do -- write a tutorial that shows how to use CVSup to get just the documentation, check it out, and see what's changed between two arbitrary revisions] ------------------------------------------------------------------------ How do I find out who else might be translating to the same language? The Documentation Project translations page at http://www.freebsd.org/docproj/translations.html lists the translation efforts that are currently known about. If someone else is already working on translating documentation to your language, please don't 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 freebsd-doc@freebsd.org in case someone else is thinking of doing a translation, but hasn't announced it yet. ------------------------------------------------------------------------ No one else is translating to my language. What do I do? Congratulations, you have just started the "FreeBSD <insert your language> Translation Project". Welcome aboard. First, decide whether or not you've 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 publicise your work and coordinate any volunteers that might want to help you. Write an e-mail to the Documentation Project mailing list, announcing that you are going to translate the documentation, so the Documentation Project translations page can be maintained. You should subscribe to the freebsd-translate@ngo.org.uk mailing list (as described earlier). If there is already someone in your country providing FreeBSD mirroring services you should contact them and ask if they can provide some webspace for your project, and possibly an e-mail 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. ------------------------------------------------------------------------ I've 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). ------------------------------------------------------------------------ I'm the only person working on translating to this language, how do I submit my translation, or, we're a translation team, and want to submit documentation that our members have translated for us? First, make sure your translation is organised properly. This means that it should drop in to the existing documentation tree and build straight away. Currently, the FreeBSD documentation is stored in a top level directory called "doc". 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. Finally, you should have directories for each document. For example, a hypothetical Swedish translation might look like doc/ sv/ Makefile FAQ/ Makefile *.sgml "sv" is the ISO639 code for "Swedish". Note the two Makefiles, which will be used to build the documentation. There is no separate language code for Swedish, so there is no intermittent directory between the "sv" and "FAQ" directories. Note: You will notice that the English FAQ and Handbook are currently in the top level directory (i.e., doc/FAQ and doc/Handbook). This is being changed, and they will move to doc/en/FAQ and doc/en/Handbook respectively. Use tar(1) and gzip(1) to compress up your documentation, and send it to the project. % cd doc % tar cf swedish-docs.tar sv % gzip -9 swedish-docs.tar Upload swedish-docs.tar.gz to ftp.freebsd.org/incoming/. Then use 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. Someone (probably the Documentation Project Manager, currently Nik Clayton) 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" 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 try and work them out. If there are no problems then your translation will be committed as soon as possible. Note from Nik: I'm extraordinarily lazy. So, if your submission works first time then expect to be offered commit privileges to the FreeBSD tree very quickly. I much prefer it if you can commit your own documentation once it is obvious that you know what you are doing :-). This gives me more free time, and means that your changes are visible to everyone else much faster. ------------------------------------------------------------------------ Can I include language or country specific text in my translation? I would prefer that you didn't. 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's no real reason why that information should not be in the English (or German, or Spanish, or Japanese...) versions as well. It is feasible that an English speaker in Korea might try and 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 send-pr(1)) and then translate the change back to your language in the translated Handbook. Thanks. ------------------------------------------------------------------------ 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 é Small "e" with an acute accent É Large "E" with an acute accent ü Small "u" with an umlaut After you have installed the iso8879 port, the files in /usr/local/share/sgml/iso8879 contain the complete list. ------------------------------------------------------------------------ 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. ------------------------------------------------------------------------ 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; <!-- $Id: chapter.sgml,v 1.24 1998/09/11 17:22:49 jkh Exp $ --> <!-- The FreeBSD Documentation Project --> The exact boilerplate may change, but it will always include an Id line and the phrase "The FreeBSD Documentation Project. Your translated documents should include their own Id 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. So, the Spanish version of this file might start <!-- $Id: chapter.sgml,v 1/4 1998/09/12 18:03:22 jesusr Exp $ --> <!-- The FreeBSD Spanish Documentation Project --> <!-- Original revision: 1.24 --> -- [intentional self-reference] can be easily accommodated using a blessed, non-self-referential dummy head-node whose own object destructor severs the links. -- Tom Christiansen in <375143b5@cs.colorado.edu> To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?19990628200217.A696>