Packages » Package i18n

Package i18n

Description:
This core package of the Freeform framework deals with internationalization of your web applications. Using this package you do not depend on different, often incomplete and non-cross-platform locale setups on different servers and operating systems for PHP5.

See also:

Authors:
  • Dennis Popel

Interfaces:
  • I18NCollation
    This interface represents a particular collation rule for a dialect. While most languages have one default collation, there are some languages that have many collations. In addition to that, this class provides an easy way to convert case of localized strings. For example, German letter Sharp S converts to double S in upper case.
  • I18NCountry
    This interface represents country-specific info such as intl and national currency code and symbol, currency decimal places, best dialect and time zone.
  • I18NDialect
    This interface represents a language dialect, or a variant - the most important piece of information about a language. It describes a concrete dialect, country of origin, possible collations, as well as it is used to format numbers, currency values and dates/times for this dialect. The formatting methods are rarely used directly, the client code should call respective methods of the I18NLocale object.
  • I18NLanguage
    This interface represents a family of language dialects. For example, there are 2 dialects of Norwegian or several dialects of Spanish. For example, in US English has changed to become what we call American English. This class encapsulates possible dialects under the same language. There always exists a special dialect, called Official, that is spoken in the country of the language origin. This class gives you access to the list of dialects. Languages are distinguished by the two-letter system codes.
  • I18NMessageDictionary
    This is the interface to message dictionaries. A message dictionary is an abstraction of a message translation facility. This interface declares just a single method, I18NMessageDictionary::translateMessage that will fetch localized message by its ID and target language/dialect code. Note that the dialect code is required; if the message for this dialect is not found, this will look up the Official dialect for the message translation. This package ships with the I18NMessageFile class that is an implementation of this interface and allows you to keep the translation infomation in ini-like files. Example
    Given the following message file:
     [en_Official]
     hello='Hello!'
     bye='Bye!'
     something='Oops!'
      [en_American]
     hello='Hi!'
     bye='So long!' 
              and the code:
    <?

     $mf     = new I18NMessageFile('/path/to/file');
         $s = $mf->translateMessage('hello', 'en', 'Official');
         // $s will contain 'Hello!'
         $s = $mf->translateMessage('hello', 'en', 'American');
         // $s will contain 'Hi!'
         $s = $mf->translateMessage('something', 'en', 'American');
         // $s will contain 'Oops!' as it will search the Official dialect
         $s = $mf->translateMessage('someotherthing', 'en', 'American', true);
         // will throw an exception
     
    ?>
  • I18NProvider
    This interface publishes methods that any i18n API provider must implement. i18n API privider's methods are called by the I18N class.

Classes:
  • I18N
    This class provides methods for accessing particular country, language, dialect, collation and locale objects. It interfaces with the concrete implementation of the Freeform I18N API (such as Free18n) and reroutes calls to its methods to this implementation. This is the main class you use to access different localization classes.
  • I18NException
    This is an empty exception class that is used by i18n
  • I18NLocale
    This is the central class in the i18n package. It provides access to locale-specific information and methods for a given combination of country and dialect information. You access instances of this class via a call to static I18N::getLocale() factory method. Then you call various formatting methods of this object to have your data formatted in a locale-specific way. Locales support translation of messages via the I18NMessageDictionary classes. Together with html you can create localizable templates for multilingual sites. Every locale object can have its own message dictionary and time zone. All date/time formattings will be performed on UNIX timestamps converted to the locale's time zone (see I18NLocale::setTimeZone() method), while all messages will be translated into the locale's dialect. The concrete implementations of the I18N API will likely use I18NCountry and I18NDialect classes to combine them into the locale object; all calls to the I18NLocale will be rerouted to the corresponding methods of the underlying objects (this is how the free18n package works)
  • I18NMessageFile
    This is an implementation of I18NMessageDictionary that uses an ini file for storing messages
  • I18NTimeZone
    This class represents a single time zone. A time zone has the following characteristics:
    • the offset from UTC in seconds during the standard (winter) time
    • the offset of daylight (summer time) that is added to the UTC offset to calculate the actual time in summer
    • the list of locations in this time zone
    • a possible intl abbreviation of the zone, like CET or EEST
    Also a timezone can be queried whether a particular UNIX timestamp is in winetr/summer time as well to convert a UNIX timestamp to a local time of the timezone.