GermanUsersguide

Produktinterne Hilfe

Hier geht es um die Übersetzung der produktinternen Hilfe in der IDE, genannt users guide oder veraltet "online help" (online im Sinne von, während man "live" in der IDE arbeitet, nicht im Sinne von www).
Fragen, Bitten Anmerkungen bitte per Mail an:
Ruth(dot)Kusterer(at)sun(dot)com oder
recJake(at)googlemail(dot)com


Unterschiede zur normalen Lokalisierung

Bei der Übersetzung der Ressourcedateien wird der einfachste mögliche Weg gewählt, d.h. es wird die Originaldatei um "_de" erweitert und dadurch ist die Übersetzung verfügbar.
Im Userguide wäre dies auch möglich, allerdings wird dort aufgrund der Fülle der zu übersetzenden HTML-Dateien und der daraus resultierenden Unübersichtlichkeit ein anderer Weg beschritten: Für jede Sprache wird ein extra Verzeichnis angelegt.
Prinzipiell sieht es so aus:

translatedfiles\src\usersguide\javahelp\org\netbeans\modules\usersguide

Für die deutsche Übersetzung würde jetzt geschrieben werden

translatedfiles\src\usersguide\javahelp\org\netbeans\modules\usersguide\de

Dementsprechend sieht das Verzeichnis der Hilfe folgendermaßen aus:

...\usersguide\de
               |- accessibility
               |- ant
               |- ...
               |- webbrowser
               |- xml

Es gilt:

  • keine HTML-Dateien unter dem de-Verzeichnis bekommt ein "_de" angehängt
  • die Titel der HTML-Dateien sollten den Titel im Inhaltsverzeichnis tragen (siehe text-Tag der ide-toc.xml und "Übersetzung von Kapitelnamen")

Aufbau des Userguide

Einleitung

Die Hilfe in der IDE wird mit dem sogenannten JavaHelp System bewerkstelligt. Dies ist eine Software, die HTML Seiten in einer Java Applikation anzeigt. Nebenbei stellt sie Navigationselemente, wie Vor- und Zurückbuttons zur Verfügung, verwaltet Inhaltsverzeichnisse und Suchindizes.
In der NetBeans IDE besteht die Hilfe aus einem Standardteil und Spezialteilen. Der Standardteil beinhaltet all die Dinge, die man zum allgemeinen Arbeiten mit der IDE benötigt, z.B. wie funktionieren die Editoren, wie legt man welche Einstellungen fest und welche Auswirkung haben diese, usw. usf. Grundlegend stellt die Standardhilfe eine Beschreibung der Plattform dar.

Externer Aufbau

Für einen Benutzer sieht die Hilfe absolut einheitlich aus. Es gibt ein Inhaltverzeichnis, in dem alle wichtige Themen aufgelistet sind. Für einen Nutzer ist es also nicht zu sehen, wo die Hilfe herkommt und wie sie erstellt wird.

Interner Aufbau

Im Inneren der Hilfe sieht das ganz anders aus. Sie ist weder homogen, noch gibt es ein großes Paket, welches den gesamten Hilfetext enthält. Das ist auch weder vorgesehen, noch gewünscht.
Wie bereits in der Einleitung erwähnt existiert eine Standardhilfe und eine Spezialhilfen. Letztere werden normalerweise von den, die IDE erweiternden, Modulen geliefert, so z.B. JavaCVS oder das EnterprisePaket in NB5.5. Nichtsdestotrotz sind die Hilfen in beiden Fällen gleich aufgebaut:

Modulname\javahelp\

Innerhalb des "javahelp" Verzeichnisse befinden sich jetzt die HTML-Dateien und einige andere wichtige Dateien. Wenn ein Modul eine eigene Hilfe mitliefert wird diese automatisch in die Standardhilfe eingebunden und für den Nutzer sieht es wieder homogen aus.
Das bedeutet aber auch, daß sich die in der Hilfe sichtbare Struktur nicht unbedingt in der tatsächlichen Verzeichnisstruktur wiederspiegeln muß (siehe Abschnitt: "Verzeichnisse").

