[Mono-list] ECMA compliance

[Serge]

I think it's a viable solution. Strictly speaking there is no fixed schema
for XML comments so everyone is free to extend it at will.
I'd prefer to stay away from XML namespaces and use nested tag instead.
Something like
<i18n>
  <l10n lang="...">
   Translated comments here.
  </l10n>
  ....
</i18n>

But that's surely not that important.

The important thing is encoding - what encoding to use.
Many widely-used code editors are not "Unicode-enabled", moreover some
have problems with anything beyond 7-bit charset.
So maybe it's better to have only English version embedded, and separate
files with translation.

Still, I think we should listen to the guys who have experience with API doc
translation.
I don't have such experience (moreover, I live in Ukraine, but I can't even
imagine the docs translated to Ukranian, don't ask me why - it's impossible
to explain in English ;-))) - still, I believe localization is very
important).


----- Original Message -----
From: "A Rafael D Teixeira" <rafaelteixeirabr@hotmail.com>
To: <serge@wildwestsoftware.com>; <mono-list@ximian.com>
Sent: Friday, November 23, 2001 4:28 PM
Subject: Re: [Mono-list] ECMA compliance


> Let me dream a little...
>
> First: I´m sure the original documentation MUST be embedded, or it´ll get
> out-of-sync very easily. The question here is: can we extend the XML
schema
> to allow for multiple languages in the original documentation? I would
like
> the answer to be yes, so that I could keep english and brazilian
portuguese
> documentation in my sources, like this:
>
> /// <summary i18n:lang="EN-US">This method returns the container of a
given
> control</summary>
> /// <i18n:summary lang="PT-BR">Este método retorna o contêiner do controle
> passado</i18n:summary>
> /// <param name="control" i18n:lang="EN-US">Control in question</param>
> /// <i18n:param name="control" lang="PT-BR">Controle em
questão</i18n:param>
> public static Control ContainerFor(Control control)
> {
> //....
> }
>
> Second: We can think of a centralized repository for xml documentation, a
> kind of cvs interfaced by web services, to control and NOTIFY translators
of
> changes in the original documentation
>
> What do you think?
>
> Rafael Teixeira
> Brazilian Developer