MadCap Flare und die Variablen

Dieser Beitrag ist eigentlich nur was für Techies und User der Software „Flare“ von MadCap. Und vielleicht auch für Technikredakteur:innen, die sich mit dem Gedanken tragen, sich das Leben auch ohne teures Redaktionssystem leichter zu machen…

Ein Problem, das besonders in der Dokumentation von Software oft auftritt, ist in die Verwendung einer textlastigen Benutzeroberfläche. Damit sind bestimmte Probleme aber quasi „eingebaut“:

• Die Benutzeroberfläche benutzt zahlreiche Begriffe („Terme“), die nicht alltäglich sind. Meist liegt es daran, dass man bei der Entwicklung der Software keine Zeit für Icons „verschwenden“ wollte.
• Diese Terme sollen identisch in der Dokumentation verwendet werden, da die Benutzer sich sonst nicht zurechtfinden, da sie ja nicht auf die Orientierung mit Icons zurück greifen können.
• Die Software soll in viele Sprachen übersetzt werden, in denen die Terme völlig anders lauten. Damit müssen auch die Terme in den jeweiligen Sprachen mit den verwendeten Begriffen in der Benutzeroberfläche übereinstimmen.

Während die Entwickler der Software sich zunächst nur um die Quellsprache kümmern müssen, also die korrekte und konsistente Verwendung der Terme in der Software selbst, ist bei der Lokalisierung auch die Qualitätskontrolle gefragt: die Lokalisierung (im Haus oder durch externe Dienstleister) sorgt dafür, dass die Begriffe in die Zielsprache übersetzt und richtig verwendet werden – und nicht Probleme auftreten wie „Gott sichere den König!“ als Übersetzung von „God save the King!“…

Allerdings kann auch eine korrekte Übersetzung nicht verhindern, dass es Terme gibt, die in einer Zielsprache ungleich mehr Platz auf dem Bildschirm benötigen als in der Quellsprache vorgesehen. Das kann zu sehr unschönen Verschiebungen und Überlagerungen von Texten auf dem Display führen. Um das zu verhindern, werden die übersetzen Terme wieder in die Software importiert und in der Qualitätskontrolle auf dem Bildschirm geprüft. Bei Problemen muss dann entweder die Benutzeroberfläche angepasst werden – für alle Sprachen – oder es werden sinnvolle Abkürzungen bzw. andere Begriffe in der Zielsprache definiert.

Bis dahin aber haben wir nur die Software, nicht die Dokumentation dazu.

Um eine Software übersetzungsfähig zu halten, legen die Entwickler ihre verwendeten Begriffe in einer eigenen Datei an, die beim Start der Software (unter Rückgriff auf die eingestellte Zielsprache) die passenden Terme aus dieser Datei ausliest und an die vorgegebene Stelle auf der Benutzeroberfläche platziert. Die Software hat dazu Platzhalter mit eindeutigen Namen, denen in der Sprachdatei die passenden Begriffe zugeordnet sind. Man kann sich das wie eine Tabelle vorstellen, in deren erster Spalte die Platzhalter angezeigt werden und in den folgenden Spalten die Terme in den jeweiligen Sprachen. Sobald die Sprache umgestellt wird, springt das Programm in die Zeile mit dem aufgerufenen Platzhalter und dann in die Spalte der Zielsprache – und zeigt den dort gefundenen Term an.

Easy.

Wenn man als Technikredakteur:in aber nun eine Dokumentation in Flare schreibt, legt man den gesamten Text in der Quellsprache an und muss bei der Verwendung eines Terms in der Benutzeroberfläche an dieser Stelle ebenso einen Platzhalter setzen, damit nach einer Übersetzung an dieser Stelle dann der korrkte Term in der Zielsprache angezeigt wird.

Flare (und andere Textverarbeitungen auch) verwendet dazu Variable, die als Variablenset im Projektordner liegen. Flare kann eine Vielzahl von Variablensets verwalten, und da diese Variablen erst bei der Ausgabe der Texte mit den definierten Termen gefüllt werden, arbeitet man mit allen Platzhaltern, die in den vorhandenen Sets angelegt sind. Bei einer Übersetzung müssen aber die Variablensets in allen Zielsprachen die gleichen Namen tragen und die gleichen Platzhalter besitzen, damit Flare sie korrekt referenziert.

Wie aber kommt man nun an die Variablen?

Wie oben bereits erwähnt, arbeiten auch die Entwickler nur mit Textbausteinen, die sich als Excel-Tabelle exportieren lassen. Diese Excel-Tabelle enthält aber eine gesamte Übersicht über alle Platzhalter und Terme in allen Lokalisierungen (Zielsprachen). Flare kann aber aus Excel-Tabellen keine Variablensets machen. Letztere sind nämlich XML-Dateien. Und genau das ist der Ansatzpunkt für eine manuelle Konvertierung.

