inc/Translation.php

   1 <?php
   2 /**
   3 * Functions involved in translating with gettext
   4 * @package awl
   5 * @subpackage   Translation
   6 * @author    Andrew McMillan <andrew@mcmillan.net.nz>
   7 * @copyright Catalyst IT Ltd
   8 * @license   http://gnu.org/copyleft/gpl.html GNU GPL v2 or later
   9 */
  10
  11 if ( !function_exists('i18n') ) {
  12   /**
  13   * Mark a string as being internationalized.  This is a semaphore method; it
  14   * does nothing but it allows us to easily identify strings that require
  15   * translation.  Generally this is used to mark strings that will be stored
  16   * in the database (like descriptions of permissions).
  17   *
  18   * AWL uses GNU gettext for internationalization (i18n) and localization (l10n) of
  19   * text presented to the user. Gettext needs to know about all places involving strings,
  20   * that must be translated. Mark any place, where localization at runtime shall take place
  21   * by using the function translate().
  22   *
  23   * In the help I have used 'xlate' rather than 'translate' and 'x18n' rather than 'i18n'
  24   * so that the tools skip this particular file for translation :-)
  25   *
  26   * E.g. instead of:
  27   *   print 'TEST to be displayed in different languages';
  28   * use:
  29   *   print xlate('TEST to be displayed in different languages');
  30   * and you are all set for pure literals. The translation teams will receive that literal
  31   * string as a job to translate and will translate it (when the message is clear enough).
  32   * At runtime the message is then localized when printed.
  33   * The input string can contain a hint to assist translators:
  34   *   print xlate('TT <!-- abbreviation for Translation Test -->');
  35   * The hint portion of the string will not be printed.
  36   *
  37   * But consider this case:
  38   *   $message_to_be_localized = 'TEST to be displayed in different languages';
  39   *   print xlate($message_to_be_localized);
  40   *
  41   * The translate() function is called in the right place for runtime handling, but there
  42   * is no message at gettext preprocessing time to be given to the translation teams,
  43   * just a variable name. Translation of the variable name would break the code! So all
  44   * places potentially feeding this variable have to be marked to be given to translation
  45   * teams, but not translated at runtime!
  46   *
  47   * This method resolves all such cases. Simply mark the candidates:
  48   *   $message_to_be_localized = x18n('TEST to be displayed in different languages');
  49   *   print xlate($message_to_be_localized);
  50   *
  51   * @param string the value
  52   * @return string the same value
  53   */
  54   function i18n($value) {
  55     return $value;  /* Just pass the value through */
  56   }
  57 }
  58
  59
  60 if ( !function_exists('translate') ) {
  61   /**
  62   * Convert a string in English to whatever this user's locale is
  63   */
  64   if ( function_exists('gettext') ) {
  65     function translate( $en ) {
  66       if ( ! isset($en) || $en == '' ) return $en;
  67       $xl = gettext($en);
  68       dbg_error_log('I18N','Translated =%s= into =%s=', $en, $xl );
  69       return $xl;
  70     }
  71   }
  72   else {
  73     function translate( $en ) {
  74       return $en;
  75     }
  76   }
  77 }
  78
  79
  80 if ( !function_exists('init_gettext') ) {
  81   /**
  82   * Initialise our use of Gettext
  83   */
  84   function init_gettext( $domain, $location ) {
  85     if ( !function_exists('bindtextdomain') ) return;
  86     bindtextdomain( $domain, $location );
  87     $codeset = bind_textdomain_codeset( $domain, 'UTF-8' );
  88     textdomain( $domain );
  89     dbg_error_log('I18N','Bound domain =%s= to location =%s= using character set =%s=', $domain, $location, $codeset );
  90   }
  91 }
  92
  93
  94 if ( !function_exists('awl_set_locale') ) {
  95   /**
  96   * Set the translation to the user's locale.  At this stage all we do is
  97   * call the gettext function.
  98   */
  99   function awl_set_locale( $locale ) {
 100     global $c;
 101
 102     if ( !is_array($locale) && ! preg_match('/^[a-z]{2}(_[A-Z]{2})?\./', $locale ) ) {
 103       $locale = array( $locale, $locale.'.UTF-8');
 104     }
 105     if ( !function_exists('setlocale') ) {
 106       dbg_log_array('WARN','No "setlocale()" function?  PHP gettext support missing?' );
 107       return;
 108     }
 109     if ( $newlocale = setlocale( LC_ALL, $locale) ) {
 110       dbg_error_log('I18N','Set locale to =%s=', $newlocale );
 111       $c->current_locale = $newlocale;
 112     }
 113     else {
 114       dbg_log_array('I18N','Unsupported locale: ', $locale, false );
 115     }
 116   }
 117 }
 118