README

A library for simple i18n management in PHP.

Installing

Include openclerk/i18n as a requirement in your project composer.json, and run composer update to install it into your project:

{
  "require": {
    "openclerk/i18n": "dev-master"
  }
}

Features

TODO

Using

I18n::addAvailableLocale(new FrenchLocale());   // implement your own Locale here

I18n::setLocale('fr');
echo t("hello");                  // returns 'bonjour'
echo I18n::getCurrentLocale();    // returns 'fr'

You can also listen to the i18n_missing_string event (with openclerk/events) to capture missing locale strings at runtime:

\Openclerk\Events::on('i18n_missing_string', function($data) {
  echo $data['locale'] . ": " . $data['key'];
});

echo t("missing string");   // prints "fr: missing string"

Providing i18n strings

One easy way to implement a Locale is simply to define it in a JSON file:

class FrenchLocale implements \Openclerk\Locale {

  function getKey() {
    return 'fr';
  }

  function getTitle() {
    return 'French' /* i18n */;
  }

  function load() {
    $json = json_decode(__DIR__ . "/fr.json", true /* assoc */);
    return $json;
  }

}

For speed, you could also define this as a PHP file require() instead.

Providing i18n strings across multiple components and projects

By using component-discovery along with translation-discovery, you can combine translation files across multiple projects and Composer dependencies at build time. For example:

abstract class DiscoveredLocale implements \Openclerk\Locale {

  function __construct($code, $file) {
    $this->code = $code;
    $this->file = $file;
  }

  function getKey() {
    return $this->code;
  }

  function load() {
    if (!file_exists($this->file)) {
      throw new \Openclerk\LocaleException("Could not find locale file for '" . $this->file . "'");
    }
    $result = array();
    require($this->file);
    return $result;
  }

}

class FrenchLocale extends DiscoveredLocale {

  public function __construct() {
    parent::__construct('fr', __DIR__ . "/../site/generated/translations/fr.php");
  }

}

\Openclerk\I18n::addAvailableLocales(DiscoveredComponents\Locales::getAllInstances());

(TODO: Add link to example project)

Persisting locale across sessions

When changing user locale, add a cookie:

setcookie('locale', $locale, time() + (60 * 60 * 24 * 365 * 10) /* 10 years in the future */);

And then check for this cookie as necessary:

if (isset($_COOKIE["locale"]) && in_array($_COOKIE["locale"], array_keys(I18n::getAvailableLocales()))) {
  I18n::setLocale($_COOKIE["locale"]);
}

Discovering translation strings

The soundasleep/translation-discovery project has a find script that can be used to search your project for translation strings that may need to be translated across all of your components.

This script will find all instances of the following translation strings, and output them to the template JSON folder:

1. t("string")
2. ht("string")
3. plural("string", 1) and plural("string", "strings", 1)
4. "string" /* i18n */
5. And the single-quote versions of these patterns