Konstantin S. Budylov 2005.
[email protected]
The given product is distributed according to a General Public License (GPL),
which you can find in a file GPL.txt in this package.
documentation Documentation
--------doc_RU.html russian
--------doc_EN.html english
languages Language files examples
--------russian.lang russian
--------english.lang english
cache The cache directory (for example script)
class.phpMultiLang.php class phpMultiLang declaration
example.php example script
GPL.txt GPL license text
CHANGES.txt List of changes and new features in this version
The class is intended for the organization of multilanguage support in web application.
Provides all basic necessary functionality for reception and a conclusion of the language data,
and some additional opportunities:
-As sources of the language data you can use of files and-or arrays.
-In case of use of files - processing of their any amount , and also caching results of processing is supported.
-Correct processing of files with magic_quotes_runtime == TRUE.
-Probably dynamic (i.e. after data processing) addition of the new language data from arrays.
-Probably dynamic change of already processed data.
-In the language data any HTML-marking is allowable.
-Probably dynamic formatting of the language data with use sprintf() modifiers.
Plus to all a class possesses the understandable interface, and is simple in use.
Use is very simple:
In the first, we include in the script a file of a class:
require "class.phpMultiLang.php";
Then, we do the same, that we do with the majority of classes, - create an object.
In the constructor we set the general directory for language files ( _LangRoot ), if we want use them - first argument.
Second argument is the directory for cache files ( _LangCachePath ).
Path must be absolute, or relative to CWD.
The specified directories should be existant, and readable, and _LangCachePath - also should be writeable.
If any from these conditions it is not executed, there will be generated an error, and value of a directory will be switched to CWD.
The CWD is also the default value for these parametres.
$Lang = new phpMultiLang('languages','cache');
Then it is necessary to set indexes and parameters of languages:
$Lang -> AssignLanguage('RU','ru');
$Lang -> AssignLanguage('EN',null,array('LC_ALL','en'));
The first argument of AssignLanguage() - is unique language index (string), on which further it will be identified.
The second (unessential) - path to a directory (relative _LangRoot), in which there should be files
for registered language.
The _LangRoot will be used by default.
The third argument is used if you want to set the locale for the given language configuration.
As the third parameter you should transfer the array, which zero element - is the NAME OF THE CONSTANT (in a string format ) for PHP function setlocale(), and element with index '1' - is the name of locale for same function (se the manual of setlocale() on a php.net).
If you want to set the locale adjustments, not specifying the language files directory,
set the second argument to
NULL.
If at the moment of a call
AssignLanguage() the directory for language is unknown, it is possible to set it later
by calling
SetLanguageDir(), transferred as parameters an index of language and a name of a directory.
For example:
$Lang -> SetLanguageDir('EN','en');
After that we specify where to take the necessary data.
For this purpose the method
AssignLanguageSource() is used.
As the first argument the index of language for which the data are added is transferred.
As the second - the name of a file (relative to directory specified for this language, and readable),
or an array, directly containing the language data.
$Lang -> AssignLanguageSource('RU','russian.lang',3600);
$Lang -> AssignLanguageSource('EN','english.lang',3600);
$Lang -> AssignLanguageSource('EN',array("some_index1"=>"Some string "));
$Lang -> AssignLanguageSource('EN',array("some_index2"=>"Some string with %smodifiers%s"));
The third parameter - is the cache expire value(in the seconds),
It is meaningful only at addition of a file and at use for the given language of a caching mode (it will be set in a
SetLanguage() method):
After we shall decide, what language is required to us,
we should initialize it, having transferred its index(What have set in
AssignLanguage),
as the first argument to
SetLanguage():
$Lang -> SetLanguage('EN', TRUE);
If the second argument is
TRUE, that is caching mode for the given language will be switched to ON (OFF by default).
At the moment of a call of this method, in case if locale adjustments for language have been set (see
AssignLanguage()), the
setlocale() will be called.
Everything, that now remained to us, to print the processed data.
It is made by a call of a method
GetString(),
As parameter for which it is necessary to transfer an index of the string necessary to us:
echo $Lang->GetString("some_index1");
echo $Lang->GetString("some_index2");
It will prints :
Some string
and
Some string with %smodifiers%s
Also there is an opportunity of additional formatting of a string,
wich contains the
sprintf-modifiers(the string with index "some_index2" in this example )
with use of a method
GetFString():
echo $Lang->GetFString("some_index2",array("<font color=#008080><b>","</b></font>"));
Prints:
Some string with modifiers
The first argument for
GetFString() is the string index.
Second - the array, contains the values for replacing by a
sprintf().
Values are processed in that order in which they are set in an array.
If modifiers in string appears less, than values in an array, superfluous values will be ignored.
If on the contrary, the modifier, corresponding value for which it is not found, comes back without changes.
One more opportunity which can be useful, dynamic change of a string.
For this purpose the method
GetStringReference() serves.
If to cause it in a similar way:
$d =&$Lang->GetStringReference('some_index1');
than $d will be the reference to a string with index "some_index1",
And by means of change $d it will be possible to change directly contents of a string "some_index1":
$d = "Changed string ";
echo $Lang->GetString("some_index1");
Prints: Changed string
At last, two more methods which can be useful:
-
GetLanguage() - Returns an index of the current active language.
and
-
GetLocale() - Returns current locale name,if it has been established.
The language file syntax
All the strings long in a language file should have the following format:
>Index (one or more spaces) 'String'
Index - sequence of symbols A-Z, 0-9, and _ (case insensitive)
String - single-quoted sequence of any symbols.
If the string should contains the 'single-quotes', they must be escaped with backslash: \'
Lines can contain any html marking.
The empty 'Strings' are not allowed.
In this version empty strings lead to some file processing errors.
In the next versions I shall try to correct it.
Another one.
I precisely did not check, but probably, everything, that does not get under a pattern of a 'string', will not processed in any way.
(it to a question on comments in a file).
In the next versions support of comments in files will be necessarily added.
Here, actually, the end.
Enjoy :)
Please, if you had any questions or wishes,
and also, if you will notice any discrepancies, or reticences in this documentation,
please, contact me
by this eMail .
Constructive criticism also with pleasure is accepted.
Table of contents