httpd-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Miles Libbey <mlib...@apache.org>
Subject Re: document translation infrastructure?
Date Tue, 01 Dec 2009 22:33:02 GMT
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<mlibbey@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


Mime
View raw message