[as2api-dev] Re: russian support of as2api

[David Holroyd]

Hi there,

On Wed, Feb 08, 2006 at 04:24:21PM +0300, Ivan Dembicki wrote:
> Hello,
> 
> This letter is sent to you on behalf of some of the russian flash
> community leaders. 
> 
> 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.
> 
> The workflow of the tool, as we see it:
> 
> - default language is english (or russian. hehe :) )
> - multiple @lang tags may be present in the document
> - when parser encounters @lang tag, it assumes, that the comment text
>   that follows, should be treated as designated language until next
>   @lang tag is found
> - html files are placed in the folders named by the language name that
>   is set in the @lang tag
> - if multiple languages are used in @lang tags, there should be
>   switches for language versions in resulting html files
> 
> Command line:
> - there should be "--language" parameter, that will specify for what
>   language you want to generate doc files (default - all languages)
> 
> That is how we see it.
>   
> Please, contact me if your are interested in further discussion and if
> you are willing to implement some new features in your as2api project.

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

There are even GUI tools that can help you to create resources in this
format (they may be commercial -- I didn't really look into this).


The default workflow could then be:

 - default comment language is english, russian, etc.
 - as2api is run against the source in a special mode that generates a
   new XLIFF file with an empty slot for each bit of translatable text
   (plus, presumably, a copy of the same text in the original language,
   as read from the source comments)
 - the translator works though this file to create the content for the
   target language
 - as3api is run against the original source with a --language parameter
   which causes it to look in the XLIFF file for the text to include
   against each API element (instead of using the text in the doc
   comments)


What do you think of this?


dave

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