MadCap Flare und die Variablen

Die­ser Bei­trag ist eigent­lich nur was für Techi­es und User der Soft­ware „Fla­re“ von Mad­Cap. Und viel­leicht auch für Technikredakteur:innen, die sich mit dem Gedan­ken tra­gen, sich das Leben auch ohne teu­res Redak­ti­ons­sys­tem leich­ter zu machen…

Ein Pro­blem, das beson­ders in der Doku­men­ta­ti­on von Soft­ware oft auf­tritt, ist in die Ver­wen­dung einer text­las­ti­gen Benut­zer­ober­flä­che. Damit sind bestimm­te Pro­ble­me aber qua­si „ein­ge­baut“:

• Die Benut­zer­ober­flä­che benutzt zahl­rei­che Begrif­fe („Ter­me“), die nicht all­täg­lich sind. Meist liegt es dar­an, dass man bei der Ent­wick­lung der Soft­ware kei­ne Zeit für Icons „ver­schwen­den“ woll­te.
• Die­se Ter­me sol­len iden­tisch in der Doku­men­ta­ti­on ver­wen­det wer­den, da die Benut­zer sich sonst nicht zurecht­fin­den, da sie ja nicht auf die Ori­en­tie­rung mit Icons zurück grei­fen kön­nen.
• Die Soft­ware soll in vie­le Spra­chen über­setzt wer­den, in denen die Ter­me völ­lig anders lau­ten. Damit müs­sen auch die Ter­me in den jewei­li­gen Spra­chen mit den ver­wen­de­ten Begrif­fen in der Benut­zer­ober­flä­che über­ein­stim­men.

Wäh­rend die Ent­wick­ler der Soft­ware sich zunächst nur um die Quell­spra­che küm­mern müs­sen, also die kor­rek­te und kon­sis­ten­te Ver­wen­dung der Ter­me in der Soft­ware selbst, ist bei der Loka­li­sie­rung auch die Qua­li­täts­kon­trol­le gefragt: die Loka­li­sie­rung (im Haus oder durch exter­ne Dienst­leis­ter) sorgt dafür, dass die Begrif­fe in die Ziel­spra­che über­setzt und rich­tig ver­wen­det wer­den – und nicht Pro­ble­me auf­tre­ten wie „Gott siche­re den König!“ als Über­set­zung von „God save the King!“…

Aller­dings kann auch eine kor­rek­te Über­set­zung nicht ver­hin­dern, dass es Ter­me gibt, die in einer Ziel­spra­che ungleich mehr Platz auf dem Bild­schirm benö­ti­gen als in der Quell­spra­che vor­ge­se­hen. Das kann zu sehr unschö­nen Ver­schie­bun­gen und Über­la­ge­run­gen von Tex­ten auf dem Dis­play füh­ren. Um das zu ver­hin­dern, wer­den die über­set­zen Ter­me wie­der in die Soft­ware impor­tiert und in der Qua­li­täts­kon­trol­le auf dem Bild­schirm geprüft. Bei Pro­ble­men muss dann ent­we­der die Benut­zer­ober­flä­che ange­passt wer­den – für alle Spra­chen – oder es wer­den sinn­vol­le Abkür­zun­gen bzw. ande­re Begrif­fe in der Ziel­spra­che defi­niert.

Bis dahin aber haben wir nur die Soft­ware, nicht die Doku­men­ta­ti­on dazu.

Um eine Soft­ware über­set­zungs­fä­hig zu hal­ten, legen die Ent­wick­ler ihre ver­wen­de­ten Begrif­fe in einer eige­nen Datei an, die beim Start der Soft­ware (unter Rück­griff auf die ein­ge­stell­te Ziel­spra­che) die pas­sen­den Ter­me aus die­ser Datei aus­liest und an die vor­ge­ge­be­ne Stel­le auf der Benut­zer­ober­flä­che plat­ziert. Die Soft­ware hat dazu Platz­hal­ter mit ein­deu­ti­gen Namen, denen in der Sprach­da­tei die pas­sen­den Begrif­fe zuge­ord­net sind. Man kann sich das wie eine Tabel­le vor­stel­len, in deren ers­ter Spal­te die Platz­hal­ter ange­zeigt wer­den und in den fol­gen­den Spal­ten die Ter­me in den jewei­li­gen Spra­chen. Sobald die Spra­che umge­stellt wird, springt das Pro­gramm in die Zei­le mit dem auf­ge­ru­fe­nen Platz­hal­ter und dann in die Spal­te der Ziel­spra­che – und zeigt den dort gefun­de­nen Term an.

