Annotation of loncom/localize/lonlocal.pm, revision 1.24

1.1       www         1: # The LearningOnline Network with CAPA
                      2: # Localization routines
                      3: #
1.24    ! www         4: # $Id: lonlocal.pm,v 1.23 2003/10/10 16:56:16 www Exp $
1.1       www         5: #
                      6: # Copyright Michigan State University Board of Trustees
                      7: #
                      8: # This file is part of the LearningOnline Network with CAPA (LON-CAPA).
                      9: #
                     10: # LON-CAPA is free software; you can redistribute it and/or modify
                     11: # it under the terms of the GNU General Public License as published by
                     12: # the Free Software Foundation; either version 2 of the License, or
                     13: # (at your option) any later version.
                     14: #
                     15: # LON-CAPA is distributed in the hope that it will be useful,
                     16: # but WITHOUT ANY WARRANTY; without even the implied warranty of
                     17: # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
                     18: # GNU General Public License for more details.
                     19: #
                     20: # You should have received a copy of the GNU General Public License
                     21: # along with LON-CAPA; if not, write to the Free Software
                     22: # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
                     23: #
                     24: # /home/httpd/html/adm/gpl.txt
                     25: #
                     26: # http://www.lon-capa.org/
                     27: #
                     28: ######################################################################
                     29: ######################################################################
