Thread: Doc translation
Hi, some PostgreSQL users in Japan have been translating 7.1 docs into Japanese. I hope the work would finish within 1-2 months. My question is how the translated docs could be merged into the doc source tree once it is done. Maybe doc/ja/src/sgml? -- Tatsuo Ishii
Tatsuo Ishii <t-ishii@sra.co.jp> writes:
> Hi, some PostgreSQL users in Japan have been translating 7.1 docs into
> Japanese. I hope the work would finish within 1-2 months. My question
> is how the translated docs could be merged into the doc source tree
> once it is done. Maybe doc/ja/src/sgml?
Hmm, *should* they be merged into the source tree, or distributed as
a separate tarball? I'm concerned that they'd always be out of sync
with the English docs :-(
regards, tom lane
> Tatsuo Ishii <t-ishii@sra.co.jp> writes: > > Hi, some PostgreSQL users in Japan have been translating 7.1 docs into > > Japanese. I hope the work would finish within 1-2 months. My question > > is how the translated docs could be merged into the doc source tree > > once it is done. Maybe doc/ja/src/sgml? > > Hmm, *should* they be merged into the source tree, or distributed as > a separate tarball? I'm concerned that they'd always be out of sync > with the English docs :-( Right. However, it would be greater for Japanese users to have the Japanese docs in the *official* distribution of PostgreSQL, than getting them from other places. What about setting up a new CVS module for the Japanese docs, isolated from the source and English doc module(pgsql)? -- Tatsuo Ishii
----- Original Message ----- From: Tatsuo Ishii <t-ishii@sra.co.jp> Sent: Sunday, June 17, 2001 11:06 PM > > Tatsuo Ishii <t-ishii@sra.co.jp> writes: > > > Hi, some PostgreSQL users in Japan have been translating 7.1 docs into > > > Japanese. I hope the work would finish within 1-2 months. My question > > > is how the translated docs could be merged into the doc source tree > > > once it is done. Maybe doc/ja/src/sgml? > > > > Hmm, *should* they be merged into the source tree, or distributed as > > a separate tarball? I'm concerned that they'd always be out of sync > > with the English docs :-( > > Right. However, it would be greater for Japanese users to have the > Japanese docs in the *official* distribution of PostgreSQL, than > getting them from other places. What about setting up a new CVS module > for the Japanese docs, isolated from the source and English doc > module(pgsql)? What about the possibility of having docs translated into another languages? Would you then include all those translations into the *official* PostgresSQL distribution? There're many languages out there, and maybe eventually the PG docs will get translated to these (some of these) languages. Wouldn't it be too much of the documentation per distribution? I guess that the setting up a separate CVS module per language might be a good idea. People just grab the distribution and docs in desired language, and plug the docs in, and here you go. And the docs are almost always "out-of-sync" with the distribution anyway :), even the English ones... Serguei
> distribution? I guess that the setting up a separate CVS module > per language might be a good idea. People just grab the distribution and docs in > desired language, and plug the docs in, and here you go. And the docs are almost always > "out-of-sync" with the distribution anyway :), even the English ones... Sounds good to me too. For example, For 7.1 Japanese docs, people could grab "postgresql-7.1-doc-ja.tar.gz" or whatever... -- Tatsuo Ishii
Tatsuo Ishii wrote: > Hi, some PostgreSQL users in Japan have been translating 7.1 docs into > Japanese. I hope the work would finish within 1-2 months. My question > is how the translated docs could be merged into the doc source tree > once it is done. Maybe doc/ja/src/sgml? > -- > Tatsuo Ishii > > ---------------------------(end of broadcast)--------------------------- > TIP 5: Have you checked our extensive FAQ? > > http://www.postgresql.org/users-lounge/docs/faq.html I think it's better to setup another cvs module, thus maintain all other languages' docs except English( the English one act as standard one), and may be we could also maintian a auto-generated html (or other format if there are no other problems) version on web site like techdoc.postgresql.org or some other places for users to browse. (I think most of people would first go to the main site to search methods to resolve their problem.) regards laser
----- Original Message ----- From: Tatsuo Ishii <t-ishii@sra.co.jp> Sent: Monday, June 18, 2001 1:26 AM > > distribution? I guess that the setting up a separate CVS module > > per language might be a good idea. People just grab the distribution and docs in > > desired language, and plug the docs in, and here you go. And the docs are almost always > > "out-of-sync" with the distribution anyway :), even the English ones... > > Sounds good to me too. > > For example, For 7.1 Japanese docs, people could grab > "postgresql-7.1-doc-ja.tar.gz" or whatever... ... and also one can put translations not only for the docs in that language CVS module/tarball, but also for all PG messaging, especially when now PG goes international (see Peter Eisentraut's post and the follow up thread of June 4 entitled "FYI: status of native language support"). Serguei
Tatsuo ... setting up a seperate CVS module for this does sound like a great idea ... you already have access to the CVS repository, right? Can you send me a tar file containing what you have so far, and I'll get it into CVS and then you'll be able to update that at will? If we set it up as: pgsql-docs/ja we could move the english docs out of pgsql itself and into this module too, as: pgsql-docs/en and any other language too ... On Mon, 18 Jun 2001, Tatsuo Ishii wrote: > > Tatsuo Ishii <t-ishii@sra.co.jp> writes: > > > Hi, some PostgreSQL users in Japan have been translating 7.1 docs into > > > Japanese. I hope the work would finish within 1-2 months. My question > > > is how the translated docs could be merged into the doc source tree > > > once it is done. Maybe doc/ja/src/sgml? > > > > Hmm, *should* they be merged into the source tree, or distributed as > > a separate tarball? I'm concerned that they'd always be out of sync > > with the English docs :-( > > Right. However, it would be greater for Japanese users to have the > Japanese docs in the *official* distribution of PostgreSQL, than > getting them from other places. What about setting up a new CVS module > for the Japanese docs, isolated from the source and English doc > module(pgsql)? > -- > Tatsuo Ishii > > ---------------------------(end of broadcast)--------------------------- > TIP 6: Have you searched our list archives? > > http://www.postgresql.org/search.mpl > Marc G. Fournier ICQ#7615664 IRC Nick: Scrappy Systems Administrator @ hub.org primary: scrappy@hub.org secondary: scrappy@{freebsd|postgresql}.org
The Hermit Hacker <scrappy@hub.org> writes:
> we could move the english docs out of pgsql itself and into this module
> too, as:
> pgsql-docs/en
Hmm, I'm not sure that that's a good idea; seems it would lose the
coupling between versions of the source and versions of the
documentation.
I quite agree that we should have an official distribution of
non-English documentation if possible. I'm just wondering how best to
keep track of which set of docs goes with which Postgres release.
Since the English docs are (we hope) kept up to date with the sources,
it seems best to keep those as part of the master CVS tree.
We could imagine keeping non-English docs in the same tree, but that
would require lots of attention to branch management --- for example,
we'd have to be careful to commit these Japanese translations of 7.1
docs into the REL7_1_STABLE branch. OTOH maybe that's just as true
if there's a separate CVS tree for docs; you'd still want to deal with
a new version per source release. So maybe a single tree is the right
answer after all.
Anyone have experience with managing this sort of situation under CVS?
Is separate tree or combined tree better?
regards, tom lane
Tatsuo Ishii writes: > Hi, some PostgreSQL users in Japan have been translating 7.1 docs into > Japanese. I hope the work would finish within 1-2 months. My question > is how the translated docs could be merged into the doc source tree > once it is done. Maybe doc/ja/src/sgml? A while ago I sent a proposal to -docs about how to handle this (basically doc/src/sgml-<lang>). No one protested so I was going to implement it; in fact, I already have in some private branch I have lying around here. It even includes some nice side-effects, such as fallback to English for incomplete translations (so you can look at the result while translation is still going on) and the integration of the translated SQL reference pages with the internationalized psql that is currently taking shape. (Someone else is working on a French translation and has been very anxious for this to happen, too.) I would not be in favour of a separate CVS module, for several reasons: First, it will marginalize the efforts. I bet there are a sufficient number of people how would be willing to track documentation upgrades and keep their language up-to-date. Second, the build machinery would get gratuitously complicated and spread around (makefiles, stylesheets, graphics, URL strings, etc.). Third, the (undoubtedly real) problem of keeping these translations up to date would not be helped by this at all. The maintainers of these translations will simply have to be honest to not label their documentation set as corresponding to version X.Y when the content is still based on the original documentation for X.(Y-2). About "I don't want to download all this stuff I can't read": We already have chunked distribution tarballs. It would be possible to "chunk out" the files pertaining to a particular language (which would include the message catalogs as well). While other open source projects sometimes keep their entire documentation in a separate cvs module, they generally keep all languages together for the reasons given above. -- Peter Eisentraut peter_e@gmx.net http://funkturm.homeip.net/~peter
On Mon, 18 Jun 2001, Peter Eisentraut wrote: > Tatsuo Ishii writes: > > > Hi, some PostgreSQL users in Japan have been translating 7.1 docs into > > Japanese. I hope the work would finish within 1-2 months. My question > > is how the translated docs could be merged into the doc source tree > > once it is done. Maybe doc/ja/src/sgml? > > A while ago I sent a proposal to -docs about how to handle this (basically > doc/src/sgml-<lang>). No one protested so I was going to implement it; in > fact, I already have in some private branch I have lying around here. It > even includes some nice side-effects, such as fallback to English for > incomplete translations (so you can look at the result while translation > is still going on) and the integration of the translated SQL reference > pages with the internationalized psql that is currently taking shape. > (Someone else is working on a French translation and has been very anxious > for this to happen, too.) > > I would not be in favour of a separate CVS module, for several reasons: > First, it will marginalize the efforts. I bet there are a sufficient > number of people how would be willing to track documentation upgrades and > keep their language up-to-date. Second, the build machinery would get > gratuitously complicated and spread around (makefiles, stylesheets, > graphics, URL strings, etc.). Third, the (undoubtedly real) problem of > keeping these translations up to date would not be helped by this at all. > The maintainers of these translations will simply have to be honest to not > label their documentation set as corresponding to version X.Y when the > content is still based on the original documentation for X.(Y-2). > > About "I don't want to download all this stuff I can't read": We already > have chunked distribution tarballs. It would be possible to "chunk out" > the files pertaining to a particular language (which would include the > message catalogs as well). > > While other open source projects sometimes keep their entire documentation > in a separate cvs module, they generally keep all languages together for > the reasons given above. I definitely have no problems with this ... one comment about Tom's "how to keep releases together" point though ... that is what Tags/Branches are for ... as long as we tag all modules, things shouldn't "fall out of sync" ... But, if you already have a clean method of doign this, please, by all means, continue ...
Peter Eisentraut <peter_e@gmx.net> writes:
> About "I don't want to download all this stuff I can't read": We already
> have chunked distribution tarballs. It would be possible to "chunk out"
> the files pertaining to a particular language
That works for picking up tarballs, but (AFAIK) not for people who
update from the CVS server. However, seeing that doc/src/sgml is
presently only about a tenth of the total CVS tree bulk, it'll probably
be a long while before the docs form an overwhelming load on CVS users.
Your other arguments seem good to me, so I agree with keeping the
translated documents in the main tree, at least for now.
regards, tom lane
> > we could move the english docs out of pgsql itself and into this module
> > too, as:
> > pgsql-docs/en
> Hmm, I'm not sure that that's a good idea; seems it would lose the
> coupling between versions of the source and versions of the
> documentation.
We could (and should, imho) leave the English docs where they are, but
they could be included as a module in the pgsql-docs repository.
> Anyone have experience with managing this sort of situation under CVS?
Yes.
> Is separate tree or combined tree better?
I would suggest defining a "pgsql-docs" module, which might contain the
actual code for non-English docs. We can define a logical module
"pgsql-en" which is included in the *logical* pgsql-docs module (the
latter also contains the *physical* pgsql-docs module).
We've done this on other projects. I can help set up the module
definitions (which are fairly simple when worked out, but perhaps not
trivial to derive from first principles. I'll steal the solution from
work I've done earlier ;)
- Thomas