The Language Files:

Basic concept

The language files are based on the well known INI file format.
This is because of the following facts: INI files can be modified/translated without additional knowledge or software requirements. Another fact is that INI files are simply readable with other programming languages, so if you got a "e;remote launcher"e; for your desktop based applications, eg in C you simple can fetch some values using the iniGetPrivateString() method.
Often I have seen that people are providing their various languages by simply including another php file with an array inner it - but this is not so secure, because of that the people providing language files can modify your applications by this or can make mistakes so that your application isn't working correctly. With INI files this all isn't possible.
Why not using XML? XML is appropriated to this as INI files are, but there is no need for the additional features privided by XML, so INI files are completely sufficient. Also the potential translater of your application has to know something about XML when he has to work with, using INI files he doesn't need any knowledge (Just how to use a text editor :P). Additional to this parsing XML files takes much more time than parsing INI files - So, why take the hammer if the nail fail does the same?

Nomination of the files

The names of the files are builded up from language codes as RFC 1766 recommends. For english as spoken in the USA, for example you can use en-US, for generall english just en. For english as spoken in Japan (Just a example!!) you may use en-JP. I hope you understand how it works. Self-Defined or phantasy languages may begin with an x, eg you would provide the language Borg, you could use x-Borg as language tag.
For more details on building the language tags, please see the RFC 1766.
The filename extension of language files is *.ini, so the english language file for the USA may be named "en-US.ini", the general english file "en.ini" and so on..
By precompiling the language files the file name extension is been transfered to *.lng.
If there are two files, one with the suffix *.ini and another with *.lng LanguageSys will prefer the precompiled *.lng file.

Structure of the langauge files

(Sorry, but at moment this part of the docs are not aviable in english. If you wrote a translation you can e-mail it to me: florian@phpws.org)
Die Language dateien (Nicht vorkompilierte!) sind im Stiel von Initialisierungsdateien (INI-Dateien) aufgebaut, jedoch müssen alle Werte in anführungszeichen (") geschrieben werden.
In Initialisierungsdateien werden einzelne Sektionen benannt, dannach werden unterhalb von diesen Sektionen werte zugewiesen, Sektionen werden durch eckige klammern ([ und ]) gekennzeichnet, zwischen diesen wird der name der Sektion geschrieben. Der Name der sektion ist Caseinsensitiv, was bedeutet das gross/kleinschreibung keine rolle spielt, jedoch sollte er immer klein geschrieben werden.
Werte werden zugewiesen, indem nach dem beginn einer Sektion eine zeichenfolge (regex: `/\w/i´) gefolgt von einem gleichheitszeichen (`=´) und dem Wert (Beliebige zeichenfolge (Ohne \r und \n) eingeschlossen in anführungszeichen).
Beispiel: [Section1]        ;Begin of the first section..
foo = "bar"       ;Sets the value of "foo" to "bar"
f_A z ="The BAZ";Sets the value of "f_a_z" to "The BAZ"
[Section2]        ;Begin of a second section..
foo= "bar"        ;Sets the value of "foo" to "bar"
empty=            ;"empty" is empty..
Hier sind auch gleich zwei weitere interessante features erkennbar, zum ersten werden hier in einer Zeile leerzeichen vor dem = benutzt, oder gar in dem string "f_A z" in zeile 3, werden jedoch alle gleich bewertet, das liegt daran, dass vor und nach dem = alle leerzeichen bis zum ersten anderen zeichen ignoriert werden. Das "f_A z" als "f_a_z" angesehen wird liegt an der behandlungsroutine, hier werden die leerzeichen automatisch durch unterstriche erstezt und alles wird kleingeschrieben (Caseinsensitive), dies ist nämlich vorraussetztung für das spätere verarbeiten als variable.
Das zweite interessante sind die Kommentare, kommentare werden mit ";" eingeleitet und können überall stehen. Sobald ausserhalb von zwei anführungszeichen (") ein ; auftauchtm wird der rest der zeile ignoriert. Wenn ";" das erste zeichen in einer Zeile ist, wird die ganze zeile so wie eine leere zeile ignoriert.

Zu beachten ist nun nurnoch, das Language-Dateien nur zwei sektionen nach werten durchsuchen, dass sind [info] und [lang].
Unter info könne werte die als informationen zu der Sprachdatei dienen festgelegt werden.
Im moment werden folgende werte unterstützt:

(Die werte sind alle Optional).
In der Sektion [lang] können beliebige werte zugewiesen werden, diese werden als späterer inhalt für die ausgabe der sprachinformationen verwendet.
Einige Beispiel Sprachdateien sind beim Download der Klasse enthalten.