Class: I18n
I18n is a class that makes it easier to add multiple language support
to PHP programs. It is lightweight and not very sophisticated, attempting
to keep it straight-forward while emulating some of the more elegant features
of other internationalization systems, such as gettext.
Since I18n is simply PHP code, it is also cross-platform, which was the
reason for not using an implementation like gettext in the first place.
New in 1.2:
- Added a $charset property.
- Added a $fullname property.
New in 1.4:
- Added a $method property, which determines the method used to create the
$lang_hash keys.
- Added a list of vowels to the 'metaphone' serialization method, making it
more unique.
- Added an optional second parameter to the get() method, which if passed
an object, will know to call the global $tpl object on the string, allowing
substitutions to occur. Note: This requires a global $tpl template object
to be available.
New in 1.6:
- Added an 'old' method, so serialize() will create old-style keys, useful for
rebuilding language files from older versions.
- Added a build_keylist() method. See below for details.
New in 1.8:
- Added a $load_new parameter to the constructor method. See below for details.
New in 2.0:
- Added support for arrays, not just objects, as the second parameter to get().
- Added a getf() method, which uses the sprintf() function instead of
saf.Template to substitute values into strings.
New in 2.2:
- Improved the pattern matching in the build_keylist() method.
New in 2.4:
- Switched the sprintf() calls in getf() to vsprintf(), which simplified the
method and made it more flexible in the process.
- Added a getLanguages() method that retrieves a list of languages from an
XML file. The XML file must be of the format:
<languages>
<lang>
<name>English</name>
<charset>ISO-8859-1</charset>
</lang>
<lang>
<name>Russian</name>
Usage Example
en
Return to Top
Properties
$buffer
$error
If an error occurs during any portion of this class, this
will contain the message.
$root
$except
$extensions = array (
'php' => '_php', // php script
'tpl' => '_tpl', // xt template
'spt' => '_spt', // simple template
'settings' => '_settings', // form settings files
'db' => '_db', // list of database tables/fields to be translated
)
$language
The language code, corresponding to the name of the language
file.
$locale
The locale code, corresponding to the name of the country
to localize numbers and dates for.
$directory
The location of the language files.
$page
The name of the current page, which can be used in the language
file in a switch statement to keep the $lang_hash array shorter, instead
of loading more than is necessary.
$lang_hash = array ()
The language hash, a key/value list.
$load_new = false
Determines whether getIndex() should call include() or
include_once() to retrieve the language keys. Default is false,
which calls include_once().
$charset = 'iso-8859-1'
The charset of the current language, which can be used to tell
the browser, or any language-aware PHP functions, which to use.
$fullname = ''
The full name of language in use (ie. 'English' for 'en').
$method = 'metaphone'
The method to use to create the $lang_hash keys. Can be
'metaphone', 'md5', and 'plain'.
$fallbacks = array ()
Contains fallback text replacements.
$languages = array ()
2-D list of available languages, retrieved from getLanguages().
$cookieName = 'sitellite_lang_pref'
Return to Top
Methods
I18n ($directory = 'inc/lang', $negotiationMethod = 'html', $load_new = false)
Constructor Method. Includes the appropriate language file
in the provided $directory. This file is intended to fill out the
$lang_hash array. $load_new determines whether to call include()
or include_once(). True calls include(), so that multiple
language files may be opened. $negotiationMethod determines the
method whereby the language of choice is determined. See the
negotiate() method for more info on this.
setLocale ()
getIndex ()
get ($original = '', $obj = '', $isHtml = false)
- Access: public
- Return: string
Takes a string, serializes it to generate a key, and performs
a key/value lookup on the $lang_hash array. Returns the value found,
or the original string if not found. This is the method used in I18n
to return translated text. Optionally includes a second parameter, which
if included, tells I18n to use a global $tpl object to parse the current
string and feed it the specified object (or associative array). This
allows developers to make elements dynamic, and even re-order elements,
inside a language string.
getf ()
- Access: public
- Return: string
Takes a string, serializes it to generate a key, and performs
a key/value lookup on the $lang_hash array. Returns the value found,
or the original string if not found. This method is very similar to
the get() method, except instead of using saf.Template to insert values
into the string, it uses the vsprintf() function to fill in the values.
If you pass an array as the second value, it will use that instead of
however many additional arguments you fed it. This is a good thing,
because if you already have all your values in an array, you can
simply say get($original, $array) instead of getf($original, $array[0],
$array[1], $array[2]).
serialize ($string = '')
- Access: public
- Return: string
Generates a key for use in a key/value lookup on the $lang_hash
array. Uses the metaphone () of the first few words in the string, as
well as the length of the string to generate the key.
build_keylist ($basedir = '.', $except = false)
- Access: public
- Return: associative array
Generates an associative array of all the occurrences of ->get ('...'),
->getf ('...'), and [I18n: ...] in all files in the directory specified
(recursively). This essentially creates a serializeable keylist that can
be used as a point of reference for building language files.
getLanguage ($id, $langfile = 'inc/lang/languages.php')
- Access: public
- Return: object
Returns a single language node as an object, taken from the
specified languages.php file.
getLanguages ($langfile = 'inc/lang/languages.php')
- Access: public
- Return: array
Returns a 2-D array from the specified language file, which
is an INI file. Each section name in the file corresponds to a
different available language. Keys in each section include
'name', 'code', 'locale', 'charset', 'fallback', and 'default'.
negotiate ($method = 'http')
- Access: public
- Return: string
Returns the preferred language of the current visitor.
If the $method is 'http' then it uses the HTTP Accept-Language
string for this info. If the $method is 'cookie' it uses a
cookie (specified by the $cookieName property) to determine,
and if the $method is 'session' it relies on the global
$session object. Default is 'http'.
writeIndex ($file, $data)
writeLanguage ($file, $data, $code, $locale = '')
Return to Top