[as2api-dev] Re: russian support of as2api

[David Holroyd]

On Wed, Feb 08, 2006 at 06:04:57PM +0000, David Holroyd wrote:
> On Wed, Feb 08, 2006 at 04:24:21PM +0300, Ivan Dembicki wrote:
> > Recently we examined a lot of tools for documenting ActionScript.
> > We've found your as2api to be the most suitable for easy and frequent
> > use, so, we would like to support your project in russian. This should
> > include translation of the manual, writing of some additional help
> > files, creating of use samples etc.
> > 
> > To make this happen, we require one slight addition to as2api
> > features. Namely, we would highly appreciate if you add support of
> > @lang tag, that will delimit document context help for different
> > languages. As we see it, a perfect tool should be able to understand
> > @lang tag and generate different html files (in different folders) for
> > the designated languages.

> This is a really interesting idea, and an area I hadn't given any
> thought to before.  Translation of the text within as2api (HTML headers,
> etc.) is already a long term goal, but supporting the content itself in
> multiple languages is new idea to me.
> 
> My initial thought is that I would not put the translations into the
> original source files.  Rather, the source should be documented with the
> author's primary language, and translations should be pulled in from an
> external file.
> 
> I think that maintaining all the translations within the original source
> would become increasingly difficult the number of target languages
> increases.  By placing the translations outside the source, adding
> a translation to a new language doesn't require modification to the
> original sources, which seems desirable to me.
> 
> Searching around, I think that something like XLIFF could be an
> appropriate format for external translation data:
> 
>   http://www.oasis-open.org/committees/xliff/documents/xliff-specification.htm

I've started working on XLIFF import / export.  It can currently handle
very simple substitutions of one section of comment-text for another, but
doesn't yet handle inline tags (e.g. the '{@link ..}' tag) or some other
important details like multiple '@see' blocks.

I also found a couple of free GUI tools for working with XLIFF data:

  'Transolution' is implemented in Python and GTK,
  http://transolution.python-hosting.com/

  'Open Language Tools' provide a XLIFF editor implemented in Java,
  https://open-language-tools.dev.java.net/

Both worked, but seemed a little bit 'quirky' (could just be that I
didn't understand how to use them properly).


----

In addition I've just committed support for using gettext to localise
text generated by as2api.  This will allow messages printed on the
command line, and things like section headings in the generated HTML to
be translated into other languages.

I'm hoping to be able to use the Launchpad 'Rosetta' service to allow
people to contribute translations of as2api.  I've just uploaded the
translatable data, but this must be allowed though a moderation queue
before it will appear on the site.


ta,
dave

-- 
http://david.holroyd.me.uk/