At the former company, we attempted to restrict product names as
untranslated, and this initially worked for western languages where
we started first, but then it didn't work later for some eastern
languages that already had a special trademark for that country,
from what I remember. I think we had some problems too around
feature names that in some cases simply had to be translated even
for cultural reasons.
We had Information Developer training around how to use product and
feature name variables effectively by restricting the way we wrote
around them to avoid translation common issues.
Finally, we avoided references to the product in general going
forward. Fortunately, in software, we can often refer generically to
the product as "the system" or application in context. Still, we had
some high level material that required the product name and we would
use the variable there.
In most cases, we used the majority of variables for nasty,
constantly changing feature names. :-)
In another case, we had a specialized product that required
variables for business object names that could be overridden by the
customer, which we then output to in-place help variables with a
dynamic mapping file. (Kind of cool, actually, though little seen
In short, I don't think there is an easy answer that avoids changes
to schemas, workflow, writing practices, and output processing for
holding and processing an effective product or feature element along
the lines of a variable, but once implemented, the automation and
customization is very powerful.
I have played around with content references with some success to
simulate variables as used in a previous company. I forget what the
specific limitations are, but I wasn't totally happy with it.
If I were to create a variables architecture for DITA today using OT
as a reference processor, I would create a generic schema for
variables, then specialize attributes as needed for products and
features (at minimum). Use a mapping file in XML to hold the
resolved values and keys. Then create a processing plug-in for those
variables, which might include special graphics associated with the
product name, if needed (has actually happened).
On 1/16/2013 9:03 AM, Kristen James Eberlein wrote:
Troy, there were a couple of
questions that I want to ask. Did the company's style guide
restrict the content developers as to how they used the
product names, for example, using product names only in the
Were the product names translated or left in English? I think
translated, based on your post, but wanted to check -- some
companies handle the problem of reusing company names by NOT
You mentioned using attributes to indicate plurals or
possessives; did you do anything to handle case or part of
Thanks for your interesting post!
Kristen James Eberlein
Principal consultant, Eberlein Consulting
Co-chair, OASIS DITA Technical Committee
Charter member, OASIS DITA Adoption Committee
+1 919 682-2290; kriseberlein (skype)
On 1/16/2013 8:47 AM, Troy Klukewich wrote:
We translated the English XML content and mapping files into
multiple languages, including Chinese, Japanese, and Arabic,
which are probably some of the more difficult languages to
translate. The agencies worked with our build kit and
generated translated versions per language, including PDF.
Granted, we had some great development resources to program
the XSLT and XSL:FO appropriately to handle multiple
I do remember some iterations where translation had to tweak
the PDF output until we programmed a solution (indexing was
challenging for Japanese, right-to-left languages, etc.). In
any case, the amount of total manual work translation had to
perform versus previous iterations was massively reduced with
subsequent cost savings and rapid turn-around. From what I
recall, we reached 100% automation for all languages handled.
If you could be more specific about which language
morphologies cannot work with variables, I'd be interested. In
some cases, the best solution might be to dump out an XLIFF
with resolved values for variables, so the base XML isn't
translated, but the XLIFF version of the same with a two-way
transformation back to the build kit for a translated version
Some translation groups will work with build kits, some don't,
so this also needs to be factored into workflow.
So I suspect that there may be no perfect global solution to
handle all possible languages from base DITA XML, but a
technical solution that handles most and then an alternate
workflow for those languages that cannot work with variables
On 1/15/2013 1:34 PM, Andrzej Zydron wrote:
Thank you for
this interesting post. Your mechanism will work for English,
and the small group of languages with a similar
primitive morphology. Unfortunately it will
fall apart when you come to translate the XML
content into any
language with a richer morphology - the
resultant output will produce ungrammatical
output and the cost of recovery from
this will be extensive.
English is a linguistic freak (a fact that
is lost on most monolingual
which allows for the relative easy substitutions that you described. I you plan to
translate your content into other languages this is
XTM International Ltd.
PO Box 2167, Gerrards Cross, SL9 8XF,
Tel: +44 (0) 1753 480 479
Mob: +44 (0) 7966 477 181