1.10      bowersj2   30: 
                     31: =pod
                     32: 
                     33: =head1 NAME
                     34: 
                     35: Apache::lonlocal - provides localization services
                     36: 
                     37: =head1 SYNOPSIS
                     38: 
                     39: lonlocal provides localization services for LON-CAPA programmers based
                     40: on Locale::Maketext. See
                     41: C<http://search.cpan.org/dist/Locale-Maketext/lib/Locale/Maketext.pod>
                     42: for more information on Maketext.
                     43: 
                     44: =head1 OVERVIEWX<internationalization>
                     45: 
                     46: As of LON-CAPA 1.1, we've started to localize LON-CAPA using the
                     47: Locale::Maketext module. Internationalization is the bulk of the work
                     48: right now (pre-1.1); localizing can be done anytime, and involves 
                     49: little or no programming.
                     50: 
                     51: The internationalization process involves putting a wrapper around
                     52: on-screen user messages and menus and turning them into keys,
                     53: which the MaketextX<Maketext> library translates into the desired
                     54: language output using a look-up table ("lexicon").X<lexicon>
                     55: 
                     56: As keys we are currently using the plain English messages, and
                     57: Maketext is configured to replace the message by its own key if no
                     58: translation is found. This makes it easy to phase in the
                     59: internationalization without disturbing the screen output.
                     60: 
                     61: Internationalization is somewhat tedious and effectively impossible
                     62: for a non-fluent speaker to perform, but is fairly easy to create
                     63: translations, requiring no programming skill. As a result, this is one
                     64: area where you can really help LON-CAPA out, even if you aren't a
                     65: programmer, and we'd really appreciate it.
                     66: 
                     67: =head1 How To Localize Handlers For Programmers
                     68: 
                     69: Into the "use" section of a module, we need to insert
                     70: 
                     71:  use Apache::lonlocal;
                     72: 
                     73: Note that there are B<no parentheses>, we B<want> to pollute our
                     74: namespace. 
                     75: 
                     76: Inside might be something like this
                     77: 
                     78:  sub message {
                     79:      my $status=shift;
                     80:      my $message='Status unknown';
                     81:      if ($status eq 'WON') {
                     82:         $message='You have won.';
                     83:      } elsif ($status eq 'LOST') {
                     84:         $message='You are a total looser.';
                     85:      }
                     86:      return $message;
                     87:  }
                     88:  ...
                     89:  $r->print('<h3>Gamble your Homework Points</h3>');
                     90:  ...
                     91:  $r->print(<<ENDMSG);
                     92:  <font size="1">Rules:</font>
                     93:  <font size="0">No purchase necessary. Illegal where not allowed.</font>
                     94:  ENDMSG
                     95: 
                     96: We have to now wrap the subroutine &mt()X<mt> ("maketext") around our 
                     97: messages, but not around markup, etc. We also want minimal disturbance. 
                     98: The first two examples are easy:
                     99: 
                    100:  sub message {
                    101:      my $status=shift;
                    102:      my $message='Status unknown';
                    103:      if ($status eq 'WON') {
                    104:         $message='You have won.';
                    105:      } elsif ($status eq 'LOST') {
                    106:         $message='You are a total looser.';
                    107:      }
                    108:      return &mt($message);
                    109:  }
                    110:  ...
                    111:  $r->print('<h3>'.&mt('Gamble your Homework Points').'</h3>');
                    112: 
                    113: The last one is a bummer, since you cannot call subroutines inside of 
                    114: (<<MARKER). I have written a little subroutine to generate a translated 
                    115: hash for that purpose:
                    116: 
                    117:  my %lt=&Apache::lonlocal::texthash('header' => 'Rules', 'disclaimer' => 
                    118:  'No purchase necessary. Illegal where not allowed.');
                    119:  $r->print(<<ENDMSG);
                    120:  <font size="1">$lt{'header'}:</font>
                    121:  <font size="0">$lt{'disclaimer'}</font>
                    122:  ENDMSG
                    123: 
                    124: As a programmer, your job is done here. If everything worked, you 
                    125: should see no changes on the screen.
                    126: 
                    127: =head1 How To Localize LON-CAPA for Translators
                    128: 
                    129: As a translator, you need to provide the lexicon for the keys, which in 
                    130: this case is the plain text message. The lexicons sit in 
                    131: loncom/localize/localize, with the language code as filename, for 
                    132: example de.pm for the German translation. The file then simply looks 
                    133: like this:
                    134: 
                    135:     'You have won.'
                    136:  => 'Sie haben gewonnen.',
                    137: 
                    138:     'You are a total looser.'
                    139:  => 'Sie sind der totale Verlierer.',
                    140: 
                    141:     'Rules'
                    142:  => 'Regeln',
                    143: 
                    144:     'No purchase necessary. Illegal where not allowed.'
                    145:  => 'Es ist erlaubt, einfach zu verlieren, und das ist Ihre Schuld.'
                    146: 
                    147: 
                    148: Comments may be added with the # symbol, which outside of a string
                    149: (the things with the apostrophe surrounding them, which are the 
                    150: keys and translations) will cause the translation routines to
                    151: ignore the rest of the line.
                    152: 
                    153: This is a relatively easy task, and any help is appreciated.
                    154: 
                    155: Maketext can do a whole lot more, see
                    156: C<http://search.cpan.org/dist/Locale-Maketext/lib/Locale/Maketext.pod>
                    157: but for most purposes, we do not have to mess with that.
                    158: 
                    159: =cut
1.1       www       160: 
                    161: package Apache::lonlocal;
                    162: 
                    163: use strict;
                    164: use Apache::localize;
1.3       www       165: use Apache::File;
1.14      www       166: use locale;
                    167: use POSIX qw(locale_h);
1.1       www       168: 
                    169: require Exporter;
                    170: 
                    171: our @ISA = qw (Exporter);
1.22      bowersj2  172: our @EXPORT = qw(mt mtn ns);
1.1       www       173: 
1.4       www       174: my $reroute;
                    175: 