Spezielle Dateien

Es existieren mehrere spezielle Dateien für eine JavaHelp:
ide.hs
Enthält abstrakte Informationen über die Hilfe. Diese Datei muß teilweise übersetzt werden, aber in jedem Fall muss ihr das "_de" angehängt werden, da sie sich über dem "de"-Verzeichnis befindet.

ide-toc.xml
Wie das Kürzel schon sagt, handelt es sich hierbei um das Inhaltsverzeichnis. TOC-Dateien sind XML-Dateien mit einem speziellen Aufbau:
<tocitem text="Übersicht zu Projekten" target="proj_about" />
tocitem = Tag der besagt, daß jetzt ein Eintrag kommt
text = der Text, der im Index erscheint. Das ist NICHT automatisch der Seitentitel. Dieses Tag sollte in jedem Fall übersetzt werden.
target = ist in den meisten Fällen der Name der HTML-Datei, auf die dieser Indexeintrag verweist.
Wird das Schlüsselwort target nicht gesetzt, ist der Eintrag ein Überbegriff, der Unterkapitel enthält, aber keine eigene Seite in der Hilfe repräsentiert.

ide-idx.xml
Dies ist die Indexdatei. Sie muß übersetzt werden, um eine schnelle Indexsuche zu ermöglichen.
Ein Eintrag sieht folgendermßen aus:
<indexitem text="Output window and" target="ant_settings" />
Auch hier gilt:
text = der angezeigte Text und muß übersetzt werden. Hier sollte aber darauf geachtet werden, daß es mit dem Seitentitel oder einem Wort in der Seite übereinstimmt.
target = wie im Inhaltsverzeichnis, ist auch dies der Verweis auf die HTML-Datei und darf NICHT übersetzt werden.


Übersetzung von Kapitelnamen

