Damit die in unserer Software verwendeten Textausgaben korrekt in die Sprache des Anwenders übersetzt werden muss sichergestellt werden, dass sie von der Übersetzungssystematik (TextEx) als solche erkannt werden. Deshalb ist es zwingend notwendig die in diesem Dokument beschriebenen Regeln einzuhalten. Das heißt, es ist die Pflicht des Entwicklers jeden Text der durch einen Nutzer sichtbar wird durch eine der genannten Funktionen aufzubereiten.
Ein Allgemeine Beschreibung der Systematik findet sich hier (Übersetzen von Texten zur Laufzeit ).
Es gilt, dass alle Texte die über die genannten Funktionen aufbereitet werden als Zeichenkette (Literale) direkt übergeben werden müssen. Sie dürfen sich nicht aus Teilen zusammensetzen oder aus Variablen stammen. Der TextEx kann nämlich nur Literale erkennen.
Für Literale : AppHelper Format und Translate
Im Grunde gib es am Objekt AppHelper zwei unterschiedliche Funktionen, Format und Translate. Die beiden unterscheiden sich lediglich in der Angabe einer Formatierung mit Platzhaltern und sollten auch entsprechend für die vorgesehenen Fälle verwendet werden. Will man also eine Zeichenkette ohne jedliche Argumente übersetzen dann muss man Translate verwenden. Sollen aber Argumente in der Zeichenkette angegeben werden, dann muss Format verwendet werden.
In der Regel kommen die Funktionen mit dem Postfix Log zum Einsatz (FormatLog, TranslateLog). Sie liefern ein LogText-Objekt zurück das an vielen Stellen erforderlich ist (Fehlermeldungen, Logbuchausgaben und Hinweispopups).
Zu den genannten Funktionen gibt es auch ein statisches Äquivalent welches ein Text im Namen enthält (FormatText, TranslateText …). Diese können bei Nichtvorhandensein einer AppHelper-Instanz verwendet werden. Jedoch sind diese in der Regel eher selten notwendig.
Grundsätzlich geht es in der Verwendung darum, die Anzahl der verschiedenen Texte zu reduzieren, denn jeder dieser muss einmal übersetzt und kontrolliert werden. Dies stellt zusätzlich eine bessere Performance zur Laufzeit sicher. Deshalb ist es ratsam, Texte möglichst mit Platzhaltern zu versehen.
Prüfung des Inhalts (logische Verwendung)
Man darf niemals den Rückgabewert einer solchen Funktion vergleichen, da dieser nicht garantiert das ist was man erwartet. Auf den Kundensystemen vorort können eigene Übersetzungen und Ersetzungen gepflegt werden die jegliche Logikprüfung (die grundsätzlich an solcher Stelle eine sehr schlechte Idee ist) zunichte macht.
Übergabe von Variablen in der die Nachricht enthalten ist
Es kommt leider oft vor, das die eigentliche Nachricht zuerst in eine Stringvariable gepackt wird und diese dann in die Format oder Translate Funktion übergeben wird. Dies führt zwar zur Laufzeit trotzdem noch zu einer Übersetzung, jedoch kann der TextEx diese Stellen nicht erkennen und somit keine Übersetzung pflegen die vorher von uns geprüft wurde.
Keine Verwendung von Format-Strings
Sind in der Nachricht Werte enthalten, die sich verändern, so müssen diese als Platzhalter übergeben werden (Format) damit nicht jede einzelne Nachricht eine Übersetzung notwendig macht, nur weil sich eine Zahl geändert hat. Will man also eine Nachricht aus mehreren Teilen zusammen setzen so muss dies immer über die Format-Funktion passieren.
String.Format statt AppHelper.Format
Der Kardinalfehler der eine Übersetzung komplett verhindert.
Für dynamische Werte : SOGLogText.TranslateResource
Für dynamische Werte, damit sind alle Texte gemeint die nicht als Literal übergeben werden können, weil sie zum Beispiel aus einer Datei oder einem Datensatz stammen muss die Funtkion SOGLogText.TranslateResource verwendet werden.