Hi all,
the issue of keeping UI strings and documentation in sync sounds familiar and
I'd like to let you know how we've been doing it for last 12 years or so - not
perfect but robust enough to publish several dozen documents with up to 1300
pages in two (was four) languages as PDF and webhelp.
The software we are writing documentation for is using dozens of XML files for
its configuration and user interface. Each UI string comes with an ID that is
more or less unique, and we can therefore reuse it in our documentation.
However, almost every configuration file has a slightly different content model
to the one before and therefore we have to pre-process everything before we can
actually use it.
In this pre-processing step, a script pulls together all the UI strings from
all the different configurations into a "normalized" xml file. This step also
pulls in the translated versions of strings. You end up with a rather big xml
file ("alltext.xml"), in which you have the ID, the original string and
translations in one place. If a translation is missing, we add a placeholder
text.
On the Docbook side, we are using guilabel/guimenu/guimenuitem to tag UI text.
By our convention, each of these elements must have a @remap attribute with its
value set to one of the IDs you can find in the software configuration files
(or rather in that big xml file from the previous step). Referencing the ID is
the important bit for the automation. For readability, the Technical Writer
would also use the UI string as content for guilabel/guimenu/guimenuitem.
However, this isn't strictly necessary as the element's content will be
replaced at a later stage.
Our publishing process is automated via ant/jenkins. Once all xincludes have
been resolved, we use some XSLT on the resulting temporary file and replace the
UI strings with the most recent versions from "alltext.xml". And that's more or
less it - an ID-based lookup and string replacement.
To assist our Technical Writers, we also provide modified versions of the
software configuration. This configs can be used to run the software in a way
that will display the internal ID alongside the UI text. By doing this, the
Technical Writer is provided with sufficient context to find the right ID to be
used for @remap. It also helps to avoid confusion where the configuration files
have several copies of the same UI string but with different ID values.
Since the UI strings are translated separately and keep their original ID, the
remapping also works when we are publishing in other languages (our primary
language is German, and we translate into English. This process has been used
in the past to translate into French, Italian and Russian as well).
A word on the authoring process: We are using oXygen XML and have put together
some schematron rules that will flag up when a remap attribute is missing or
when the content of a guilabel is different from the current value in the
lookup file. This was done as a proof-of-concept and isn't required for
authoring, but we encourage using it. We are also experimenting with schematron
quickfixes to replace UI strings where necessary - this also is experimental
and not a feature we are using all the time, but it comes in handy every now
and then.
We do most of our translation inhouse (we used OmegaT in the past, but not
anymore, sorry!). The documentation and the UI strings are translated
separately (by the same Translator) into two separate translation memories.
When translating the documentation, all guilabel/guimenu/guimenuitem are set to
be non-translatable. However, our Translator sees the element content and thus
has all the context information they need. Once they export their files to the
target language, the UI strings will still be in German. The German text is
then replaced via a combination of @lang and @remap when publishing to their
respective output format.
For those cases where UI text does need to be translated/localized, a Technical
Writer can set a @translate attribute to "yes" on guilabel elements and
override the replacement. The TMS will unlock those elemetns and the Translator
can modify the content of those elements.
I am aware that this process might be problematic with certain languages and/or
if the source material is not well maintained and probably
for many other reasons, too. We had trouble in the past with UI text that was
split into several individual strings or when placeholders are
being used. With regards to mnemonics and shortcuts - those are indeed
annoying. Our specific problem is that the software configuration wasn't
designed to be translation friendly, and we basically have to strip away things
before going into translation. I do believe that this problem could be solved
if we put in some effort in redesigning the configuration files. Screenshots
also matter and need manual updates when the UI text changes.
Bottom line is: We manage to keep our documentation and user interface
synchronized in terms of UI strings. It took a while to get to this level and
we still haven't solved every issue but for the most part, it works. On top of
that, the Technical Writers and our Dev team are constantly sharing
information. Developers also need to consult the Technical Writers and
Translator before adding or changing any UI text - that way we have more
control over terminology and consistency.
I hope that helps and you get some ideas out of this.
Regards
Patrick
[Quadient]
Patrick Riffel
Team Leader Information Development
p.rif...@quadient.com<mailto:p.rif...@quadient.com>
+49 711 806098-0
Hauptstätter Straße 70
70178 Stuttgart
www.quadient.com<https://www.quadient.com/>
Learn more about Quadient<https://www.quadient.com/connections>
Quadient DOPiX Germany GmbH ist ein beim Amtsgericht Stuttgart eingetragenes
Unternehmen.
Registernummer: HRB 17655
Sitz der Gesellschaft: Hauptstätter Straße 70, 70178 Stuttgart
Geschäftsführer: Andreas Schwegler, Duncan Spanner, Laurent du Passage
