Return to lonlocal.pm CVS log

Up to [LON-CAPA] / loncom / localize

- Backport 1.59 (part).

    1: # The LearningOnline Network with CAPA
    2: # Localization routines
    3: #
    4: # $Id: lonlocal.pm,v 1.50.2.3 2010/02/12 14:20:41 raeburn Exp $
    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: ######################################################################
   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
  160: 
  161: package Apache::lonlocal;
  162: 
  163: use strict;
  164: use Apache::localize;
  165: use locale;
  166: use POSIX qw(locale_h strftime);
  167: use DateTime();
  168: use DateTime::TimeZone;
  169: use DateTime::Locale;
  170: 
  171: require Exporter;
  172: 
  173: our @ISA = qw (Exporter);
  174: our @EXPORT = qw(mt mtn ns mt_user);
  175: 
  176: # ========================================================= The language handle
  177: 
  178: use vars qw($lh);
  179: 
  180: # ===================================================== The "MakeText" function
  181: 
  182: sub mt (@) {
  183: #    open(LOG,'>>/home/www/loncapa/loncom/localize/localize/newphrases.txt');
  184: #    print LOG (@_[0]."\n");
  185: #    close(LOG);
  186:     if ($lh) {
  187:         if ($_[0] eq '') {
  188:             if (wantarray) {
  189:                 return @_;
  190:             } else {
  191:                 return $_[0];
  192:             }
  193:         } else {
  194:             return $lh->maketext(@_);
  195:         }
  196:     } else {
  197: 	if (wantarray) {
  198: 	    return @_;
  199: 	} else {
  200: 	    return $_[0];
  201: 	}
  202:     }
  203: }
  204: 
  205: sub mt_user {
  206:     my ($user_lh,@what) = @_;
  207:     if ($user_lh) {
  208:         if ($what[0] eq '') {
  209:             if (wantarray) {
  210:                 return @what;
  211:             } else {
  212:                 return $what[0];
  213:             }
  214:         } else {
  215:             return $user_lh->maketext(@what);
  216:         }
  217:     } else {
  218:         if (wantarray) {
  219:             return @what;
  220:         } else {
  221:             return $what[0];
  222:         }
  223:     }
  224: }
  225: 
  226: # ============================================================== What language?
  227: 
  228: sub current_language {
  229:     if ($lh) {
  230: 	my $lang=$lh->maketext('language_code');
  231: 	return ($lang eq 'language_code'?'en':$lang);
  232:     }
  233:     return 'en';
  234: }
  235: 
  236: sub preferred_languages {
  237:     my @languages=();
  238:     if (($Apache::lonnet::env{'request.role.adv'}) && ($Apache::lonnet::env{'form.languages'})) {
  239:         @languages=(@languages,split(/\s*(\,|\;|\:)\s*/,$Apache::lonnet::env{'form.languages'}));
  240:     }
  241:     if ($Apache::lonnet::env{'course.'.$Apache::lonnet::env{'request.course.id'}.'.languages'}) {
  242:         @languages=(@languages,split(/\s*(\,|\;|\:)\s*/,
  243:                  $Apache::lonnet::env{'course.'.$Apache::lonnet::env{'request.course.id'}.'.languages'}));
  244:     }
  245: 
  246:     if ($Apache::lonnet::env{'environment.languages'}) {
  247:         @languages=(@languages,
  248:                     split(/\s*(\,|\;|\:)\s*/,$Apache::lonnet::env{'environment.languages'}));
  249:     }
  250:     my $browser=$ENV{'HTTP_ACCEPT_LANGUAGE'};
  251:     if ($browser) {
  252:         my @browser =
  253:             map { (split(/\s*;\s*/,$_))[0] } (split(/\s*,\s*/,$browser));
  254:         push(@languages,@browser);
  255:     }
  256: 
  257:     foreach my $domtype ($Apache::lonnet::env{'user.domain'},$Apache::lonnet::env{'request.role.domain'},
  258:                          $Apache::lonnet::perlvar{'lonDefDomain'}) {
  259:         if ($domtype ne '') {
  260:             my %domdefs = &Apache::lonnet::get_domain_defaults($domtype);
  261:             if ($domdefs{'lang_def'} ne '') {
  262:                 push(@languages,$domdefs{'lang_def'});
  263:             }
  264:         }
  265:     }
  266:     return &get_genlanguages(@languages);
  267: }
  268: 
  269: sub get_genlanguages {
  270:     my (@languages) = @_;
  271: # turn "en-ca" into "en-ca,en"
  272:     my @genlanguages;
  273:     foreach my $lang (@languages) {
  274:         unless ($lang=~/\w/) { next; }
  275:         push(@genlanguages,$lang);
  276:         if ($lang=~/(\-|\_)/) {
  277:             push(@genlanguages,(split(/(\-|\_)/,$lang))[0]);
  278:         }
  279:     }
  280:     #uniqueify the languages list
  281:     my %count;
  282:     @genlanguages = map { $count{$_}++ == 0 ? $_ : () } @genlanguages;
  283:     return @genlanguages;
  284: }
  285: 
  286: # ============================================================== What encoding?
  287: 
  288: sub current_encoding {
  289:     my $default='UTF-8';
  290:     if ($Apache::lonnet::env{'browser.os'} eq 'win' && 
  291: 	$Apache::lonnet::env{'browser.type'} eq 'explorer') {
  292:         $default='ISO-8859-1';
  293:     }
  294:     if ($lh) {
  295: 	my $enc=$lh->maketext('char_encoding');
  296: 	return ($enc eq 'char_encoding'?$default:$enc);
  297:     } else {
  298: 	return $default;
  299:     }
  300: }
  301: 
  302: # =============================================================== Which locale?
  303: # Refer to locale -a
  304: #
  305: sub current_locale {
  306:     if ($lh) {
  307: 	my $enc=$lh->maketext('lang_locale');
  308: 	return ($enc eq 'lang_locale'?'':$enc);
  309:     } else {
  310: 	return undef;
  311:     }
  312: }
  313: 
  314: # ============================================================== Translate hash
  315: 
  316: sub texthash {
  317:     my %hash=@_;
  318:     foreach (keys %hash) {
  319: 	$hash{$_}=&mt($hash{$_});
  320:     }
  321:     return %hash;
  322: }
  323: 
  324: # ========= Get a handle (do not invoke in vain, leave this to access handlers)
  325: 
  326: sub get_language_handle {
  327:     my $r=shift;
  328:     if ($r) {
  329: 	my $headers=$r->headers_in;
  330: 	$ENV{'HTTP_ACCEPT_LANGUAGE'}=$headers->{'Accept-language'};
  331:     }
  332:     my @languages=&preferred_languages();
  333:     $ENV{'HTTP_ACCEPT_LANGUAGE'}='';
  334:     $lh=Apache::localize->get_handle(@languages);
  335:     if ($r) {
  336: 	$r->content_languages([&current_language()]);
  337:     }
  338: ###    setlocale(LC_ALL,&current_locale);
  339: }
  340: 
  341: # ========================================================== Localize localtime
  342: sub gettimezone {
  343:     my ($timezone) = @_;
  344:     if ($timezone ne '') {
  345:         if (!DateTime::TimeZone->is_valid_name($timezone)) {
  346:             $timezone = 'local';
  347:         }
  348:         return $timezone;
  349:     }
  350:     my $cid = $Apache::lonnet::env{'request.course.id'};
  351:     if ($cid ne '') {
  352:         if ($Apache::lonnet::env{'course.'.$cid.'.timezone'}) {
  353:             $timezone = $Apache::lonnet::env{'course.'.$cid.'.timezone'};
  354:         } else {
  355:             my $cdom = $Apache::lonnet::env{'course.'.$cid.'.domain'};
  356:             if ($cdom ne '') {
  357:                 my %domdefaults = &Apache::lonnet::get_domain_defaults($cdom);
  358:                 if ($domdefaults{'timezone_def'} ne '') {
  359:                     $timezone = $domdefaults{'timezone_def'};
  360:                 }
  361:             }
  362:         }
  363:     } elsif ($Apache::lonnet::env{'request.role.domain'} ne '') {
  364:         my %uroledomdefs = 
  365:             &Apache::lonnet::get_domain_defaults($Apache::lonnet::env{'request.role.domain'});
  366:         if ($uroledomdefs{'timezone_def'} ne '') {
  367:             $timezone = $uroledomdefs{'timezone_def'};
  368:         }
  369:     } elsif ($Apache::lonnet::env{'user.domain'} ne '') {
  370:         my %udomdefaults = 
  371:             &Apache::lonnet::get_domain_defaults($Apache::lonnet::env{'user.domain'});
  372:         if ($udomdefaults{'timezone_def'} ne '') {
  373:             $timezone = $udomdefaults{'timezone_def'};
  374:         }
  375:     }
  376:     if ($timezone ne '') {
  377:         if (DateTime::TimeZone->is_valid_name($timezone)) {
  378:             return $timezone;
  379:         }
  380:     }
  381:     return 'local';
  382: }
  383: 
  384: sub locallocaltime {
  385:     my ($thistime,$timezone) = @_;
  386:     if (!defined($thistime) || $thistime eq '') {
  387: 	return &mt('Never');
  388:     }
  389:     if (($thistime < 0) || ($thistime eq 'NaN')) {
  390:         &Apache::lonnet::logthis("Unexpected time (negative or NaN) '$thistime' passed to lonlocal::locallocaltime");  
  391:         return &mt('Never');
  392:     }
  393:     if ($thistime !~ /^\d+$/) {
  394:         &Apache::lonnet::logthis("Unexpected non-numeric time '$thistime' passed to lonlocal::locallocaltime");
  395:         return &mt('Never');
  396:     }
  397: 
  398:     my $dt = DateTime->from_epoch(epoch => $thistime)
  399:                      ->set_time_zone(&gettimezone($timezone));
  400: 
  401:     # TimeZone tries to determine the 'local' timezone from $ENV{TZ} if this
  402:     # fails it searches through various system files. Under certain
  403:     # circumstances this is an extremly expensive operation.
  404:     # So after the first run we store the timezone in $ENV{TZ} to significantly
  405:     # speed up future lookups.
  406:     $ENV{TZ} = $dt->time_zone()->name()
  407:         if (! $ENV{TZ} && gettimezone($timezone) eq 'local');
  408: 
  409:     if ((&current_language=~/^en/) || (!$lh)) {
  410: 
  411: 	return $dt->strftime("%a %b %e %I:%M:%S %P %Y (%Z)");
  412:     } else {
  413: 	my $format=$lh->maketext('date_locale');
  414: 	if ($format eq 'date_locale') {
  415: 	    return $dt->strftime("%a %b %e %I:%M:%S %P %Y (%Z)");
  416: 	}
  417: 	my $time_zone  = $dt->time_zone_short_name();
  418: 	my $seconds    = $dt->second();
  419: 	my $minutes    = $dt->minute();
  420: 	my $twentyfour = $dt->hour();
  421: 	my $day        = $dt->day_of_month();
  422: 	my $mon        = $dt->month()-1;
  423: 	my $year       = $dt->year();
  424: 	my $wday       = $dt->wday();
  425:         if ($wday==7) { $wday=0; }
  426: 	my $month  =(split(/\,/,$lh->maketext('date_months')))[$mon];
  427: 	my $weekday=(split(/\,/,$lh->maketext('date_days')))[$wday];
  428: 	if ($seconds<10) {
  429: 	    $seconds='0'.$seconds;
  430: 	}
  431: 	if ($minutes<10) {
  432: 	    $minutes='0'.$minutes;
  433: 	}
  434: 	my $twelve=$twentyfour;
  435: 	my $ampm;
  436: 	if ($twelve>12) {
  437: 	    $twelve-=12;
  438: 	    $ampm=$lh->maketext('date_pm');
  439: 	} else {
  440: 	    $ampm=$lh->maketext('date_am');
  441: 	}
  442: 	foreach ('seconds','minutes','twentyfour','twelve','day','year',
  443: 		 'month','weekday','ampm') {
  444: 	    $format=~s/\$$_/eval('$'.$_)/gse;
  445: 	}
  446: 	return $format." ($time_zone)";
  447:     }
  448: }
  449: 
  450: sub getdatelocale {
  451:     my ($datelocale,$locale_obj);
  452:     if ($Apache::lonnet::env{'course.'.$Apache::lonnet::env{'request.course.id'}.'.datelocale'}) {
  453:         $datelocale = $Apache::lonnet::env{'course.'.$Apache::lonnet::env{'request.course.id'}.'.datelocale'};
  454:     } elsif ($Apache::lonnet::env{'request.course.id'} ne '') {
  455:         my $cdom = $Apache::lonnet::env{'course.'.$Apache::lonnet::env{'request.course.id'}.'.domain'};
  456:         if ($cdom ne '') {
  457:             my %domdefaults = &Apache::lonnet::get_domain_defaults($cdom);
  458:             if ($domdefaults{'datelocale_def'} ne '') {
  459:                 $datelocale = $domdefaults{'datelocale_def'};
  460:             }
  461:         }
  462:     } elsif ($Apache::lonnet::env{'user.domain'} ne '') {
  463:         my %udomdefaults = &Apache::lonnet::get_domain_defaults($Apache::lonnet::env{'user.domain'});
  464:         if ($udomdefaults{'datelocale_def'} ne '') {
  465:             $datelocale = $udomdefaults{'datelocale_def'};
  466:         }
  467:     }
  468:     if ($datelocale ne '') {
  469:         eval {
  470:             $locale_obj = DateTime::Locale->load($datelocale);
  471:         };
  472:         if (!$@) {
  473:             if ($locale_obj->id() eq $datelocale) {
  474:                 return $locale_obj;
  475:             }
  476:         }
  477:     }
  478:     return $locale_obj;
  479: }
  480: 
  481: 
  482: # ==================== Normalize string (reduce fragility in the lexicon files)
  483: 
  484: # This normalizes a string to reduce fragility in the lexicon files of
  485: # huge messages (such as are used by the helper), and allow useful
  486: # formatting: reduce all consecutive whitespace to a single space,
  487: # and remove all HTML
  488: sub normalize_string {
  489:     my $s = shift;
  490:     $s =~ s/\s+/ /g;
  491:     $s =~ s/<[^>]+>//g;
  492:     # Pop off beginning or ending spaces, which aren't good
  493:     $s =~ s/^\s+//;
  494:     $s =~ s/\s+$//;
  495:     return $s;
  496: }
  497: 
  498: # alias for normalize_string; recommend using it only in the lexicon
  499: sub ns {
  500:     return normalize_string(@_);
  501: }
  502: 
  503: # mtn: call the mt function and the normalization function easily.
  504: # Returns original non-normalized string if there was no translation
  505: sub mtn (@) {
  506:     my @args = @_; # don't want to modify caller's string; if we
  507: 		   # didn't care about that we could set $_[0]
  508: 		   # directly
  509:     $args[0] = normalize_string($args[0]);
  510:     my $translation = &mt(@args);
  511:     if ($translation ne $args[0]) {
  512: 	return $translation;
  513:     } else {
  514: 	return $_[0];
  515:     }
  516: }
  517: 
  518: # ---------------------------------------------------- Replace MT{...} in files
  519: 
  520: sub transstatic {
  521:     my $strptr=shift;
  522:     $$strptr=~s/MT\{([^\}]*)\}/&mt($1)/gse;
  523: }
  524: 
  525: =pod 
  526: 
  527: =item * mt_escape
  528: 
  529: mt_escape takes a string reference and escape the [] in there so mt
  530: will leave them as is and not try to expand them
  531: 
  532: =cut
  533: 
  534: sub mt_escape {
  535:     my ($str_ref) = @_;
  536:     $$str_ref =~s/~/~~/g;
  537:     $$str_ref =~s/([\[\]])/~$1/g;
  538: }
  539: 
  540: 1;
  541: 
  542: __END__