Lokalisierungs-Klasse

Localization base class

This small localiser base class uses a pattern system similar to the one known in Drupal. It is the frontend class that is called when something shall be translated, and uses two parameters:

1st parameter is a text that can contain placeholders for variable texts that are not part of the translation process.
2nd parameter is an associative array where these constant expressions are defined (keys) and with what they are replaced in the translated text (and untranslated text if no translation is found).

Take a look at the example to see how this translation pattern/placeholder system works. Its actually quite simple.

Different from Drupal, this class does not differ between the in-text constant replacement characters :, @ and ! are not interpreted. The placeholders are replaced exactly as the appear in the definition array.

You can implement any kind of translation system as backend. All you need to do is to overload the sw\Localizer class and initialize the frontend with your inherited class (Localizer::start(...)). What you must do to overload the protected method localize($text, $const). See example.

Diese kleine Localisierungs-Basisklasse verwendet ein System ähnlich dem bekannten Drupal-Überseter. Es ist eine Frontend-Klasse, die aufgerufen wird, wenn etwas übersetzt werden soll. Dabei werden zwei Parameter übergeben:

Ein Text, der ersetzt werden soll und Platzhalter enthalten kann, welche nicht mitübersetzt werden.
Ein assiziatives Array, in dem die Platzhalter (Keys) und deren Werte (array values) angegeben werden. Die Platzhalter werden nach dem Übersetzen im Text ersetzt (und auch im Originaltext, falls keine Übersetzung gefunden wurde).

Anders als bei Drupal beachtet diese Klasse die Platzhalter-Sonderzeichen :, @ und ! nicht. Was als die Keys im $const array werden wie sie sind durch ihre Werte ersetzt.

Du kannst Deine eigenes Übersetzungsbackend gestalten wie gewünscht - als PO-Datei, MySql Tabelle etc. Alles was getan werden muss, ist von dieser Basisklasse abzuleiten und die Methode localize($text, $const) zu überladen. Das Frontend muss natürlich davon informiert werden, dass diese neue Übersetzungsklasse verwendet werden soll, weshalb der Klassenname (Localizer::start(...)) übergeben wird. Ein Blick ins Beispiel macht diese Verwendung klar:

Sample source code

Anwendungsbeispiel

<?php
include_once('swlib/swlib.class.php');
 
use sw\Localizer;
use sw\FileSystem as fs;
 
/**
 * Our own localisation class derived from the Localizer:
 *
 */
class MyLocalizer extends sw\Localizer {
 
  /**
   * Here we keep our data in the example code. Translation table is defined as
   * key-value array, where the keys are the patterns to translate and the
   * values are associatove arrays containing 'language' => 'translated pattern'.
   *
   * @var array
   */
  private static $translationTable = array(
    'Welcome :name!' => array(
      'de' => 'Willkommen :name!'
    ),
    'Could not change directory to :dir: Does not exist.' => array(
      'de' => 'Konnte nicht ins Verzeichnis ":dir" wechseln weil es nicht existiert.'
    ),
    'Could not change directory to :dir: Not readable.' => array(
      'de' => 'Konnte nicht ins Verzeichnis ":dir" wechseln weil die Leserechte fehlen.'
    ),
    // etc etc etc
  );
 
  /**
   * This is how we initialize our localiser.
   *
   * @param string $language
   */
  public function __construct($language='') {
    parent::__construct($language);
    //
    // Open a PO file, connect to a database.
    //
  }
 
  /**
   * We overload this to specify how we localise. We can do this using any
   * kind of database, file, or fixed expressions in PHP. It's up to you.
   *
   * @param string $text
   * @param array $const
   */
  protected function localize($text, $const = array()) {
 
    // We just check if we know the pattern and if the language is implemented
    // and replace the pattern to give it back to the base class localize().
    if(isset(self::$translationTable[$text])) {
      if(isset(self::$translationTable[$text][$this->language()])) {
        $text = self::$translationTable[$text][$this->language()];
      }
    }
    // Let the base class replace the constants for us.
    return parent::localize($text, $const);
  }
}
 
////////////////////////////////////////////////////////////////////////////////
// Let's use our translation class:
////////////////////////////////////////////////////////////////////////////////
 
// Initialise the localiser with our class as translator. Do this at the
// beginning of your script. However, you can redo or change it whenever you
// want. The lib does not care.
Localizer::start("\MyLocalizer", 'en');
 
// We can change the language whenever we want as well.
Localizer::language('de');
 
