Hello I want to translate book to polish language.
Can any one from development team or responsible for book give me some feedback?
At first hand in connection with copyright in book and polish law i have to have written permission to do such thing. Second hand document template will be very helpful.
Welcome community opinion.
Hi Piotr. Translations - even partial ones - would be great!
The book is licensed with Apache 2.0 license and thus your are free to translate it, distribute copies without any extra license or agreements. For details, see
http://vaadin.com/license
.
All build scripts, stylesheets and supporting material to book can be found in our SVN at
http://dev.vaadin.com/svn/doc/trunk/
.
When you have gotten started, we would be happy to provide committer access to incubator for the polish translation of the book.
Is there any kind of template for the written permission you could send us if you need that according to Polish law or what should the document contain? Preferrably in english but I have a polish friend who could check the document for us if its only in polish.
Very nice of you!
Oh and our main writer is Magi (magi at vaadin dot com) so if you want templates and things like that you should talk to him about tips and tricks. I’ll point him this way to drop by too!
Wow, a Polish translation would be excellent! I guess there’s quite a bit work involved… Unfortunately, my Polish is a bit…rusty…so my help is limited to technical issues.
There are a couple of issues.
- As noted, the book is licensed under Apache 2 License, so copying and modifying, and translating, is ok.
However, as Apache 2 License section 6 states, the license does
not
grant the use of trademarks and such (Vaadin name, logos, etc), so a written permission may be required regarding that. The rules regarding the use of the Vaadin trademarks are stated at the license page (
http://vaadin.com/license
), on the right side of the page.
However
, if the translation is done under the Vaadin project and submitted as a “Contribution” (see the definition in the Apache 2 License in section 1) to the Vaadin SVN, the issue goes away, as the contributions are incorporated into the product (see the license). The trademark is an issue only if the translated book is published by some other party than IT Mill. For example, if you do not want to submit the translation as a contribution to Vaadin project, but want to print and distribute the book just yourself.
Also, asking for a written permission may be relevant – the local laws in Poland (or Finland for that matter) might not allow as much freedom as the Apache 2 license does, which is written in U.S., where the copyright and contract laws allow more freedom in giving rights in a license.
- The Vaadin fonts are commercial and not included in the repository. If you want to make custom copies of the book by yourself, you may need to buy the fonts.
- I strongly recommend that if there are to be translations of Book of Vaadin, it should first be internationalized so that it is easy in future to translate
only
the changed strings (paragraphs, titles, etc) and merge them to existing translations. Many Open Source products use such i18n tools for translating documentation and at least some are based on DocBook, which we use. I’ll have to look into this. In any case, it should be somewhat easy to extract translatable strings from a DocBook file and convert them to some format accepted by some localization tool. I recommend using Gnu Gettext format, which is the most common and supported by many tools.
Maybe something else as well.
The English version is, I must admit, infested with typs and erros grammar, so it would be great to get feedback regarding those when you are doing the translation.
I assume that as long as I am contributor and my job is distributed by IT MILL I do not need special permissions. It is honest. Thanks.
As soon as I am going to have first two chapters I’ll ask for incubator.
I made the POT files for Book of Vaadin using the xml2po program in the poxml package. I put them in the repo, see
http://dev.vaadin.com/browser/doc/trunk/manual/translations/pot
. There are plenty of free tools for editing PO files (I use KBabel on Linux).
I haven’t looked at the POT files very closely to see if there are any difficult issues with some strings. There could be.
What OS are you using? The poxml package is available for Linux, but there might be equivalent tools for other OSes as well.
There’s an example PO file for a partial Finnish translation of the Preface in
http://dev.vaadin.com/browser/doc/trunk/manual/translations/fi_FI/book.po
. I don’t quite yet have the script to build the translated book using the “po2xml” program, but it should be somewhat easy, working on it. There could be some problems in Docbook configuration, hard to say yet. At least the hyphenation settings have to be done. There may be one or two strings in English in the configuration files, I’ll have to deal with those.
Are you familiar with Gettext (PO files) or translation/localization tools in general?
I am not familliar with any localization/translation tool.
What I have is very good polish and good reading english.
I work on Ubuntu 9.04 (Gnome).
Can I translate xml files directly?
Ok I see what’s going on with this pot files. I do not have to use any tool and edit this files by hand. Correct?
PO-files are interesting approach to translation a book. It might add some extra work and definitely forces the translation to be identical in structure to the original. Still - I can definitely see the benefits - this way the translation will be kept completely in sync even when there are changes to the original book - furthermore it makes it easy to release intermediate versions where only parts of the book are translated.
Marko - is xml2po able “sync” po files when source xml changes? I mean - can it correctly add missing new phrases to po-files in the correct location without deleting existing translations?
In the man page of xml2po is some thing like this:
Just perfect. Just “sudo apt-get install kbabel” and you’re there. Also install the poxml package, it’s in Ubuntu. You’ll need it to test the translations; the “po2xml” program takes the original English XML file and a PO file that includes both the English and translated strings, and produces a corresponding translated XML file. See “man po2xml”.
I really recommend the KBabel. Poedit (“apt-get install poedit”) is an alternative, but I haven’t used it and can’t say much about it. KBabel is a KDE program but runs just as well under Gnome. You should probably not start it with “kbabel”, but run “catalogmanager”, which allows opening a project that contains multiple PO files, as Book of Vaadin does.
In Catalog Manager, go to Project->New. Give conf file name “book-of-vaadin.kbabel” or something, Polish as the language, and “other” as the project type. Set the base folder for the PO files a folder that contains the translated files. This should be “manual/translations/pl_PL” under the documentation source tree (“svn co http://dev.vaadin.com/svn/doc/trunk”). Give the “manual/translations/pot” under the doc source tree as the root folder for POT files. Click Finish. The Catalog Manger should now scan both the PO and POT folders and list the translations. There are no existing translations for Polish so it’s all untranslated files.
Below is a project for the Finnish translations (there’s only the book.po):
When you click a file, it automatically copies the POT file to a PO file (in the pl_PL folder), which will contain the translations, and opens the actual KBabel editor.
You probably want XML validation and such for the BoV files, so go through the settings and enable the XML validator, if it’s not already enabled (it should be).
Oh, and please set the translator identity in the project settings to get your credits correctly so that’s it’s at least included in the PO files (see the header section of
http://dev.vaadin.com/browser/doc/trunk/manual/translations/fi_FI/book.po
for example). We’ll have to put some sort of translator field in the generation scripts to have translator names included in the book properly.
(POT files are template files for translating, do not edit them. A POT file is in the beginning copied to PO file, which is translated and then contains both English and translated strings. As the documentation is updated and new POT files generated, it’s possible to merge (with msgmerge) the new texts to the POT files, thus reusing the old translations. Strings that do not match exactly but have a close match are marked as “fuzzy” and need to be checked. This happens, for example, if one word changes in a paragraph.)
Just ask me if you have any questions.
No, it apparently gives an error and exits. So the PO files have to be in sync with the source XML files when you generate the translated XML files. The translator will have to merge the updated source to the existing translations every time he does “svn update”. That will usually invalidate some translations (make them fuzzy), and they have to be corrected, but that’s how it goes. I’ll have to make some scripts (add to the book Makefile) for doing POT file generation and merging easily.
An alternative would be to keep a copy of the book XML files from which the POT files were generated, and update those less often, that is, not every time I commit changes to the book. This might stabilize the translation process greatly. Well, we can either do this in the project’s SVN repository OR the translation can do it himself. Or he can just not do “svn update” so often.
Hmm, maybe I should document the merge-translate-compile process a bit once I get the (probably quite easy) scripts working.
Thanks Marco for help with kbabel. I had to pull some older packages from debian repos because Ubuntu came on KDE 4 and Localize. Right now I’m ending book.po and before night I should have first draft of it.
Oh, KDE 4 has got a new translation tool? So it seems. I suppose it’s ok as well, probably quite similar to KBabel. It seems to have the Catalog Manager integrated in the translation program, so it might be nicer to use (I’ve noticed that KBabel has some problems with the two programs, such as in managing project preferences). Use whatever you like.
I made some changes to book.xml; the po2xml program did not like the ISO-8859-1 encoded book.xml and part1-vaadin.xml, so I changed the encodings for those files.
I also made a proof-of-concept Makefile (
http://dev.vaadin.com/browser/doc/trunk/manual/translations/fi_FI/Makefile
) for building a PDF book from the Finnish translations (manual/translations/fi_FI) and it seems to work just fine. You could just copy it to your pl_PL directory and it should work with “make compile”. “make merge” runs the msgmerge.
The higher-level Makefile in the “manual” directory has an “i18n” target that rebuilds the POTs.
So we have now a translation toolchain for Book of Vaadin up and running? That was fast.
Essentially yes, though building the localized HTML and PDF manuals needs to be integrated properly in the documentation build process. Looking into it.
One issue is with untranslated chapters. I first thought that they would just be left out so that a partially translated book would have just the translated chapters. It would be ok to have for example just the chapters 1 and 2 in a translation. However, that would lead to broken references from the translated chapters to untranslated ones, and there are a lot of references in chapters 1 and 2. To avoid the problem, the untranslated chapters would have to be in English.
Ok. IMO we should hold our horses with the build process until the first chapter translations are ready.
About translation I am working on but I have sudden project also. Beginning from Monday, I will have more time. Right now I have first draft of book.pot. There are some untranslated tags like Book of Vaadin and similar so it maybe good material for tests. I can send this only tell me to who and where.
I’ll create an incubator directory for you. Will contact by email for access details.
Book.po in repo. There is a lot of language bugs so don’t show it more public. Use it only for tests. 
Thanks!