alryaz/php-i18n

Simple Internatonalization Component

Installs: 15

Dependents: 0

Watchers: 1

Forks: 27

Open Issues: 1

Language: PHP

v2.2.0 2014-04-21 15:00 UTC

README

This is a simple i18n class for PHP. Nothing fancy, but fast, because it uses caching and it is easy to use. Try it out!

Some of its features:

  • YAML and INI support, with PHP array support coming soon!
  • Composer-ready!
  • File caching
  • Flexible API
  • Built-in support for vsprintf formatting
  • Automatic finding out what language to use
  • Simplicity ;)

Requirements

  • Write permissions in cache directory
  • PHP 5.3.1 (works with this version and above, mainly because of Spyc loader that is used)
  • PHP SPL extension (installed by default)

Setup

To use the i18n class, look at the provided examples. You will find there a simple tutorial for this class in the file. Otherwise follow these easy five steps:

1. Require composer package

Add the following line to your composer.json file, in the require section:

"require": {
    ...
    "alryaz/php-i18n": "dev-master"
    ...
}

2. Create language files

To use this class, you have to use ini files for the translated strings. This could look like this:

lang_en.ini (English)

greeting = "Hello World!"

[category]
somethingother = "Something other..."

lang_de.ini (German)

greeting = "Hallo Welt!"

[category]
somethingother = "Etwas anderes..."

Save both files in the directory you will set in step 4. The files must be named like the filePath setting, where '{LANGUAGE}' will be replaced by the chosen language, e.g. 'en' or 'de'.

3. Initialize the class

<?php
    $i18n = new \I18n\I18n();
    ...
?>

4. Set some settings if necessary

The possible settings are:

  • Language file path (the ini files) (default: ./lang/lang_{LANGUAGE}.ini)
  • Cache file path (default: ./langcache/)
  • The fallback language, if no one of the user languages is available (default: en)
  • A forced language, if you want to force a language (default: none)
  • The section seperator: this is used to seperate the sections in the language class. If you set the seperator to _abc_ you could access your localized strings via $i18n->category_abc_name if you use categories in your ini. (default: _)
<?php
    $i18n = new \I18n\I18n();
    $i18n->setCachePath('./tmp/cache');
    $i18n->setFilePath('./langfiles/lang/lang_{LANGUAGE}.ini'); // language file path
    $i18n->setFallbackLang('en');
    $i18n->setForcedLang('en') // force english, even if another user language is available
    $i18n->setSectionSeperator('_');
    ...
?>
Shorthand

There is also a shorthand for that: you can set all settings in the constructor!

<?php
    $i18n = new \I18n\I18n('lang/lang_{LANGUAGE}.ini', 'langcache/', 'en');
    ...
?>

The (optional) parameters are:

  1. the language file path (the ini files)
  2. the language cache path
  3. fallback language

5. Call the init() method to load all files and translations

Call the init() file to instruct the class to load the needed language file, to load the cache file or generate it if it is not available and make the L class available so you can access your localizations.

<?php
    ...
    $i18n->init();
?>

6. Use the localizations

To call your localizations, use one of the following ways provided in the example below.

In this example, we use the translation string seen in step 1.

<?php

    // 1. Accessing variable;
    echo $i18n->greeting; // If 'en' is applied: 'Hello World'

    // 2. Accessing variable (non-static)
    echo $i18n->lastmodified('today'); // Could be: 'Last modified: today'

    // 3. Calling class method
    echo $i18n->t('greeting'); // If 'de' is applied: 'Hallo Welt!'

    // 4. Calling object directly
    echo $i18n('category_somethingother') // If 'en' is applied: 'Something other...'

?>

Every function will yield the same result, which will be formatted by a PHP function, vsprintf.

Thats it!

How it finds out the user language

This class tries to find out the user language by generating a queue of the following things:

  1. Forced language (if set)
  2. GET parameter 'lang' ($_GET['lang'])
  3. SESSION parameter 'lang' ($_SESSION['lang'])
  4. HTTP_ACCEPT_LANGUAGE (can be multiple languages) ($_SERVER['HTTP_ACCEPT_LANGUAGE'])
  5. Fallback language

First it will remove duplicate elements and then it will replace all characters that are not A-Z, a-z or 0-9. After that it searches for the language files. For example, if you set the GET parameter 'lang' to 'en' without a forced language set, the class would try to find the file lang/lang_en.ini (if the setting langFilePath was set to default (lang/lang_{LANGUAGE}.ini)). If this file was not there, it would try to find the language file for the language defined in the session and so on.

How to change this implementation

You can change this 'algorithm' by extending the i18n class. You could do it like that:

<?php
    class My_I18n extends \I18n\I18n {

        public function getUserLangs() {
            $userLangs = new array();

            $userLangs[] = $_GET['language'];

            $userLangs[] = $_SESSION['userlanguage'];

            return $userLangs;
        }

    }

    $i18n = new My_I18n();
    // [...]
?>

This very basic extension of the i18n class replaces the default implementation of the getUserLangs()-method and only uses the GET parameter 'language' and the session parameter 'userlanguage'. You see that this method must return an array.

Note that this example function is insecure: getUserLangs() also has to escape the results or else i18n will load every file!

Fork it!

Contributions are always welcome.