Re: [Docutils-users] reStructuredText and Localization of Documents, Scaling to Lots of Content, Managed Over Time

[Guenter M. <mi...@us...>]

On 2019-10-31, Kent Borg wrote:
> I am wondering about tools and techniques to help manage translating and 
> localizing documents. Particularly when scaled up and used over time.

Did you have a look at the translating extension for Sphinx?
(I know it exists, but don't know a URL or details.)

> Some considerations:

> - Say a commercial service produces a translated rST document, how might 
> we easily know that it is structurally the same (that the RST didn't 
> accidentally get edited)?

It would be possible code a transform that strips all Text
nodes when exporting. Alternatively, you may use XSLT processing of the
Docutils XML output...

But you may also think about different order of marked-up words or links due
to different grammatical rules in the respective languages...


> - As documents change over time, sometimes there will only be small 
> changes. We don't want to waste time and money redoing the entire 
> document, but the translator should be able to see the whole document, 
> to see the context, but only translate the changed part. (Alternatively, 
> maybe in the only-one-change example, the translator needs to change in 
> a different part of the document because of a change in terminology that 
> should correspond.)

You may split the document source in a master and several child documents.
Pass the relevant child rST and an export of the complete document to the
translating service...


> Some of the things I am wondering about slide into content management 
> questions and don't have any language-specific aspects and are just 
> worrying about managing rST documents over time, maybe with shared 
> components that are used via include directives, etc.

Being text based, rST documents are well suited for version management via
Git or similar.


As a Python package, Docutils can be used as module of a wider system.
Limits are your imagination and coding ressources.

> I note that the Wikipedia has a page on content management systems, and 
> another page on translation management systems. I'm wondering about rST 
> considerations...


Günter