On Mar 22, 2007, at 8:35 PM, Max Carlson wrote:
Sounds good - so for now, folks can tag translations with lang="jp"
and we can sort out the doc tools later - at least for the dev guide.
Right, just use that attribute (just like we already use @condition
to tag things like solo/proxied or dhtml/flash) and we're future-proof.
For the refquide, perhaps we can add a lang tag to the source-level
comments? That way, all translations are inline next to their
sources.
We could. I worry about the impact that would have on readability of
the sources -- the volume of comments, specifically. I also wonder
whether that would really fit common localization workflows; if you
were writing or updating localized documentation, wouldn't you rather
do it in a batch in one or a few files, rather than opening and
changing a large number of files?
Thanks - the new documentation system rocks, by the way!
Jim Grandy wrote:
Hi Max,
Docbook (or rather docbook-xsl) does have a facility for tracking
language, see
http://www.sagehill.net/docbookxsl/Localizations.html#LangAttribute
It doesn't handle conditional compilation per se, but we could
easily add a docbook-xsl customization that stripped all but one
language.
This would neatly solve the problem for the dev guide, but it
wouldn't solve things for the RefGuide since the 'wrapper pages'
no longer exist; the refguide is generated from comments in the
source code itself.
What we can do for the refguide is add a way of providing an
overlay mechanism, where a localized js2doc file (a simple XML
format) is used to override descriptive text on an entry-by-entry
basis.
I should also point out that one big change to the dev guide I'd
like to make is to migrate the English version of the developer's
guide to be pure Docbook. Currently it is in HTML with arbitrary
Docbook extensions, which complicates the tool chain without
adding much benefit. I believe we can accomplish this migration by
running the first pass of the tools once and checking in the
output; this should also be possible with any localized
documentation.
jim
On Mar 22, 2007, at 7:04 PM, Max Carlson wrote:
Hi Jim,
The friendly Laszlo.jp folks have begun translating the
developer's guide and wrapper pages to Japanese. After chatting
about process with Togawa-San, it seems like it would be ideal to
be able to tag documentation bits with a language tag, e.g.
<lang_jp>...</lang_jp> and have 'ant doc_jp' generate the docs
with just the <lang_jp/> bits. I'm sure docbook has a provision
for this. It seems like we could get away with leaving the
tagging system as-is and just translate the textual bits in the
documentation.
Let me know your thoughts, and how I can help!
--Regards,
Max Carlson
OpenLaszlo.org
--
Regards,
Max Carlson
OpenLaszlo.org
