OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

docbook-apps message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: Re: [docbook-apps] Multilanguage DocBook documents - best practices needed

Hi Robert,
Your life will be much easier if you separate the languages into separate directories. Translation management process then can be assisted by your source control system telling you which language modules have changed since the last translation, and you can track the progress of each language separately.

Separate files would also be better for olinking. Keeping them separate allows you to keep the original id attributes on the translated content. If they were in the same file, the translated ids would have to be changed to avoid duplicate ids, and then your olinking would break without further customization. Each language would have its own olink database, referencing the target.db files of its respective translated books. With ids preserved, the original olink targetdoc attributes will still work, but will deliver translated link text.

I should mention that olinking also has a language fallback feature. If, for example, one of your books is not translated, an olink database for a translation could reference the English target.db, and it will be handled as English if it is labeled with a lang="en" attribute. That feature is described here:


Bob Stayton
Sagehill Enterprises

----- Original Message ----- From: "Robert Fekete" <frobert@balabit.com>
To: "Bob Stayton" <bobs@sagehill.net>
Cc: <docbook-apps@lists.oasis-open.org>
Sent: Wednesday, July 18, 2012 11:54 PM
Subject: Re: [docbook-apps] Multilanguage DocBook documents - best practices needed

Sorry if I was not clear on this.

The books I am talking about are product manuals, about three-four separate books that are cross-linked, olinked, and modular, all the bells and whistles that DocBook offers to single-source technical documents. It also gets updated and somewhat reorganized 3-4 times a year, as new versions of the product are released. All of this is currently in English, but we will get it translated to other languages. I am unsure what is the best way to handle it so that after the translation, for example, olinks will keep working and point to the proper place in the translated document, and so on.

I imagine that one way would be to put the source text and the translations into the same file (for every file we have), and then create different versions of the top-level book element with different lang attributes. But then if we have to manage 3+ different languages in the same file, this would be a pain, and it would also require lots of extra work to merge back the different translations to the same file when we get it back from the translator.

Another way might be to duplicate every file into separate language directories, and modify our build scripts to handle them "properly". Here I am not sure if the olink database and similar things will work properly (but maybe I am just being afraid of shadows).


On 07/18/2012 11:05 PM, Bob Stayton wrote:

When you say "Multilanguage DocBook documents", I think of single book
containing both the master language and the translations. Or are the different
languages in different books? If they are mixed together in one book, then you
will have to modify xml:id values in the translated content to avoid duplicate
ids, and that will affect your cross referencing as well.

Bob Stayton
Sagehill Enterprises

----- Original Message ----- From: "Fekete Róbert" <frobert@balabit.com>
To: <docbook-apps@lists.oasis-open.org>
Sent: Wednesday, July 18, 2012 11:47 AM
Subject: [docbook-apps] Multilanguage DocBook documents - best practices needed

Hi Everyone,

I am in need for your experiences and advice about handling multilanguage
DocBook documents (that is, documents in a master language and its translations).

We have a set of DocBook documents (books and articles) that are heavily
modular (consisting of 50+ source files), and rich with xrefs, olinks, and
screenshots. Currently we have three output formats, but we are planning to
add new formats as well. Now these documents has to be translated - currently
to one language, possibly to more in the future.

Another gotcha is, that this is is not a one-time translation, but should be
maintained and updated about 3-4 times a year with the changes of the original
document. (We do use version control.)

So my question is, do you have any recommendations on how to handle and manage
the translation and multilanguage building of such a document set? What is the
"best" way to organize the source files? I am looking for a solution that, for
example, minimizes the risk of breaking links in the translated versions, and
also does not require much post-processing on the translated files (except for
generating the output files).

Also, since the translation will be done by an external translation agency
(using computer-aided translation tools), storing the source text and the
translations in the same file is not really feasible.

Any comment, tip, or recommendation is most welcome.

Kind Regards,

Robert Fekete

To unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: docbook-apps-help@lists.oasis-open.org

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]