Class Translation

PEAR
   |
   --Translation

Classes extended from Translation:

Located in File: Program_Root/translation.class.0121.php


Translation class
Class allows to store and retrieve all the strings on multilingual site in the 
database.
Class connects to any database using PHP PEAR extension - so it needs 
PEAR to be installed to work correctly.
The object should be created for every page. While creation all the strings 
connected with specific page and the strings connected with all the pages 
on the site are loaded into variable, so access to them is quite fast and 
does not overload database server connection.
Reducing the DB connections by possibility to use the existing ones - the 
constructor right now needs the PEAR DB DSN to make the connection do 
the DB. The new version will allow user to use the existing DB connection 
(PEAR DB connection) instead of making the new one. To do so he just needs 
to pass to the constructor the handle for this connection instead of DSN.

Class Variable Summary
$ConnectionReused
Is true if the connection was reused, not made from the class
Default Value: -><-
$db
Connection to database
Default Value: -><-
$ErrorText
The string that will be displayed, if no string has been found in the DB for specified string_id
Default Value: -><-
$LanguageID
Language identifier
Default Value: -><-
$PageName
Page identifier
Default Value: -><-
$Strings
Strings of the given page array
Default Value: ->array()<-
$TableDefinitions
The array with table and column names
Default Value: -><-

Inherited Class Variable Summary

Inherited Method Summary

Method Summary
void constructor Translation ( $PageName, $LanguageID, $pear_DSN, [$CustomTables = 0] )
Class constructor
string getLangName ( )
Active language name retrieval
string getMetaTags ( )
META tags retrieval
array getOtherLangs ( )
Other languages retrieval
string gstr ( $StringName, [$Params = array()] )
Translated string retrieval
void _Translation ( )
Class destructor
Variable Detail

$ConnectionReused

Data type: int
Is true if the connection was reused, not made from the class


$db

Data type: DB
Connection to database


$ErrorText

Data type: string
The string that will be displayed, if no string has been found in the DB for specified string_id


$LanguageID

Data type: string
Language identifier


$PageName

Data type: string
Page identifier


$Strings

Data type: array
Strings of the given page array
This one is for fast access to cached strings for specified page

$TableDefinitions

Data type: array
The array with table and column names
The table may have following items:

'langsavail' - table, in which all the information of the possible languages 
is kept. This array item may be the string - then the structure of the table 
remains as original, but the name is specified here; or the array with the 
following items:
'name' - the name of the table - default is 'tr_langsavail'
'lang_id' - the column that stores the language identifier - default 
is 'lang_id'
'lang_name' - the column that stores the language name - default 
is 'name'
'metatags' - the column that stores meta tags for the pages in specified 
language - default is 'metatags'
'errortext' - the column that stores the text that will be displayed in case 
if some text will not be found in the DB - default is 'errortext'

'strings_XX' - table, in which the strings of language "XX" (the 
corresponding lang_id) are kept. This array item may be the string - then 
the structure of the table remains as original, but the name is specified 
here; or the array with the following items:
'name' - the name of the table - default is 'tr_strings_XX'
'page_id' - the page identifier - default is 'page_id'.
'string_id' - the string indetifier - default is 'string_id'.
'string' - the string itself - default is 'string'.

This parameter in fact has impact only if the DB is used as the strings 
repository. The defaults are set in the way that the method is compatible 
with lower versions.


Method Detail

constructor Translation

void constructor Translation ( $PageName, $LanguageID, $pear_DSN, [$CustomTables = 0] )

Class constructor

Function Parameters:
- string $PageName: the page identifier. It identifies strings connected with specific page on the site
- string $LanguageID: language id. All the languages are stored on the database on specific ID's.
- string $pear_DSN: This might be 3 types: the PEAR DSN string form making the connection; the PEAR DB connection handle; the string in the format: gettext://LOCALE:LANG:BINDTXTDOMAIN:TXTDOMAINFILE:TXTDOMAIN:CFGFILE for using the native PHP gettext support.
- array $CustomTables: This is the array of the names of the tables and optionally the names of columns. It contains the following elements:
Function Info:
Since - version 1.2.1

getLangName

string getLangName ( )

Active language name retrieval
Retrieves the name of active language
Function Parameters:
Function Info:
Return - current active language name or PEAR_ERROR object in case of problems

getMetaTags

string getMetaTags ( )

META tags retrieval
Retrievs the META tags that should be added on the top of translated page, so the translated characters will be correctly displayed on client's browser.
Function Parameters:
Function Info:
Return - with configured in DB META tags for selected language. In case of DB error - returns PEAR_ERROR object.

getOtherLangs

array getOtherLangs ( )

Other languages retrieval
Retrieves names of all other languages, not the active.
Function Parameters:
Function Info:
Return - 2-dimensional array (0..)('id', 'name') for all the languages defined in DB but the current selected one. In case of DB error - returns PEAR_ERROR object.

gstr

string gstr ( $StringName, [$Params = array()] )

Translated string retrieval
Retrieves the string basing on string identifier (string_id) or by 
page_id.string_id. It means the strings_id may be specified in 2 ways:
- as normal string_id - then the string is retrieved from the cached version
of strings in the current page_id
- as [page_id].[string_id] - then teh strings is retrieved from the DB by getting
it from the given page_id. The additional optimization mechanism checks
if the page_id is not the same, as the current - if it is - the string will still be
retrieved from the cached version.
Also in the Params array there can be the item 'lang_id'. If not 'action' has 
been given then the string from specified lang_id (in specified language) 
will be retrieved. This solution is not recommended for common usage 
(e.g. for the whole pages) as this will not use the cached in the constructor 
strings, but will make another query to the DB for the specified query.
Another item that can be this array is 'action'. This specified special 
actions that should be performed. The special actions can be the following:
'normal' - this is default setting. It means that method will act as if this 
item was not given.
'translate' - this will couse, that the $StringName will not be the 
string_id, but the string itself. This must be set only together with 
'lang_id' item. Method will try to find the specified string in the foreign 
(specified in lang_id) language and will retrieve the corresponding string in 
the current language. This solution is not recommended for common usage 
(e.g. for the whole pages) as this will not use the cached in the constructor 
strings, but will make another query to the DB for the specified query.
Item 'optimization' is used to specify the optimization of the queries - 
if the main load should be performed by the PHP server (by doing more, but 
less complicated queries) or DB server (PHP is sending only one, but 
complicated query). This one is used only together with specified 'lang_id' 
and 'action'=>'translate' - as this performs more operations, then other 
queries. It can have following values:
'php' - the default setting, cousing PHP to make 2 (or 3 if the string will 
be found in some other page_id then the current) uncomplicated queries. This 
is recommened if the DB server is the same machine as the PHP server.
'db' - this couses PHP to make only 1, but comlicated query. This is 
recommended if the DB server is separate machine, then PHP server. WARNING: 
This will not work with MySQL DB server and Db servers, that does not 
supports nested SELECTs (SELECT ... FROM ... WHERE sth = (SELECT...))
Function Parameters:
- string $StringName: string identifier - unique for the page as well as for the strings, that are available on all the pages.
- array $Params: string string may be parametrized - and the paraters, that will be "inserted" into string may be typen into this array. It means, that &&1&& string will be replaced by 1st array element; string &&2&& will be replaced by 2nd array element; string &&3&& will be replaced by 3rd array element etc.
Function Info:
Return - retrieved string

_Translation

void _Translation ( )

Class destructor

Function Parameters:
Function Info:
Since - version 1.2.1