Easy.

Wenn man als Technikredakteur:in aber nun eine Doku­men­ta­ti­on in Fla­re schreibt, legt man den gesam­ten Text in der Quell­spra­che an und muss bei der Ver­wen­dung eines Terms in der Benut­zer­ober­flä­che an die­ser Stel­le eben­so einen Platz­hal­ter set­zen, damit nach einer Über­set­zung an die­ser Stel­le dann der korrk­te Term in der Ziel­spra­che ange­zeigt wird.

Fla­re (und ande­re Text­ver­ar­bei­tun­gen auch) ver­wen­det dazu Varia­ble, die als Varia­blen­set im Pro­jekt­ord­ner lie­gen. Fla­re kann eine Viel­zahl von Varia­blen­sets ver­wal­ten, und da die­se Varia­blen erst bei der Aus­ga­be der Tex­te mit den defi­nier­ten Ter­men gefüllt wer­den, arbei­tet man mit allen Platz­hal­tern, die in den vor­han­de­nen Sets ange­legt sind. Bei einer Über­set­zung müs­sen aber die Varia­blen­sets in allen Ziel­spra­chen die glei­chen Namen tra­gen und die glei­chen Platz­hal­ter besit­zen, damit Fla­re sie kor­rekt refe­ren­ziert.

Wie aber kommt man nun an die Varia­blen?

Wie oben bereits erwähnt, arbei­ten auch die Ent­wick­ler nur mit Text­bau­stei­nen, die sich als Excel-Tabel­le expor­tie­ren las­sen. Die­se Excel-Tabel­le ent­hält aber eine gesam­te Über­sicht über alle Platz­hal­ter und Ter­me in allen Loka­li­sie­run­gen (Ziel­spra­chen). Fla­re kann aber aus Excel-Tabel­len kei­ne Varia­blen­sets machen. Letz­te­re sind näm­lich XML-Datei­en. Und genau das ist der Ansatz­punkt für eine manu­el­le Kon­ver­tie­rung.

Von XLS zu XML

Als Werk­zeug brau­chen wir eine Tabel­len­kal­ku­la­ti­on wie Excel und einen ein­fa­chen Text­edi­tor wie BBE­dit (macOS) oder Note­pad (Win­dows). Und natür­lich Fla­re selbst für die Kon­trol­le.

1. Mit Excel die Tabel­le der Begrif­fe öff­nen und ein neu­es Blatt anle­gen. Am bes­ten für jede Ziel­spra­che ein neu­es Blatt.
2. Aus der Tabel­le die Spal­te der Platz­hal­ter kopie­ren und in das neue Blatt in die zwei­te Spal­te ein­set­zen.
3. Das Blatt mit den Begrif­fen öff­nen und die Spal­te der Sprach­aus­prä­gun­gen (Quell- oder Ziel­spra­che) kopie­ren.
4. Die kopier­te Spal­te in die vier­te Spal­te auf dem neu­en Blatt ein­set­zen.

Im nächs­ten Schritt müs­sen wir aus der Tabel­le eine Text­da­tei machen, die dann mit den pas­sen­den XML-Ele­men­ten „ange­rei­chert“ wird. ¹XML ist eine Aus­zeich­nungs­spra­che, bei der die „Aus­zeich­nun­gen“ (Tags) in spit­zen Klam­mern den Begriff ein­rah­men und damit kenn­zeich­nen, wo der Inhalt beginnt und wo er endet: „<h1>“ bei­spiels­wei­se kenn­zeich­net den Beginn der Über­schrift in der ers­ten Ebe­ne, „</​h1>“ kenn­zeich­net ihr Ende: „<h1>Überschrift der ers­ten Ebene</h1>“ zeigt bei­s­pu­iels­wei­se ein Brow­ser als „Über­schrift 1″ an. Das Aus­se­hen des Tex­tes lässt sich in einer ande­ren Datei bestim­men, dem „Style­sheet“. Das ist hier sehr vor­teil­haft, da dadurch die For­ma­tie­rung (das Aus­se­hen) völ­lig unab­hän­gig vom Inhalt defi­niert wer­den kann.