Der Userguide setzt sich aus verschiedenen Kapiteln zusammen. Einige davon werden im Inhaltsverzeichnis aufgeführt, andere nur in Indizes und wieder andere sind nur über andere Seiten verlinkt. Nichtsdestotrotz sollten die Namen immer gleich sein, d.h. wenn eine Seite geöffnet wird, sollte die Überschrift genauso lauten, wie der Text an der Stelle, wo diese Seite verlinkt wurde (hier gibt es eine Ausnahme: Wenn eine Seite innerhalb von Text referenziert wird, kann im Sinne des besseren Textflußes und der besseren Lesbarkeit natürlich auch eine andere Wortwahl verwendet werden.
Um diese Homogenität zu erreichen gibt es zwei Dokumente:
Kapitelnamen des Inhaltsverzeichnisses: PDF, ODS(OpenOffice2.0-SpreadSheet)
Kapitelnamen, die nicht im Inhaltsverzeichnis erscheinen: PDF, ODS(OpenOffice2.0-SpreadSheet)

Bitte beachten: Dies sind "lebende" Dokumente! Bis zur offiziellen Veröffentlichung der deutschen Hilfe, können sich diese Dokumente immer mal wieder ändern, sei es wegen Korrekturen der Rechtschreibung oder auch wegen Umbenennung von Kapiteln.


Stil

Die übersetzung sollte im unpersönlichen Stil, also dritte Person Neutrum gehalten werden.
Dazu ein paar Beispiele:
Originalsatz: When creating Java applications you typically set up a single main project.
Übersetzung: Beim Anlegen einer Javaanwendung erzeugt man typischerweise ein einzelnes Hauptprojekt.

Originalsatz: When you build a project...
Übersetzung: Wenn man ein Projekt erzeugt...

Warum diese Art der Übersetzung? Wenn man eine perönliche Form wählt, muß man zuerst entscheiden, welche das sein wird, als formell (Sie) oder informell (Du). Schon an diesem Punkt scheiden sich die Geister. Viel schlimmer ist es aber für den Endbenutzer. Manch einer fühlt sich - salopp gesagt - auf den Schlips getreten, wenn er von einem Programm mit professionellem Anspruch, geduzt wird. Ein anderer Benutzer findet es aber befremdlich, von der IDE gesiezt zu werden.
Die unpersönlich Anrede ist dann der beste Mittelweg.
Im Englischen ist das weniger problematisch, da dort das "you" bekanntermaßen sowohl "Sie", als auch "Du" heißen kann. :(


Verzeichnisse

Wie bereits erwähnt, reflektiert sich die Sicht des Benutzers auf die Hilfe nicht unbedingt in der zugrunde liegenden Verzeichnisstruktur. Die folgende Tabelle enthält alle (Unter)Verzeichnisse der Standardhilfe im Projekt Translatedfiles und den jeweiligen Übersetzungsstatus (fertig, in Arbeit, noch nicht begonnen).
Aus dieser Tabelle kann sich jeder der möchte, ein oder mehrere Verzeichnisse wählen und diese übersetzen.
Bitte den Namen in eckigen Klammern eintragen, damit der Link zum Wikiprofil erzeugt wird :)

Verzeichnis Dateien(Status) Übersetzer
../ide_de.hs 1/1 JakeJ
ide-toc.xml 1/1 JakeJ
ide-idx.xml 0/1 JakeJ
accessibility 0/3 JakeJ
ant 11/11 JakeJ
beans 0/17  ???
compile 11/11 JakeJ
configure 0/24 JakeJ
configure/modules 0/6 JakeJ
configure/workspace 0/7 JakeJ
debug 0/24  ???
debug/CSH 0/27  ???
editing 22/22 JakeJ
editing/codecompletion 7/7 JakeJ
editing/configuring 6/6 JakeJ
editing/csh 6/6 JakeJ
editing/macros 5/5 JakeJ
files 12/12 JakeJ
getstart 3/3 JakeJ
gui 0/20  ???
gui/csh 0/9  ???
gui/layout_managers 0/5  ???
internationalize 0/15  ???
java 4/4 JakeJ
java/synchronizing 2/2 JakeJ
javadoc 0/7  ???
junit 0/9  ???
misc-general 0/1  ???
project 23/23 JakeJ
project/csh 27/27 JakeJ
propfiles 0/6  ???
refactor 0/18  ???
refactor/csh 0/16  ???
run 0/8  ???
shortcuts 7/7 JakeJ
webbrowser 0/9  ???
xml 0/9  ???
xml/catalog 0/5  ???
xm/css 0/4  ???
xml/dtd 0/4  ???
xml/samples 0/3  ???
xml/sax 0/2  ???
xml/schema 0/1  ???
xml/xsl 0/2  ???
Total 148/410 36,1%


Diese Tabelle spiegelt nicht den CVS-Stand wieder, sondern den Stand der Übersetzung.


Übereinstimmungssicherstellungsüberprüfungszeug (Frei nach Ruth Kusterer)

Vokabel/Wendung Übersetzung
See also Siehe auch
Legal Notices Rechtliche Hinweise
Wizard Assistent


Bei Problemen mit der Übersetzung sollte vor das zu übersetzende Wort der String !!!!! gesetzt werden. Das erleichtert die spätere Suche danach und eine eventuelle Korrektur der Übersetzung.


Umlaute

Umlaute benötigen, damit sie in jedem Browser und auf jedem Rechner und hier insbesondere in der Hilfe, korrekt angezeigt werden, ein spezielles Format in einer HTML-Datei. Entweder erzeugt der HTML-Editor dies automatisch beim Tippen (z.B. NVu tut dies) oder man muß die Umlaute von Hand ersetzen. Niemals sollte man aber das JDK-Tool native2ascii verwenden.
Folgende Ersetzungen sind für Umlaute vorgesehen
ä = &auml;
Ä = &Auml;
ü = &uuml;
Ü = &Uuml;
ö = &ouml;
Ö = &Ouml;
ß = &szlig;
Achtung:
a) Das Semikolon am Ende ist wichtig. Ohne wird die Zeichenkette nicht als solche erkannt.
b) Die Leerzeichen zwichen dem '&' und dem nächsten Zeichen müssen natürlich auch entfernt werden. (Die Darstellung läßt es leider nicht anders zu :( )


Hilfe und Hinweise

Test der Übersetzung

Es gibt verschiedene Wege sich die eigene Übersetzung live in der IDE anszusehen:
a) Erzeugen und Installieren als NBM (Achtung: Dieses Vorgehen kann zu Problemen mit Umlauten führen!)
b) Eine lokalisierte Test-IDE erzeugen

