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: