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
|
|
Patrick Riffel Team Leader Information Development
+49 711 806098-0
Hauptstätter Straße 70 |
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