1.1       www       176: # ========================================================= The language handle
                    177: 
                    178: use vars qw($lh);
                    179: 
                    180: # ===================================================== The "MakeText" function
                    181: 
                    182: sub mt (@) {
1.23      www       183: #    my $fh=Apache::File->new('>>/home/www/loncapa/loncom/localize/localize/newphrases.txt');
                    184: #    print $fh join('',@_)."\n";
                    185: #    $fh->close();
1.3       www       186:     unless ($ENV{'environment.translator'}) {
1.12      albertel  187: 	if ($lh) {
                    188: 	    return $lh->maketext(@_);
                    189: 	} else {
                    190: 	    return @_;
                    191: 	}
1.3       www       192:     } else {
1.12      albertel  193: 	if ($lh) {
                    194: 	    my $trans=$lh->maketext(@_);
                    195: 	    my $link='<a target="trans" href="/cgi-bin/translator.pl?arg1='.
                    196: 		&Apache::lonnet::escape($_[0]).'&arg2='.
                    197: 		&Apache::lonnet::escape($_[1]).'&arg3='.
                    198: 		&Apache::lonnet::escape($_[2]).'&lang='.
                    199: 		$ENV{'environment.translator'}.
                    200: 		'">[['.$trans.']]</a>';
                    201: 	    if ($ENV{'transreroute'}) {
                    202: 		$reroute.=$link;
                    203: 		return $trans;
                    204: 	    } else {
                    205: 		return $link;
                    206: 	    }
1.4       www       207: 	} else {
1.12      albertel  208: 	    return @_;
1.4       www       209: 	}
                    210:     }
                    211: }
                    212: 
1.24    ! www       213: # ================================================================ The <mt> tag
        !           214: 
        !           215: BEGIN {
        !           216: }
        !           217: 
        !           218: sub start_mt {
        !           219:     my ($target,$token,$tagstack,$parstack,$parser,$safeeval)=@_;
        !           220:     return &mt(&Apache::lonxml::get_all_text("/mt",$parser));
        !           221: }
        !           222: 
        !           223: sub end_mt {
        !           224:     return '';
        !           225: }
        !           226: 
1.6       www       227: # ============================================================== What language?
                    228: 
                    229: sub current_language {
1.20      albertel  230:     if ($lh) {
                    231: 	my $lang=$lh->maketext('language_code');
                    232: 	return ($lang eq 'language_code'?'en':$lang);
                    233:     }
1.21      www       234:     return 'en';
1.6       www       235: }
                    236: 
1.8       www       237: # ============================================================== What encoding?
                    238: 
                    239: sub current_encoding {
1.12      albertel  240:     if ($lh) {
                    241: 	my $enc=$lh->maketext('char_encoding');
                    242: 	return ($enc eq 'char_encoding'?'':$enc);
                    243:     } else {
                    244: 	return undef;
                    245:     }
1.8       www       246: }
                    247: 
1.15      www       248: # =============================================================== Which locale?
                    249: # Refer to locale -a
                    250: #
                    251: sub current_locale {
                    252:     if ($lh) {
                    253: 	my $enc=$lh->maketext('lang_locale');
                    254: 	return ($enc eq 'lang_locale'?'':$enc);
                    255:     } else {
                    256: 	return undef;
                    257:     }
                    258: }
                    259: 
1.4       www       260: # ============================================================== Translate hash
                    261: 
                    262: sub texthash {
                    263:     my %hash=@_;
                    264:     foreach (keys %hash) {
                    265: 	$hash{$_}=&mt($hash{$_});
                    266:     }
                    267:     return %hash;
                    268: }
1.5       www       269: # ======================================================== Re-route translation
                    270: 
                    271: sub clearreroutetrans {
                    272:     &reroutetrans();
                    273:     $reroute='';
                    274: }
1.4       www       275: 
                    276: # ======================================================== Re-route translation
                    277: 
                    278: sub reroutetrans {
                    279:     $ENV{'transreroute'}=1;
                    280: }