Unstimmigkeiten im englischen Original

An manchen Stellen der Hilfe existieren Einträge (speziell bei Optionen und Tastaturkürzeln), die sich so nicht in der IDE wiederspiegeln. Entweder weil der Eintrag nicht richtig dokumentiert ist oder weil die Dokumentation für diese Einträge keine Revision erfahren hat und daher auf alten NetBeans-Versionen beruht.
Ob ein Eintrag korrekt ist, oder die beschriebene Hilfe so überhaupt in der IDE funktioniert sollte auf jeden Fall geprüft werden. Wenn es absolut nicht funktioniert, sprich die Hilfe etwas beschreibt, das nicht existiert oder so nicht möglich ist, kann der ensprechende Textabschnitt korrigiert (auch gelöscht) werden!
In wenigen Fällen kann es auch sein, das Copy&Paste Fehler auftreten. Diese sollten überprüft und bei Bedarf korrigiert, bzw. gelöscht werden.

Stolpersteine

Wenn man sich eine Seite in einem normalen Browser ansieht, hat man manchmal Einträge die so aussehen:
In a you can use
Diese Konstellation (kein korrekter Satzbau - fehlendes Objekt - und die zwei Leerzeichen) gibt einen Hinweis darauf, daß im Quelltext der HTML-Datei noch etwas versteckt ist. Meist ist es folgender Eintrag:

<object classid="java:com.sun.java.help.impl.JHSecondaryViewer"> 
 <param name="content" value="./csh/glossary_freeform.html">
 <param name="viewerActivator" value="javax.help.LinkLabel">
 <param name="viewerStyle" value="javax.help.Popup">
 <param name="viewerSize" value="400,160">
 <param name="text" value="free-form projects"> 
 <param name="textFontSize" value="medium">
 <param name="textFontFamily" value="SansSerif">
 <param name="textFontStyle" value="italic">
 <param name="textFontWeight" value="bold">
 <param name="textColor" value="blue"> 
</object>

Interessant für die Übersetzung ist hier nur die Zeile:
<param name="text" value="free-form projects">
Man muß hier den Eintrag hinter value übersetzen.


Tippfehler

Hier eine Liste gern gemachter Tippfehler. Die passieren nunmal im Rausch des Tippens:)

Fehler Richtig
wei wie
Fesnter Fenster
dei die
ind er in der
ind ie in die
... ...


Bitte beim Gegenlesen, auf solche Dinge achten. Das erfordert einiges an Konzentration, da man (laut Linguistenforschung) schnell darüber hinwegliest, besonders, wenn man den Text schon zig Mal gelesen hat.


Spezielle Teile des Userguide

Wie weiter oben erwähnt, existieren im Userguide spezielle Hilfen für spezielle Module. Auf dieser Seite (im Bereich "Translation Scope"), finden sich die Module, welche eine eigene Hilfe mitbringen.
Im Normallfall findet sich auch die Hilfe für diese Module im Projekt "TranslatedFiles". Auch hier gilt, daß im Verzeichnis JavaHelp des Moduls ein Unterveichnis "de" angelegt werden muß.

Not logged in. Log in, Register

By use of this website, you agree to the NetBeans Policies and Terms of Use. © 2012, Oracle Corporation and/or its affiliates. Sponsored by Oracle logo