//
// Lets use it. We have the text "Welcome :name!", where ":name" shall be a
// placeholder. Taking a look at the "translation table", we see that
// 'Welcome :name!' will be translated to 'Willkommen :name!'. After this
// the term ":name" will be replaced with "Rincewind". That's it already.
//
$text = 'Welcome :name!';
print "\n";
print "# Direct translation: \n";
print "  Pattern   : $text\n";
print "  Localized : " . Localizer::translate($text, array(':name' => 'Rincewind')) . "\n\n";
 
//
// Localized library exceptions:
//
print "# Localised library exceptions:\n";
print "  Command   : fs::chdir('/tmp/not-existing-directory');\n";
try {
  fs::chdir('/tmp/not-existing-directory');
} catch(\Exception $e) {
  print "  Exception : " . $e->getMessage() . "\n\n";
}
 
//
//  And all this again with the ungaught exception feature. All exceptions
//  of the library are localisable.
//
print "# Uncaught exception feature of swlib:\n";
fs::chdir('/tmp/not-existing-directory');

Output

Ausgabe

# Direct translation:
  Pattern   : Welcome :name!
  Localized : Willkommen Rincewind!

# Localised library exceptions:
  Command   : fs::chdir('/tmp/not-existing-directory');
  Exception : Konnte nicht ins Verzeichnis "/tmp/not-existing" wechseln weil es nicht existiert.

# Uncaught exception feature of swlib:

Uncaught Exception: 'Konnte nicht ins Verzeichnis "/tmp/not-existing" wechseln weil es nicht
existiert.' in .../sys/FileSystem.class.php[255] 

/.../localizer.test.php@92 sw\FileSystem::chdir("/tmp/not-existing")

Class source code

Klassen-Quelltext

<?php
 
/**
 * Base class for localization. Can be overloaded ( method localize() ) to
 * implement translations from different sources, e.g. database, po/pot file,
 * ini file etc. The implementation has to take into account that constants
 * can be defined in the text using an associative array, e.g.
 *
 * localize("Here is a :contant inside", array(':constant' => 'REPLACED CONSTANT'))
 *
 * Constants have to start with one of ":", "!" or "@". All replacements that
 * are not string or numeric will be ignored
 *
 * @gpackage de.atwillys.sw.php.swLib
 * @author Stefan Wilhelm
 * @copyright Stefan Wilhelm, 2005-2010
 * @license GPL
 * @version 1.0
 */
 
namespace sw;
 
class Localizer {
 
  /**
   * Language code definition, can be en-us, de-de etc.
   * @var string
   */
  protected $lang = '';
 
  /**
   * Stores the instance
   * @var Localizer
   */
  private static $instance = null;
 
  /**
   * Object's localization method
   * OVERLOAD THIS TO DEFINE YOUR LOCALIZER
   *
   * @param string $text
   * @param array $const
   */
  protected function localize($text, $const=array()) {
    if (empty($const)) {
      return $text;
    } else {
      return str_ireplace(array_keys($const), array_values($const), $text);
    }
  }
 
  /**
   * Constructor
   * @param string $language
   */
  public function __construct($language='') {
    $this->lang = trim($language);
  }
 
  /**
   * Returns and optionally sets the language code
   * @param string $lang=null
   * @return string
   */
  public static function language($lang=null) {
    if (!is_null($lang)) {
      self::$instance->lang = trim($lang);
    }
    $lang = strtolower(trim($lang));
    return self::$instance->lang;
  }
 
  /**
   * Initializes the localizer
   * @param mixed $localizer
   * @param string $language
   */
  public static final function start($localizer=null, $language='') {
    if (empty($localizer)) {
      self::$instance = new self();
    } else if (is_string($localizer)) {
      self::$instance = new $localizer(self::language($language));
    }
    if (!self::$instance instanceof self) {
      // Don't use translated exceptions here, there is no localizer yet
      throw new \Exception("Specified localization class is not derived from class Localizer");
    }
  }
 
  /**
   * Destroys the localizer instance
   */
  public static final function stop() {
    self::$instance = null;
  }
 
  /**
   * Returns the translated version of a text
   * @param string $text
   * @param array $const
   */
  public static final function translate($text, $const=array()) {
    if (empty($const)) {
      $const = array();
    } else {
      foreach ($const as $k => $v) {
        $const[$k] = (empty($k) || strpos(':!@', substr($k, 0, 1)) === false) ? null : print_r($v, true);
      }
      $const = array_filter($const, 'is_string');
    }
    if(!self::$instance) {
      return str_ireplace(array_keys($const), array_values($const), $text);
    } else {
      return self::$instance->localize($text, $const);
    }
  }
}

GIT repositories

Services

GNU octave web interface