1.5       www       281: 
1.4       www       282: # ==================================================== End re-route translation
                    283: sub endreroutetrans {
                    284:     $ENV{'transreroute'}=0;
                    285:     if ($ENV{'environment.translator'}) {
                    286: 	return $reroute;
                    287:     } else {
                    288: 	return '';
1.3       www       289:     }
1.1       www       290: }
                    291: 
                    292: # ========= Get a handle (do not invoke in vain, leave this to access handlers)
                    293: 
                    294: sub get_language_handle {
1.9       www       295:     my $r=shift;
1.2       www       296:     $lh=Apache::localize->get_handle(&Apache::loncommon::preferred_languages);
1.12      albertel  297:     if (&Apache::lonnet::mod_perl_version == 1) {
                    298: 	$r->content_languages([&current_language()]);
1.8       www       299:     }
1.24    ! www       300:     &Apache::lonxml::register('Apache::lonlocal',('mt'));
1.16      www       301: ###    setlocale(LC_ALL,&current_locale);
1.18      www       302: }
                    303: 
                    304: # ========================================================== Localize localtime
                    305: 
                    306: sub locallocaltime {
                    307:     my $thistime=shift;
                    308:     if ((&current_language=~/^en/) || (!$lh)) {
                    309: 	return ''.localtime($thistime);
                    310:     } else {
                    311: 	my $format=$lh->maketext('date_locale');
                    312: 	if ($format eq 'date_locale') {
                    313: 	    return ''.localtime($thistime);
                    314: 	}
                    315: 	my ($seconds,$minutes,$twentyfour,$day,$mon,$year,$wday,$yday,$isdst)=
                    316: 	    localtime($thistime);
                    317: 	my $month=(split(/\,/,$lh->maketext('date_months')))[$mon];
                    318: 	my $weekday=(split(/\,/,$lh->maketext('date_days')))[$wday];
                    319: 	if ($seconds<10) {
                    320: 	    $seconds='0'.$seconds;
                    321: 	}
                    322: 	if ($minutes<10) {
                    323: 	    $minutes='0'.$minutes;
                    324: 	}
                    325: 	$year+=1900;
                    326: 	my $twelve=$twentyfour;
1.19      www       327: 	my $ampm;
1.18      www       328: 	if ($twelve>12) {
                    329: 	    $twelve-=12;
1.19      www       330: 	    $ampm=$lh->maketext('date_pm');
1.18      www       331: 	} else {
1.19      www       332: 	    $ampm=$lh->maketext('date_am');
1.18      www       333: 	}
                    334: 	foreach 
                    335: 	('seconds','minutes','twentyfour','twelve','day','year',
1.19      www       336: 	 'month','weekday','ampm') {
1.18      www       337: 	    $format=~s/\$$_/eval('$'.$_)/gse;
                    338: 	}
                    339: 	return $format;
                    340:     }
1.1       www       341: }
                    342: 
1.17      bowersj2  343: # ==================== Normalize string (reduce fragility in the lexicon files)
                    344: 
                    345: # This normalizes a string to reduce fragility in the lexicon files of
                    346: # huge messages (such as are used by the helper), and allow useful
                    347: # formatting: reduce all consecutive whitespace to a single space,
                    348: # and remove all HTML
                    349: sub normalize_string {
                    350:     my $s = shift;
                    351:     $s =~ s/\s+/ /g;
                    352:     $s =~ s/<[^>]+>//g;
1.22      bowersj2  353:     # Pop off beginning or ending spaces, which aren't good
                    354:     $s =~ s/^\s+//;
                    355:     $s =~ s/\s+$//;
1.17      bowersj2  356:     return $s;
                    357: }
1.22      bowersj2  358: 
                    359: # alias for normalize_string; recommend using it only in the lexicon
                    360: sub ns {
                    361:     return normalize_string(@_);
                    362: }
                    363: 
                    364: # mtn: call the mt function and the normalization function easily.
                    365: # Returns original non-normalized string if there was no translation
                    366: sub mtn (@) {
                    367:     my @args = @_; # don't want to modify caller's string; if we
                    368: 		   # didn't care about that we could set $_[0]
                    369: 		   # directly
                    370:     $args[0] = normalize_string($args[0]);
                    371:     my $translation = &mt(@args);
                    372:     if ($translation ne $args[0]) {
                    373: 	return $translation;
                    374:     } else {
                    375: 	return $_[0];
                    376:     }
                    377: }
                    378: 
1.1       www       379: 1;
                    380: 
                    381: __END__

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>