On Thu, 2005-05-12 at 16:49 +0200, Francois Gouget wrote:
This patch adds the framework for translating Wine's documentation and adds a translation of the FAQ to French as a demonstration.
No compressed patches, please.
Also, the patch is big, and some things are cleaner than others. Let's break it down a bit.
Here is what the framework does:
- first it moves most of en/Makefile.in to Make.rules.in so that this
code can be shared across the various translations.
Well, the reason I didn't do that is for cases like incomplete translations.
We can move to Make.rules.in: -- DB2* defines -- the targets (docs, pdf, etc) -- the tar rules
The rest we can keep local, see how things evolve. We can always refactor it up.
- the actual translation is stored in a po file, one per documentation
document. So for French we currently have fr/wine-faq.po and later we will also have wineusr-guide.po and winelib-guide.po.
I'm not too hot about it to be honest. SGML is hard on the eye, this .po stuff seems to be even worse. But maybe it's easier to work with due to the various tools. If it makes it easier for you to maintain the translation, I'm cool with it. However, I'm not sure this will be the preferred way for all translators out there, so we shouldn't force it on everybody.
- Using po files lets us track exactly which translation paragraphs
are up to date and which are not. It also lets us leverage the tools that have been developed around that format such as KBabel and maybe even make it possible for contributors to translate the documentation online using tools like Pootle (http://pootle.wordforge.org/), Kartouche (http://i18n.kde.org/tools/kartouche/) or Rosetta (https://launchpad.ubuntu.com/rosetta).
This is great, but I doubt such tools can tell you *what* changed when something did change (the *what* here is "how did paragraph change")
- The link between the SGML files and the PO files and back is handled
by PO4A (http://po4a.alioth.debian.org/).
I'm a bit worried about this one. It's new, debian specific, etc. There's no .rpm for it, and that makes me nervous. Tools like this must be easily available.
Even if we go for it, maybe we'll have to keep the generated .sgml in CVS (just like configure).
- So configure.ac checks for the po4a tools. If they are missing then
the translated documentation cannot be built. I also added a Makepo.rules.in that should be used by Makefiles building translated documentation. What it does is just include the main Make.rules.in file and add a couple of rules for generating SGML using PO files, and extending the 'clean' target. This last bit cannot be put in the top-level Make.rules.in because it does '$(RM) $(ALLBOOKS:%=%.sgml)' which would be unfortunate in the en directory.
The $(RM)... can remain local, and the rules can go in Make.rules.in. It would be confusing to have too many rule files.
sed -e 's/^<\(article .*\) lang="en">$/<\1 lang="fr">/' -e 's/^<\(book .*\) lang="en">$/<\1 lang="fr">/' wine-faq.posgml >wine-faq.sgml || (rm -f wine-faq.sgml && false)
Nasty. BTW, the 'lang="en"' part of the patch can go in separately too.
On Fri, 13 May 2005, Dimi Paun wrote:
On Thu, 2005-05-12 at 16:49 +0200, Francois Gouget wrote:
This patch adds the framework for translating Wine's documentation and adds a translation of the FAQ to French as a demonstration.
No compressed patches, please.
I know, I only compressed it because of the size.
Also, the patch is big, and some things are cleaner than others. Let's break it down a bit.
Ok.
Here is what the framework does:
- first it moves most of en/Makefile.in to Make.rules.in so that this
code can be shared across the various translations.
Well, the reason I didn't do that is for cases like incomplete translations.
We can move to Make.rules.in: -- DB2* defines -- the targets (docs, pdf, etc) -- the tar rules
Ok, I'll start with just the above.
I had moved the WINE*_SRCS variables to Make.rules.in because they are needed to have proper dependencies in the po translations. Raw SGML translation can use it even if they only translate one book. The only case where it could be a problem for raw SGML translations is if it translates only part of a book, i.e. if it translates wineusr-configuring.sgml but not wineusr-fonts.sgml. I'm not sure how likely or desirable that is. Maybe we could generate empty/placeholder files to deal with this case.
The alternative is to duplicate the SGML source file list into each po Makefile or in Makepo.rules.in.
[...]
- the actual translation is stored in a po file, one per documentation
document. So for French we currently have fr/wine-faq.po and later we will also have wineusr-guide.po and winelib-guide.po.
I'm not too hot about it to be honest. SGML is hard on the eye, this .po stuff seems to be even worse. But maybe it's easier to work with due to the various tools. If it makes it easier for you to maintain the translation, I'm cool with it.
It is *very much* easier. Just one example. At CodeWeavers we have a German translation of the CrossOver documentation. Initially it was in SGML. But I don't speak German so I had no idea what was up-to-date and what was not, which means it was impossible to say whether it was 90% obsolete (not shippable) or >90% up-to-date. Using the system of CVS version tracking you proposed could give an indication on a per-file basis but that's pretty coarse (wineusr: 10 files, 9% resolution, it's worse for wine-faq). With po files I know which paragraphs are up-to-date and which are not (1373 paragraphs, 0.07% resolution).
However, I'm not sure this will be the preferred way for all translators out there, so we shouldn't force it on everybody.
With the framework as I made it, non-po translations can use Make.rules.in and then things work exactly the same as for the English documentation.
- Using po files lets us track exactly which translation paragraphs
are up to date and which are not. It also lets us leverage the tools that have been developed around that format such as KBabel and maybe even make it possible for contributors to translate the documentation online using tools like Pootle (http://pootle.wordforge.org/), Kartouche (http://i18n.kde.org/tools/kartouche/) or Rosetta (https://launchpad.ubuntu.com/rosetta).
This is great, but I doubt such tools can tell you *what* changed when something did change (the *what* here is "how did paragraph change")
It doesn't but then even a basic diff won't tell you that. A basic diff will also get confused and tell you most of the file changed if lines got rewrapped. PO files don't care.
- The link between the SGML files and the PO files and back is handled
by PO4A (http://po4a.alioth.debian.org/).
I'm a bit worried about this one. It's new, debian specific, etc. There's no .rpm for it, and that makes me nervous. Tools like this must be easily available.
The project is reasonably active. And it's just perl so installation is pretty trivial. We could even stick it in a po4a/ directory in CVS and use it from there.
Even if we go for it, maybe we'll have to keep the generated .sgml in CVS (just like configure).
That's a possibility.
- So configure.ac checks for the po4a tools. If they are missing then
the translated documentation cannot be built. I also added a Makepo.rules.in that should be used by Makefiles building translated documentation. What it does is just include the main Make.rules.in file and add a couple of rules for generating SGML using PO files, and extending the 'clean' target. This last bit cannot be put in the top-level Make.rules.in because it does '$(RM) $(ALLBOOKS:%=%.sgml)' which would be unfortunate in the en directory.
The $(RM)... can remain local, and the rules can go in Make.rules.in. It would be confusing to have too many rule files.
Ok.
sed -e 's/^<\(article .*\) lang="en">$/<\1 lang="fr">/' -e 's/^<\(book .*\) lang="en">$/<\1 lang="fr">/' wine-faq.posgml >wine-faq.sgml || (rm -f wine-faq.sgml && false)Nasty. BTW, the 'lang="en"' part of the patch can go in separately too.
Ok, will submit it separately.
On Fri, 2005-05-13 at 11:47 +0200, Francois Gouget wrote:
No compressed patches, please.
I know, I only compressed it because of the size.
Yeah, but that meant I couldn't read it most of the day, as I couldn't decompress it. Plus it's a pain. Patches shouldn't be too big to begin with, and in a (very few) cases when they are, I don't think it's a problem if they go to the list uncompressed.
The alternative is to duplicate the SGML source file list into each po Makefile or in Makepo.rules.in.
Let's keep them in the Makefiles for now, they are easy enough to move up later on.
It doesn't but then even a basic diff won't tell you that. A basic diff will also get confused and tell you most of the file changed if lines got rewrapped. PO files don't care.
Right. It's a great aid, I agree. What I mean however is that they can not tell you what changed in the *original* when things do change. When you translate something, and you see that paragraphs X,Y,Z changed, would be great if it also tells you how they changed.
The project is reasonably active. And it's just perl so installation is pretty trivial. We could even stick it in a po4a/ directory in CVS and use it from there.
Yeah, I think that's the way to go. We shouldn't make it a pain for people to contribute.
On Fri, 13 May 2005, Dimi Paun wrote: [...]
The project is reasonably active. And it's just perl so installation is pretty trivial. We could even stick it in a po4a/ directory in CVS and use it from there.
Yeah, I think that's the way to go. We shouldn't make it a pain for people to contribute.
The best way to do that would be to do a vendor import. The way to do that would be as follows:
wget http://alioth.debian.org/download.php/1031/po4a-0.21.tar.gz tar xfz po4a-0.21.tar.gz cd po4a-0.21 cvs -d ... import -ko -m "Import of PO4A release 0.21" docs/po4a PO4A po4a-0_21
But it's probably best to wait for the initial bits of the French to be checked in. Here how I propose to proceed: 1) we get the first bits of the French translation checked in 2) then you would import Po4a 3) and I adapt the makefiles to look for it in po4a/ instead of trying to detect it in configure.ac
Alternately we can swap 1 and 2 and then 3 would go away.
The best way to do that would be to do a vendor import. The way to do that would be as follows:
True. There's no point to first add the Fr translation and then po4a if the FR requires it. We need to decide if we are going to use it or not. I have no experience with it, any other opinions out there?
On Fri, 2005-05-13 at 16:18 +0200, Francois Gouget wrote:
- we get the first bits of the French translation checked in
- then you would import Po4a
- and I adapt the makefiles to look for it in po4a/ instead of
trying to detect it in configure.ac
Alternately we can swap 1 and 2 and then 3 would go away.
Let's give po4a a shot. 2 is done, so we can carry on with 3 and 1.
-
Dimi Paun -
Dimitrie Paun
-
Francois Gouget