Overview

Packages

  • awl
    • AuthPlugin
    • AwlDatabase
    • Browser
    • classEditor
    • DataEntry
    • DataUpdate
    • EMail
    • iCalendar
    • MenuSet
    • PgQuery
    • Session
    • Translation
    • User
    • Utilities
    • Validation
    • vCalendar
    • vComponent
    • XMLDocument
    • XMLElement
  • None
  • PHP

Functions

  • awl_set_locale
  • i18n
  • init_gettext
  • Overview
  • Package
  • Function
  • Tree
  • Deprecated
  • Todo
  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: 
119: 
AWL API documentation generated by ApiGen 2.8.0