1 <?php
 2 /**
 3  * Dynamically provide translatable entites for the {@link i18n} logic.
 4  * This is particularly handy for natural language strings in static variables
 5  * of a class definition, as the _t() method can only be used in a runtime/instance
 6  * context. The provideI18nEntities() method enables you to define your own entities
 7  * with your custom naming, mostly involving either the variable name or the array
 8  * key. With this in place, you can use a getter method to trigger translation
 9  * of your values.
10  * For any statics containing natural language, never use the static directly -
11  * always wrap it in a getter.
12  * 
13  * @package sapphire
14  * @subpackage i18n
15  * @uses i18nTextCollector->collectFromEntityProviders()
16  */
17 interface i18nEntityProvider {
18     
19     /**
20      * Example usage:
21      * <code>
22      * class MyTestClass implements i18nEntityProvider {
23      * function provideI18nEntities() {
24      *  $entities = array();
25      *  foreach($this->stat('my_static_array) as $key => $value) {
26      *      $entities["MyTestClass.my_static_array_{$key}"] = array(
27      *          $value,
28      *          PR_MEDIUM,
29      *          'My context description'
30      *      );
31      *  }
32      *  return $entities;
33      * }
34      * 
35      * static function my_static_array() {
36      *  $t_my_static_array = array();
37      *  foreach(self::$my_static_array as $k => $v) {
38      *      $t_my_static_array[$k] = _t("MyTestClass.my_static_array_{$key}", $v);
39      *  }
40      *  return $t_my_static_array;
41      * }
42      * }
43      * </code>
44      * 
45      * Example usage in {@link DataObject->provideI18nEntities()}.
46      * 
47      * You can ask textcollector to add the provided entity to a different module
48      * than the class is contained in by adding a 4th argument to the array:
49      * <code>
50      * class MyTestClass implements i18nEntityProvider {
51      * function provideI18nEntities() {
52      *  $entities = array();
53      *      $entities["MyOtherModuleClass.MYENTITY"] = array(
54      *          $value,
55      *          PR_MEDIUM,
56      *          'My context description',
57      *          'myothermodule'
58      *      );
59      *  }
60      *  return $entities;
61      * }
62      * </code>
63      * 
64      * @return array All entites in an associative array, with
65      * entity name as the key, and a numerical array of pseudo-arguments
66      * for _t() as a value.
67      */
68     function provideI18nEntities();
69 }
70 ?>