You are viewing a plain text version of this content. The canonical link for it is here.
Posted to docs@httpd.apache.org by Paul Querna <pa...@querna.org> on 2009/11/25 20:41:22 UTC

Re: document translation infrastructure?

(adding docs@httpd cc)

On Tue, Nov 24, 2009 at 10:20 AM, Miles Libbey <ml...@apache.org> wrote:
> Hi folks-
> We have a volunteer to translate our documentation from English into Korean.
>  Any recommendations for translation management/infrastructure? That is-- as
> the english documentation changes, is there any software that can help to
> find out of date or new strings/sections?

I would recommend looking at or copying how the httpd project handles
documentation translation.

<http://httpd.apache.org/docs-project/docsformat.html>  Explains some
of the basics.

For translations, the build keeps track of what subversion revs
changes a english version of the document, and then modifies the
non-english translations with information about the missing revisions.
 On the generated output, it also automatically adds a banner saying
that the file is out of date compared to the english version.

A concrete example:
<https://svn.apache.org/repos/asf/httpd/httpd/trunk/docs/manual/bind.xml>
is the current english version of the bind() docs.'

the meta file keeps track of which translations are outdated:
<https://svn.apache.org/repos/asf/httpd/httpd/trunk/docs/manual/bind.xml.meta>

If you look at the german translation:
<https://svn.apache.org/repos/asf/httpd/httpd/trunk/docs/manual/bind.xml.de>
You can see it keeps a comment at the top of the file, tracking the
SVN revisions the english version has over the german version:
<!-- English Revision: 420990:587444 (outdated) -->

For the translater, they can then run svn log/diff over that rev range
and update their translation.

This system seems to work pretty well for docs@httpd, and I imagine it
could be adopted to raw HTML.

Someone from docs@httpd could likely explain it better....

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org


Re: document translation infrastructure?

Posted by André Malo <nd...@perlig.de>.
* Miles Libbey wrote: 


> Hi folks-
> I work in the Traffic Server incubator project, and have had our first
> request to translate documentation from English into Korean.
>
> I think I missing something in the process that Paul describes.  Sounds
> like:
> 1. Someone makes a change to the English docbook/xml file, and submits a
> patch.
> 2. The patch gets reviewed, and assuming high quality changes, gets
> committed

usually the people directly commit it. The English documentation has CTR 
policy (commit then review).

> 3. something happens in which all the xml.{language_code} files get a
> new "English Revision" comment [what's the something and it's
> surrounding process?], and I'm guessing all reviewed by/{language}
> translation comments get removed.

The English documents (xml) are authoritative. They have the 
LastChangedRevision property set which is filled inside a comment by every 
subversion checkout.

The translator of a document adds a comment to the translation, which 
contains the svn revision number the translation is based on (also within a 
comment, with a specified format).

The build system does the following on every run:

- check which translations exist
- check the LastChangedRevision of the english documents against each 
  translation and if it is different from the translator's comment, the 
  comment is changed to contain the original translator's base revision and 
  the new one of the english document. These generated comments are further
  modified if the English document changes again.
- generate "meta" files for each english document, which contain the 
  information collected above: which languages are available and whether 
  they are outdated or not.
- these meta files are included in the transformation process (xslt) to 
  generate the final html files and typemaps for mod_negotiation.
- Additionally for each language build a list of outdated files is emitted 
  on the console.

[...]


> 6. Something transforms the xml into html.  When transforming,
>   - if there is a (outdated) reference, the language site gets a "This
> translation may be out of date" message on the relevant pages (including
> the index).

Yes.

>   - the html files are copied to a language directory, removing the
> .{language_code} from the file name in the process
> [when does this happen? Is the priority to get a better English version
> out quickly or give other languages a chance to catch up before a push
> date?]

See the typemap story above. There's a corresponding httpd configuration 
working with the typemaps.

nd

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org


Re: document translation infrastructure?

Posted by Miles Libbey <ml...@apache.org>.
Hi folks-
I work in the Traffic Server incubator project, and have had our first 
request to translate documentation from English into Korean.

I think I missing something in the process that Paul describes.  Sounds 
like:
1. Someone makes a change to the English docbook/xml file, and submits a 
patch.
2. The patch gets reviewed, and assuming high quality changes, gets 
committed
3. something happens in which all the xml.{language_code} files get a 
new "English Revision" comment [what's the something and it's 
surrounding process?], and I'm guessing all reviewed by/{language} 
translation comments get removed.
4. Translators run something like
  svn update
  grep "(outdated) -->" *.xml.fr
to get a list of files that are outdated.  [is there something that 
prompts translators to do this?]
5. Translators submit patches (including changing the "English Revision" 
comment to remove the outdated reference, and their name in a 
translation comment), a second person reviews.  Assuming high quality 
changes the second person adds their name to a reviewed by comment, and 
the change is checked in.
6. Something transforms the xml into html.  When transforming,
  - if there is a (outdated) reference, the language site gets a "This 
translation may be out of date" message on the relevant pages (including 
the index).
  - the html files are copied to a language directory, removing the 
.{language_code} from the file name in the process
[when does this happen? Is the priority to get a better English version 
out quickly or give other languages a chance to catch up before a push 
date?]

Roughly correct?

Our current documentation is HTML based -- is there anything about the 
httpd doc process that could not be done for html (vs xml)?

Thanks!
miles libbey

Paul Querna may have written the following on 11/25/09 11:41 AM:
> (adding docs@httpd cc)
>
> On Tue, Nov 24, 2009 at 10:20 AM, Miles Libbey<ml...@apache.org>  wrote:
>> Hi folks-
>> We have a volunteer to translate our documentation from English into Korean.
>>   Any recommendations for translation management/infrastructure? That is-- as
>> the english documentation changes, is there any software that can help to
>> find out of date or new strings/sections?
>
> I would recommend looking at or copying how the httpd project handles
> documentation translation.
>
> <http://httpd.apache.org/docs-project/docsformat.html>   Explains some
> of the basics.
>
> For translations, the build keeps track of what subversion revs
> changes a english version of the document, and then modifies the
> non-english translations with information about the missing revisions.
>   On the generated output, it also automatically adds a banner saying
> that the file is out of date compared to the english version.
>
> A concrete example:
> <https://svn.apache.org/repos/asf/httpd/httpd/trunk/docs/manual/bind.xml>
> is the current english version of the bind() docs.'
>
> the meta file keeps track of which translations are outdated:
> <https://svn.apache.org/repos/asf/httpd/httpd/trunk/docs/manual/bind.xml.meta>
>
> If you look at the german translation:
> <https://svn.apache.org/repos/asf/httpd/httpd/trunk/docs/manual/bind.xml.de>
> You can see it keeps a comment at the top of the file, tracking the
> SVN revisions the english version has over the german version:
> <!-- English Revision: 420990:587444 (outdated) -->
>
> For the translater, they can then run svn log/diff over that rev range
> and update their translation.
>
> This system seems to work pretty well for docs@httpd, and I imagine it
> could be adopted to raw HTML.
>
> Someone from docs@httpd could likely explain it better....

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org