1. In die ers­te Spal­te den Aus­druck <Varia­ble Name=“ ein­set­zen und nach unten mul­ti­pli­zie­ren. Damit wer­den die Aus­zeich­nun­gen „Varia­ble“ geöff­net.
2. In die drit­te Spal­te den Aus­druck „> ein­set­zen und nach unten mul­ti­pli­zie­ren. Damit schlie­ßen wir die Platz­hal­ter­de­fi­ni­ti­on „Name“.
3. In die fünf­te Spal­te den Aus­druck </​Variable> ein­set­zen und nach unten mul­ti­pli­zie­ren. Damit sind die Aus­zeich­nun­gen „Varia­ble“ geschlos­sen.
4. Das Tabel­len­blatt als *.CSV-Datei expor­tie­ren. Damit erset­zen wir die Tabel­len­zel­len durch Satz­zei­chen und erhal­ten eine dum­me Text­da­tei.

1. Mit dem Text­edi­tor (hier BBE­dit) in meh­re­ren Such­läu­fen die Satz­zei­chen ent­fer­nen.
2. Mit dem Text­edi­tor ein vor­han­de­nes Varia­blen­set im Fla­re-Pro­jekt­ord­ner öff­nen (falls kein Varia­blen­set vor­han­den ist, in Fla­re mit „Neu > Varia­blen­set“ im ent­spre­chen­den Ord­ner anle­gen).
3. Aus die­sem Varia­blen­set die ein­lei­ten­den Zei­len „<?xml .… <Cata­pult­Va­riable­Set>“ kopie­ren und vor die ers­te Zei­le der Text­da­tei ein­fü­gen. Damit wird fest­ge­legt, was Fla­re mit den nach­fol­gen­den Aus­zeich­nun­gen machen soll.
4. Aus dem Varia­blen­set die letz­te Zei­le „</​CatapultVariableSet>“ kopie­ren. Damit wird in guter XML-Manier die Aus­zeich­nung wie­der geschlos­sen.
5. Die Datei als *.flvar spei­chern und in Fla­re in den Ord­ner „Variable­Sets“ kopie­ren.

Jetzt müs­sen wir nur noch zur Kon­trol­le die Datei in Fla­re öff­nen, um zu sehen, ob Fla­re damit ein­ver­stan­den ist – mög­li­cher­wei­se ent­hält der Text (schwarz) Son­der­zei­chen, die nicht mit der XML-Defi­ni­ti­on kom­pa­ti­bel sind.

Die­se Schrit­te muss man zwar für jede Spra­che wie­der­ho­len, da sich die Begrif­fe im Inter­face jedoch nicht so oft ändern, ist die Häu­fig­keit eher gering. Und mit ein biss­chen Übung auch in weni­gen Minu­ten erle­digt…

• 1
  XML ist eine Aus­zeich­nungs­spra­che, bei der die „Aus­zeich­nun­gen“ (Tags) in spit­zen Klam­mern den Begriff ein­rah­men und damit kenn­zeich­nen, wo der Inhalt beginnt und wo er endet: „<h1>“ bei­spiels­wei­se kenn­zeich­net den Beginn der Über­schrift in der ers­ten Ebe­ne, „</​h1>“ kenn­zeich­net ihr Ende: „<h1>Überschrift der ers­ten Ebene</h1>“ zeigt bei­s­pu­iels­wei­se ein Brow­ser als „Über­schrift 1″ an. Das Aus­se­hen des Tex­tes lässt sich in einer ande­ren Datei bestim­men, dem „Style­sheet“. Das ist hier sehr vor­teil­haft, da dadurch die For­ma­tie­rung (das Aus­se­hen) völ­lig unab­hän­gig vom Inhalt defi­niert wer­den kann.