Von XLS zu XML

Als Werkzeug brauchen wir eine Tabellenkalkulation wie Excel und einen einfachen Texteditor wie BBEdit (macOS) oder Notepad (Windows). Und natürlich Flare selbst für die Kontrolle.

1. Mit Excel die Tabelle der Begriffe öffnen und ein neues Blatt anlegen. Am besten für jede Zielsprache ein neues Blatt.
2. Aus der Tabelle die Spalte der Platzhalter kopieren und in das neue Blatt in die zweite Spalte einsetzen.
3. Das Blatt mit den Begriffen öffnen und die Spalte der Sprachausprägungen (Quell- oder Zielsprache) kopieren.
4. Die kopierte Spalte in die vierte Spalte auf dem neuen Blatt einsetzen.

Im nächsten Schritt müssen wir aus der Tabelle eine Textdatei machen, die dann mit den passenden XML-Elementen „angereichert“ wird. ¹XML ist eine Auszeichnungssprache, bei der die „Auszeichnungen“ (Tags) in spitzen Klammern den Begriff einrahmen und damit kennzeichnen, wo der Inhalt beginnt und wo er endet: „<h1>“ beispielsweise kennzeichnet den Beginn der Überschrift in der ersten Ebene, „</h1>“ kennzeichnet ihr Ende: „<h1>Überschrift der ersten Ebene</h1>“ zeigt beispuielsweise ein Browser als „Überschrift 1“ an. Das Aussehen des Textes lässt sich in einer anderen Datei bestimmen, dem „Stylesheet“. Das ist hier sehr vorteilhaft, da dadurch die Formatierung (das Aussehen) völlig unabhängig vom Inhalt definiert werden kann.

1. In die erste Spalte den Ausdruck <Variable Name=“ einsetzen und nach unten multiplizieren. Damit werden die Auszeichnungen „Variable“ geöffnet.
2. In die dritte Spalte den Ausdruck „> einsetzen und nach unten multiplizieren. Damit schließen wir die Platzhalterdefinition „Name“.
3. In die fünfte Spalte den Ausdruck </Variable> einsetzen und nach unten multiplizieren. Damit sind die Auszeichnungen „Variable“ geschlossen.
4. Das Tabellenblatt als *.CSV-Datei exportieren. Damit ersetzen wir die Tabellenzellen durch Satzzeichen und erhalten eine dumme Textdatei.

1. Mit dem Texteditor (hier BBEdit) in mehreren Suchläufen die Satzzeichen entfernen.
2. Mit dem Texteditor ein vorhandenes Variablenset im Flare-Projektordner öffnen (falls kein Variablenset vorhanden ist, in Flare mit „Neu > Variablenset“ im entsprechenden Ordner anlegen).
3. Aus diesem Variablenset die einleitenden Zeilen „<?xml …. <CatapultVariableSet>“ kopieren und vor die erste Zeile der Textdatei einfügen. Damit wird festgelegt, was Flare mit den nachfolgenden Auszeichnungen machen soll.
4. Aus dem Variablenset die letzte Zeile „</CatapultVariableSet>“ kopieren. Damit wird in guter XML-Manier die Auszeichnung wieder geschlossen.
5. Die Datei als *.flvar speichern und in Flare in den Ordner „VariableSets“ kopieren.

Jetzt müssen wir nur noch zur Kontrolle die Datei in Flare öffnen, um zu sehen, ob Flare damit einverstanden ist – möglicherweise enthält der Text (schwarz) Sonderzeichen, die nicht mit der XML-Definition kompatibel sind.

Diese Schritte muss man zwar für jede Sprache wiederholen, da sich die Begriffe im Interface jedoch nicht so oft ändern, ist die Häufigkeit eher gering. Und mit ein bisschen Übung auch in wenigen Minuten erledigt…

• 1
  XML ist eine Auszeichnungssprache, bei der die „Auszeichnungen“ (Tags) in spitzen Klammern den Begriff einrahmen und damit kennzeichnen, wo der Inhalt beginnt und wo er endet: „<h1>“ beispielsweise kennzeichnet den Beginn der Überschrift in der ersten Ebene, „</h1>“ kennzeichnet ihr Ende: „<h1>Überschrift der ersten Ebene</h1>“ zeigt beispuielsweise ein Browser als „Überschrift 1“ an. Das Aussehen des Textes lässt sich in einer anderen Datei bestimmen, dem „Stylesheet“. Das ist hier sehr vorteilhaft, da dadurch die Formatierung (das Aussehen) völlig unabhängig vom Inhalt definiert werden kann.