Erste Schritte in der Plugin-Entwicklung - Teil 3: Sprachfiles
Das Joomla! Plugin, das in Teil 1 und im Teil 2 dieser Serie "Erste Schritte in der Plugin-Entwicklung" erstellt wurde kann bisher leider nur eine Sprache? Was aber, wenn du dein Plugin auch Joomla!-Anwendern in anderen Ländern in verschieden Sprachen anbieten willst?
Momentan sind alle Texte in dem kleinen Plugin im Quelltext sofort eingefügt. Das hat zur Folge, dass Sprachanpassungen nur von jemandem erledigt werden können, der sich auch mit der Programmierung auskennt. Außerdem ist die Änderung recht aufwendig, da die Texte über das ganze Programm verteilt in verschiedenen Dateien verstreut sind.
Ideal wäre es, wenn die Sprachanpassungen zentral an einer Stelle in einer Textdatei erfolgen könnten! Das siehst du doch sicher auch so, oder? Also, dann los – in diesem Teil des Tutorials bauen wir das Plugin so um, dass alle Texte die angezeigt werden in einer Sprachdatei zusammengefasst werden. Falls du eine weitere Sprache unterstützen willst, musst du im Grunde genommen nun nur diese Datei übersetzen.
Was brauchst du?
Idealerweise hast du die ersten beiden Teile dieses Tutorials bearbeitet. Ausreichend ist es aber auch, wenn du grundsätzlich weißt, welche Typen von Erweiterungen es in Joomla! gibt und was genau ein Plugin ausmacht. Den in Teil 1 und Teil 2 erstellten Programmcode kannst du dir auch hier besorgen: Link zu Github.
Vielleicht magst du auch das Debuggen der Sprachdateien aktivieren. Das ist im Entwicklungsprozess sinnvoll, weil du so schnell siehst, ob du eine Übersetzung vergessen hast oder sich ein Tippfehler eingeschlichen hat. Du findest die Einstellung zum Aktivieren des Debuggens der Sprachdateien im Hauptmenü des Backends (Administrationsbereich) unter System | Globale Konfiguration im Register System.
Wenn du diese Einstellung aktivierst, werden alle Texte, die per Sprachdatei übersetzt werden können, in doppelten Hochsternen angezeigt. Fehlt eine Übersetzung stehen anstelle der Sterne Fragezeichen.
Sprachdateien zum Plugin hinzufügen
Ergänze die in Teil 2 erstellten Dateien coordstomap.xml um den in der folgenden Abbildung grün hervorgehobenen Text und lösche das Rote.
Als letztes legst du den Ordner Language an und erstellst hierin die aus der folgenden Abbildung ersichtlichen Unterordner und Dateien.
Alle Änderungen findest du übrigens auch bei Github. Die vollständigen Dateien kannst du dir hier ansehen.
ACHTUNG: Achte bei der Erstellung der Sprachtexte unbedingt auf Leerzeichen!
Der Eintrag
wird anders interpretiert als:
Was auch noch wichtig ist: Speichere die Sprachdateien immer unter dem Zeichensatz UTF8 ohne BOM (byte-order mark)!
Packe nun wieder die von dir erstellten Dateien in ein ZIP-Archiv, nenne dieses zum Beispiel plg_content_coordstomap_v1.2.0 und installiere es wie in Teil 1 über die Joomla! Installationsroutine.
Wie ich schon in Teil 1 und im Teil 2 erwähnte wird das Plugin dadurch, dass wir die Methode update in der XML-Datei gewählt haben, nicht ganz neu installiert sondern aktualisiert (und somit vorher deinstalliert), falls bei dir die Version 2 noch installiert ist! Bei einer Aktualisierung ist es nun so, dass, falls du den in Teil 2 angelegten Parameter „Quotes“ vor dem Update schon belegt hattest, diese Belegung nach der Aktualisierung immer noch vorhanden ist!
Parameterwerte die einmal gesetzt wurden, bleiben auch im Falle eines Updates erhalten. Nur bei einer Neuinstallation werden diese auf die Standardwerte gesetzt!
Namenskonventionen
Jede Sprachdatei ist mit einem Kürzel gekennzeichnet, welches in der ISO-639 und ISO-3166 festgelegt ist: Die ersten beiden Kleinbuchstaben benennen die Sprache. Für Deutsch wäre das
"de"
und
"en"
für Englisch.
Nach dem Bindestrich weisen die zwei Großbuchstaben auf das Land. So können die Besonderheiten im Schweizerdeutsch zum Beispiel über "CH" oder Österreichisch über "AT" vom "DE" abgegrenzt werden.
Ein Verzeichnis mit dem Namen
"de-CH"
enthält die Übersetzung für die Schweiz.
ACHTUNG: Das Verzeichnis en-GB sollte bei jeder Erweiterung immer mit den notwendigen Sprachdateien vorhanden sein. Joomla! wählt dieses Verzeichnis immer, wenn bei einer installierten Erweiterung keine Sprachdateien für die aktuell aktive Sprache zur Verfügung stehen. Wenn also ein Franzose dein Plugin - welches deutsche und englische Sprachdateien enthält - auf seinem Joomla! mit der Standardsprache Französisch installiert, werden die Texte in englischer Sprache angezeigt.
Das sollte dein Ergebnis sein!
Sofort nach der Installation wird dir in einer deutschen Joomla! Installation die Beschreibung in deutscher Sprache angezeigt.
Vielleicht hast du gemerkt, dass nach der Installation das Unterverzeichnis languages nicht ins Pluginverzeichnis kopiert wurde und fragst du dich nun, woher Joomla! den Beschreibungstext nimmt. Die Sprachdateien der Plugins findest du, wenn du die Installationsdatei (Manifestdatei) wie hier im Beispiel erstellt hast, im Verzeichnis DEINJOOMLA\administrator\language\de-DE\ - beziehungsweise im Verzeichnis DEINJOOMLA\administrator\language\en-GB\.
Falls es dir lieber ist, die Sprachdateien nur in dem Verzeichnis deiner Erweiterung zu speichern, kannst du dies auch tun. Wie du das tun kannst findest du hier.
Öffne nun im Backend das Menü Erweiterungen | Plugins und klicke dann auf den Namen deines Plugins, der hier nun auch aus den Sprachfiles geladen wird.
Es öffnet sich daraufhin ein Untermenü, in dem du Details zum Plugin ablesen kannst. Beachte, dass auch hier alle Texte aus deiner Sprachdatei gezogen werden.
Nun wunderst du dich, JNO und JYES hast du gar nicht in deine Sprachdatei aufgenommen. Diese werden aber in der Datei coordstomap.xml in Zeile 35 und 36 von dem Parameter genutzt.
Gut aufgepasst! Hier handelt es sich um eine Übersetzung, die du nicht selbst vornehmen musst. Das hat Joomla! für dich gemacht. Du kannst nämlich auf die globalen Sprachstrings von Joomla!, die du in der Datei DEINJOOMLA\administrator\language\de-DE\de-DE.ini - beziehungsweise E:\xamppa\htdocs\joomla3\administrator\language\en-GB\en-GB.ini - findest, zurückgreifen.
Interessiert dich, ob die englischen Sprachfiles auch richtig angezeigt werden? Dann wechsele im Backend ins Menü System | Kontrollzentrum und wähle links Sprachen aus.
Achte hier darauf, dass du die Sprache für den Administrator änderst und setze die Standardsprache auf englisch.
Nun werden dir im Backend alle Texte in englischer Sprache angezeigt. Wenn du im Menü Erweiterungen | Plugins auf den Namen deines Plugins klickst, kannst du überprüfen, ob auch deine englischen Sprachdateien fehlerfrei arbeiten.
Im Frontend unseres Plugins nutzen wir momentan noch keine Sprachstrings.
Deshalb ändert sich hier nichts. Falls dich interessiert, wie du in einer PHP Datei die Übersetzungen nutzen kannst, findest du dies hier.
Overrides
Und nun kommt das allerbeste: Dadurch, dass du Sprachdateien und Sprachstrings verwendest, kann ein Anwender deiner Erweiterung in Joomla! benutzerfreundlich selbst die Texte die er gerne ändern möchte, anpassen.
Wechsle, um dir diese Möglichkeit selbst anzusehen, im Backend wieder ins Menü System | Kontrollzentrum und wähle links nun Overrides aus. Wichtig ist, dass du nun links im Bereich Filter die richtige Option wählst. Klicke dann links oben auf die Schaltfläche „Neu“.
Falls dir der Sprachschlüssel, den ich für die Beschriftung des Parameterfeldes gewählt hatte zu lang ist, kannst du ihn hier abkürzen.
Gibt dazu einfach die Werte wie im nachfolgenden Bild ein und speichere diese.
Schön ist, dass du hier auch nach Sprachtexten oder Sprachtextschlüsseln suchen kannst. Wenn du den Wert einer Erweiterung (die du nicht selbst geschrieben hast) ändern willst, weißt du ja in der Regel nicht, in welcher Datei sich diese Übersetzung versteckt.
Und in der nächsten Abbildung kannst du nun sehen, dass der überschriebene Sprachstring auch tatsächlich bei der Anzeige verwendet wird.
Programmcode im Detail
coordstomap.xml
Sehen wir uns zunächst die neuen oder geänderten Zeilen der Datei coordstomap.xml im Einzelnen an.
- <name>Content - Coordinates to OSMMap</name>
+ <name>plg_content_coordstomap</name>Sprachstrings werden in der Regel in Großbuchstaben geschrieben. Eine Ausnahme ist der Name der Erweiterung in der Installationsdatei (Manifestdatei). Warum das so ist, habe ich einmal im Forum hinterfragt - mein Kollege würde sagen: "Historisch gewachsen" oder "Das war schon immer so" ...
- <version>1.1.0</version>
+ <version>1.2.0</version>Wie schon in Teil 2 empfehle ich dir die Versionsnummer des Plugins zu erhöhen. So kannst du später immer gut nachvollziehen, welche Funktion in welcher Version ergänzt wurde.
- <description>This plugin will replace gps coordinates with a link to osm. Requires Joomla 3.0 or greater.
- Don't forget to publish this plugin !</description>
+ <description>PLG_CONTENT_COORDSTOMAP_XML_DESCRIPTION</description>Anstelle des fest kodierten Textes, setzt du nun den Platzhalter in der Datei ein. Je nach Standard-Sprache wird später bei der Anzeige auf der Website der Text aus den Sprachdateien, die wir im nächstes Abschnitt ansehen werden, gezogen.
+ <languages>
+ <language tag="en-GB">language/en-GB/en-GB.plg_content_coordstomap.ini</language>
+ <language tag="en-GB">language/en-GB/en-GB.plg_content_coordstomap.sys.ini</language>
+ <language tag="de-DE">language/de-DE/de-DE.plg_content_coordstomap.ini</language>
+ <language tag="de-DE">language/de-DE/de-DE.plg_content_coordstomap.sys.ini</language>
+ </languages>Dieser neue Abschnitt teilt Joomla! bei der Installation mit, dass und welche Sprachdateien es gibt. Joomla legt diese dann in den Standardsprachverzeichnissen ab.
Sprachdateien
Für jede Sprache musst du zwei Dateien anlegen. Für die deutsche Sprache sind das zum Beispiel die Dateien
de-DE.plg_content_coordstomap.ini
und
de-DE.plg_content_coordstomap.sys.ini.
In jede der Dateien trägst du pro Zeile einen Sprachtextschlüssel und den dazugehörigen Text ein. Den Sprachtextschlüssel kannst du dir als eine Art Platzhalter vorstellen.
Sehen wir uns die Dateien für die Sprachen Deutsch und Englisch einmal an.
coordstomap3/language/de-DE/de-DE.plg_content_coordstomap.ini
PLG_CONTENT_COORDSTOMAP="Content - Koordinaten und OSMMap"
PLG_CONTENT_COORDSTOMAP_XML_DESCRIPTION="Dieses Plugin ergänzt GPS-Koordinaten in einem Beitrag mit einem Link zur passenden Position auf der OSM-Karte. Joomla 3.0 oder höher ist Voraussetzung. Das Plugin muss aktiviert werden!"
PLG_CONTENT_COORDSTOMAP_PARAMS_QUOTES_DESCRIPTION="Zum Beispiel, '50.244 7.2648' anstelle von 50,244 7.2648"
PLG_CONTENT_COORDSTOMAP_PARAMS_QUOTES_LABEL="Werden die Koordinaten in Anführungszeichen eingegeben?"
coordstomap3/language/de-DE/de-DE.plg_content_coordstomap.sys.ini
PLG_CONTENT_COORDSTOMAP="Content - Koordinaten und OSMMap"
PLG_CONTENT_COORDSTOMAP_XML_DESCRIPTION="Dieses Plugin ergänzt GPS-Koordinaten in einem Beitrag mit einem Link zur passenden Position auf der OSM-Karte. Joomla 3.0 oder höher ist Voraussetzung. Das Plugin muss aktiviert werden!"
coordstomap3/language/en-GB/en-GB.plg_content_coordstomap.ini
PLG_CONTENT_COORDSTOMAP="Content - Coordinates to OSMMap"
PLG_CONTENT_COORDSTOMAP_XML_DESCRIPTION="This plugin will replace gps coordinates with a link to osm. Requires Joomla 3.0 or greater. Don't forget to publish this plugin !"
PLG_CONTENT_COORDSTOMAP_PARAMS_QUOTES_DESCRIPTION="For example, '50.244 7.2648' instead of 50,244 7.2648"
PLG_CONTENT_COORDSTOMAP_PARAMS_QUOTES_LABEL="Are the coordinates provided with quotes."coordstomap3/language/en-GB/en-GB.plg_content_coordstomap.sys.ini
PLG_CONTENT_COORDSTOMAP="Content - Coordinates to OSMMap"
PLG_CONTENT_COORDSTOMAP_XML_DESCRIPTION="This plugin will replace gps coordinates with a link to osm. Requires Joomla 3.0 or greater. Don't forget to publish this plugin !"Theoretisch kannst du die Sprachstrings nennen wie du magst. Einfacher ist es aber, wenn du dich an Konventionen hältst. Beginne den String mit PLG um zu kennzeichnen, dass dieser String in einem Plugin verwendet wird. Als nächstes folgt hier im Beispiel der Text CONTENT, weil der String in einem Content Plugin eingesetzt wird. Der dritte Teil des Namens ist CORDSTOMAP – der Name deines Plugins. Und zum Schluss fügst du eine kurze Beschreibung an. So behältst du selbst die Übersicht, welcher String für was eingesetzt wird.
Sprachstrings dürfen nur aus alphanumerischen Zeichen, also Ziffern und Buchstaben bestehen. Das einzige erlaubte Sonderzeichen ist der Unterstrich. Leerzeichen sind nicht möglich.
Was musst du beim Anlegen der Sprachdatei beachten?
Zum einen ist es wichtig, dass pro Zeile nur ein Sprachstring eingetragen ist. An diesen schließt sich ein Gleichheitszeichen an. Hinter dem Gleichheitszeichen steht der Text in der jeweiligen Sprache. Dieser Text muss in Anführungszeichen stehen!
Warum benötigst du eigentlich zwei Sprachdateien pro Sprache?
Eine die mit .ini endet und eine die mit .sys.ini endet? Die Datei .sys.ini nutzt Joomla! zum Übersetzten des Namens der Erweiterung und der Beschreibung während der Installation. Außerdem benötigst du diese Datei zum Übersetzen der Texte im Menü des Backends (Administrationsbereich) und für die Anzeige in den verschiedenen Managern im Joomla!-Backend. Alle anderen Übersetzungen übernimmt die Datei .ini.
Achtung:
Obwohl du den Namen deiner Erweiterung und die Beschreibung ja schon in der Datei .sys.ini eingetragen hast, musst du diese Angaben auch in die .ini-Datei eintragen, da Joomla! diese Texte nach der Installation, zum Beispiel zur Anzeige im Backend, von hier nimmt. Mehr dazu findest du auch hier.
Was solltest du bei einem Plugin noch beachten?
Wir hatten hier noch keine Sprachtexte in der Plugin Datei selbst. Wenn du hier Sprachtexte einfügst, musst du noch eine Variable ergänzen. Der Eintrag protected $autoloadLanguage = true; lädt automatisch die richtigen Sprachdateien für dich. Es ruft die Funktion loadLanguage() der Klasse JPlugin auf.
Fazit
Du hast nun deine vielleicht erste Erweiterung für Jooma! fertiggestellt: Ein Plugin, dass automatisch Koordinaten in Hyperlinks zur OSM-Karte umwandelt. Du hast eine Menge über die XML-Installationsdatei oder Manifest Datei und auch ein paar PHP-Anweisungen kennen gelernt. Wir haben uns die verschieden Plugin-Typen angesehen und etwas über das Entwurfsmuster Observer erfahren. Du weißt nun, wie du ein Installationspaket erstellst und wie du dieses in Joomla! installierst.
Sollen wir als nächstes ein Modul erstellen?
