typo3/sysext/lang/lang.php

   1 <?php
   2 /***************************************************************
   3 *  Copyright notice
   4 *
   5 *  (c) 1999-2005 Kasper Skaarhoj (kasperYYYY@typo3.com)
   6 *  All rights reserved
   7 *
   8 *  This script is part of the TYPO3 project. The TYPO3 project is
   9 *  free software; you can redistribute it and/or modify
  10 *  it under the terms of the GNU General Public License as published by
  11 *  the Free Software Foundation; either version 2 of the License, or
  12 *  (at your option) any later version.
  13 *
  14 *  The GNU General Public License can be found at
  15 *  http://www.gnu.org/copyleft/gpl.html.
  16 *  A copy is found in the textfile GPL.txt and important notices to the license
  17 *  from the author is found in LICENSE.txt distributed with these scripts.
  18 *
  19 *
  20 *  This script is distributed in the hope that it will be useful,
  21 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  22 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  23 *  GNU General Public License for more details.
  24 *
  25 *  This copyright notice MUST APPEAR in all copies of the script!
  26 ***************************************************************/
  27 /**
  28  * Contains the TYPO3 Backend Language class
  29  *
  30  * $Id$
  31  * Revised for TYPO3 3.6.0
  32  *
  33  * @author      Kasper Skaarhoj <kasperYYYY@typo3.com>
  34  */
  35 /**
  36  * [CLASS/FUNCTION INDEX of SCRIPT]
  37  *
  38  *
  39  *
  40  *   88: class language
  41  *  138:     function init($lang,$altPath='')
  42  *  183:     function addModuleLabels($arr,$prefix)
  43  *  209:     function hscAndCharConv($lStr,$hsc)
  44  *  224:     function makeEntities($str)
  45  *  241:     function JScharCode($str)
  46  *  260:     function getLL($index,$hsc=0)
  47  *  278:     function getLLL($index,$LOCAL_LANG,$hsc=0)
  48  *  299:     function sL($input,$hsc=0)
  49  *  344:     function loadSingleTableDescription($table)
  50  *  396:     function includeLLFile($fileRef,$setGlobal=1,$mergeLocalOntoDefault=0)
  51  *  441:     function readLLfile($fileRef)
  52  *  451:     function localizedFileRef($fileRef)
  53  *
  54  * TOTAL FUNCTIONS: 12
  55  * (This index is automatically created/updated by the extension "extdeveval")
  56  *
  57  */
  58
  59
  60
  61
  62
  63
  64
  65
  66
  67
  68
  69
  70
  71
  72
  73
  74 /**
  75  * Contains the TYPO3 Backend Language class
  76  *
  77  * For detailed information about how localization is handled,
  78  * please refer to the 'Inside TYPO3' document which descibes this.
  79  *
  80  * This class is normally instantiated as the global variable $LANG in typo3/template.php
  81  * It's only available in the backend and under certain circumstances in the frontend
  82  *
  83  * @author      Kasper Skaarhoj <kasperYYYY@typo3.com>
  84  * @package TYPO3
  85  * @subpackage core
  86  * @see typo3/template.php, template
  87  */
  88 class language {
  89         var $lang='default';            // This is set to the language that is currently running for the user
  90         var $langSplit='default';       // Values like the labels in the tables.php-document are split by '|'. This values defines which language is represented by which position in the resulting array after splitting a value. (NOTICE: Obsolete concept!)
  91
  92                 // Default charset in backend
  93         var $charSet = 'iso-8859-1';
  94
  95                 // Array with alternative charsets for other languages. (Moved to t3lib_cs, Set from csConvObj!)
  96         var $charSetArray = array();
  97
  98                 // This is the url to the TYPO3 manual
  99         var $typo3_help_url= 'http://www.typo3.com/man_uk/';
 100                 // Array with alternative URLs based on language.
 101         var $helpUrlArray = array(
 102                 'dk' => 'http://www.typo3.com/man_dk/',
 103         );
 104
 105         var $debugKey = FALSE;          // If true, will show the key/location of labels in the backend.
 106
 107
 108         var $moduleLabels = Array();    // Can contain labels and image references from the backend modules. Relies on t3lib_loadmodules to initialize modules after a global instance of $LANG has been created.
 109
 110                 // Internal
 111         var $langSplitIndex=0;                  // Points to the position of the current language key as found in constant TYPO3_languages
 112         var $LL_files_cache=array();    // Internal cache for read LL-files
 113         var $LL_labels_cache=array();   // Internal cache for ll-labels (filled as labels are requested)
 114
 115                 // Internal charset conversion:
 116         var $origCharSet='';            // If set, then it means that the this->charSet is set to a forced, common value for the WHOLE backend regardless of user language. And THIS variable will contain the original charset for the language labels. With ->csConvObj we must then convert the original charset to the charset used in the backend from now on.
 117
 118         /**
 119          * instance of the "t3lib_cs" class. May be used by any application.
 120          *
 121          * @var t3lib_cs
 122          */
 123         var $csConvObj;
 124
 125
 126
 127
 128
 129
 130
 131
 132         /**
 133          * Initializes the backend language.
 134          * This is for example done in typo3/template.php with lines like these:
 135          *
 136          * require (PATH_typo3.'sysext/lang/lang.php');
 137          * $LANG = t3lib_div::makeInstance('language');
 138          * $LANG->init($BE_USER->uc['lang']);
 139          *
 140          * @param       string          The language key (two character string from backend users profile)
 141          * @param       string          IGNORE. Not used.
 142          * @return      void
 143          */
 144         function init($lang,$altPath='')        {
 145
 146                         // Initialize the conversion object:
 147                 $this->csConvObj = t3lib_div::makeInstance('t3lib_cs');
 148                 $this->charSetArray = $this->csConvObj->charSetArray;
 149
 150                         // Internally setting the list of TYPO3 backend languages.
 151                 $this->langSplit=TYPO3_languages;
 152
 153                         // Finding the requested language in this list based on the $lang key being inputted to this function.
 154                 $ls = explode('|',$this->langSplit);
 155                 while(list($i,$v)=each($ls))    {
 156                         if ($v==$lang)  {       // Language is found. Configure it:
 157                                 $this->langSplitIndex=$i;               // The index of the language as found in the TYPO3_languages list
 158                                 $this->lang = $lang;                    // The current language key
 159                                 if ($this->helpUrlArray[$this->lang])   $this->typo3_help_url=$this->helpUrlArray[$this->lang]; // The help URL if different from the default.
 160                                 if ($this->charSetArray[$this->lang])   $this->charSet=$this->charSetArray[$this->lang];                // The charset if different from the default.
 161                         }
 162                 }
 163
 164                         // If a forced charset is used and different from the charset otherwise used:
 165                 if ($GLOBALS['TYPO3_CONF_VARS']['BE']['forceCharset'] && $GLOBALS['TYPO3_CONF_VARS']['BE']['forceCharset']!=$this->charSet)     {
 166                                 // Set the forced charset:
 167                         $this->origCharSet = $this->charSet;
 168                         $this->charSet = $GLOBALS['TYPO3_CONF_VARS']['BE']['forceCharset'];
 169
 170                         if ($this->charSet!='utf-8' && !$this->csConvObj->initCharset($this->charSet))  {
 171                                 t3lib_BEfunc::typo3PrintError ('The forced character set "'.$this->charSet.'" was not found in t3lib/csconvtbl/','Forced charset not found');
 172                                 exit;
 173                         }
 174                         if ($this->origCharSet!='utf-8' && !$this->csConvObj->initCharset($this->origCharSet))          {
 175                                 t3lib_BEfunc::typo3PrintError ('The original character set "'.$this->origCharSet.'" was not found in t3lib/csconvtbl/','Forced charset not found');
 176                                 exit;
 177                         }
 178                 }
 179         }
 180
 181         /**
 182          * Adds labels and image references from the backend modules to the internal moduleLabels array
 183          *
 184          * @param       array           Array with references to module labels, keys: ['labels']['tablabel'], ['labels']['tabdescr'], ['tabs']['tab']
 185          * @param       string          Module name prefix
 186          * @return      void
 187          * @see t3lib_loadModules
 188          */
 189         function addModuleLabels($arr,$prefix)  {
 190                 if (is_array($arr))     {
 191                         reset($arr);
 192                         while(list($k,$larr)=each($arr))        {
 193                                 if (!isset($this->moduleLabels[$k]))    {
 194                                         $this->moduleLabels[$k]=array();
 195                                 }
 196                                 if (is_array($larr))    {
 197                                         reset($larr);
 198                                         while(list($l,$v)=each($larr))  {
 199                                                 $this->moduleLabels[$k][$prefix.$l]=$v;
 200                                         }
 201                                 }
 202                         }
 203                 }
 204         }
 205
 206         /**
 207          * Will htmlspecialchar() the input string and before that any charset conversion will also have taken place if needed (see init())
 208          * Used to pipe language labels through just before they are returned.
 209          *
 210          * @param       string          The string to process
 211          * @param       boolean         If set, then the string is htmlspecialchars()'ed
 212          * @return      string          The processed string
 213          * @see init()
 214          */
 215         function hscAndCharConv($lStr,$hsc)     {
 216                 $lStr = $hsc ? htmlspecialchars($lStr) : $lStr;
 217                 if ($this->origCharSet) {
 218                         $lStr = $this->csConvObj->conv($lStr,$this->origCharSet,$this->charSet,1);
 219                 }
 220                 return $lStr;
 221         }
 222
 223         /**
 224          * Will convert the input strings special chars (all above 127) to entities. The string is expected to be encoded in the charset, $this->charSet
 225          * This function is used to create strings that can be used in the Click Menu (Context Sensitive Menus). The reason is that the values that are dynamically written into the <div> layer is decoded as iso-8859-1 no matter what charset is used in the document otherwise (only MSIE, Mozilla is OK). So by converting we by-pass this problem.
 226          *
 227          * @param       string          Input string
 228          * @return      string          Output string
 229          */
 230         function makeEntities($str)     {
 231                         // Convert string to UTF-8:
 232                 if ($this->charSet!='utf-8')    $str = $this->csConvObj->utf8_encode($str,$this->charSet);
 233
 234                         // Convert string back again, but using the full entity conversion:
 235                 $str = $this->csConvObj->utf8_to_entities($str);
 236                 return $str;
 237         }
 238
 239         /**
 240          * Converts the input string to a JavaScript function returning the same string, but charset-safe.
 241          * Used for confirm and alert boxes where we must make sure that any string content does not break the script AND want to make sure the charset is preserved.
 242          * Originally I used the JS function unescape() in combination with PHP function rawurlencode() in order to pass strings in a safe way. This could still be done for iso-8859-1 charsets but now I have applied the same method here for all charsets.
 243          *
 244          * @param       string          Input string, encoded with $this->charSet
 245          * @return      string          Output string, a JavaScript function: "String.fromCharCode(......)"
 246          */
 247         function JScharCode($str)       {
 248
 249                         // Convert string to UTF-8:
 250                 if ($this->charSet!='utf-8')    $str = $this->csConvObj->utf8_encode($str,$this->charSet);
 251
 252                         // Convert the UTF-8 string into a array of char numbers:
 253                 $nArr = $this->csConvObj->utf8_to_numberarray($str);
 254
 255                 return 'String.fromCharCode('.implode(',',$nArr).')';
 256         }
 257
 258         /**
 259          * Returns the label with key $index form the globally loaded $LOCAL_LANG array.
 260          * Mostly used from modules with only one LOCAL_LANG file loaded into the global space.
 261          *
 262          * @param       string          Label key
 263          * @param       boolean         If set, the return value is htmlspecialchar'ed
 264          * @return      string
 265          */
 266         function getLL($index,$hsc=0)   {
 267                 // Get Local Language
 268                 if (strcmp($GLOBALS['LOCAL_LANG'][$this->lang][$index],''))     {
 269                         $output = $this->hscAndCharConv($GLOBALS['LOCAL_LANG'][$this->lang][$index], $hsc);     // Returns local label if not blank.
 270                 } else {
 271                         $output = $this->hscAndCharConv($GLOBALS['LOCAL_LANG']['default'][$index], $hsc);       // Returns default label
 272                 }
 273                 return $output.($this->debugKey ? ' ['.$index.']':'');
 274         }
 275
 276         /**
 277          * Works like ->getLL() but takes the $LOCAL_LANG array used as the second argument instead of using the global array.
 278          *
 279          * @param       string          Label key
 280          * @param       array           $LOCAL_LANG array to get label key from
 281          * @param       boolean         If set, the return value is htmlspecialchar'ed
 282          * @return      string
 283          */
 284         function getLLL($index,$LOCAL_LANG,$hsc=0)      {
 285                 // Get Local Language
 286                 if (strcmp($LOCAL_LANG[$this->lang][$index],''))        {
 287                         $output = $this->hscAndCharConv($LOCAL_LANG[$this->lang][$index], $hsc);        // Returns local label if not blank.
 288                 } else {
 289                         $output = $this->hscAndCharConv($LOCAL_LANG['default'][$index], $hsc);          // Returns default label
 290                 }
 291                 return $output.($this->debugKey ? ' ['.$index.']':'');
 292         }
 293
 294         /**
 295          * splitLabel function
 296          * Historically labels were exploded by '|' and each part would correspond to the translation of the language found at the same 'index' in the TYPO3_languages constant.
 297          * Today all translations are based on $LOCAL_LANG variables. 'language-splitted' labels can therefore refer to a local-lang file + index instead!
 298          * It's highly recommended to use the 'local_lang' method (and thereby it's highly deprecated to use 'language-splitted' label strings)
 299          * Refer to 'Inside TYPO3' for more details
 300          *
 301          * @param       string          Label key/reference
 302          * @param       boolean         If set, the return value is htmlspecialchar'ed
 303          * @return      string
 304          */
 305         function sL($input,$hsc=0)      {
 306                 if (strcmp(substr($input,0,4),'LLL:'))  {       // Using obsolete 'language-splitted' labels:
 307                         $t = explode('|',$input);
 308                         $out = $t[$this->langSplitIndex] ? $t[$this->langSplitIndex] : $t[0];
 309                         return $this->hscAndCharConv($out, $hsc);
 310                 } else {        // LOCAL_LANG:
 311                         if (!isset($this->LL_labels_cache[$this->lang][$input])) {      // If cached label
 312                                 $restStr = trim(substr($input,4));
 313                                 $extPrfx='';
 314                                 if (!strcmp(substr($restStr,0,4),'EXT:'))       {       // ll-file refered to is found in an extension.
 315                                         $restStr = trim(substr($restStr,4));
 316                                         $extPrfx='EXT:';
 317                                 }
 318                                 $parts = explode(':',$restStr);
 319                                 $parts[0]=$extPrfx.$parts[0];
 320                                 if (!isset($this->LL_files_cache[$parts[0]]))   {       // Getting data if not cached
 321                                         $this->LL_files_cache[$parts[0]] = $this->readLLfile($parts[0]);
 322
 323                                                 // If the current language is found in another file, load that as well:
 324                                         $lFileRef = $this->localizedFileRef($parts[0]);
 325                                         if ($lFileRef && is_string($this->LL_files_cache[$parts[0]][$this->lang]) && $this->LL_files_cache[$parts[0]][$this->lang]=='EXT')      {
 326                                                 $tempLL = $this->readLLfile($lFileRef);
 327                                                 $this->LL_files_cache[$parts[0]][$this->lang] = $tempLL[$this->lang];
 328                                         }
 329
 330                                                 // Overriding file?
 331                                         if (isset($GLOBALS['TYPO3_CONF_VARS']['BE']['XLLfile'][$parts[0]]))     {
 332                                                 $ORarray = $this->readLLfile($GLOBALS['TYPO3_CONF_VARS']['BE']['XLLfile'][$parts[0]]);
 333                                                 $this->LL_files_cache[$parts[0]] = t3lib_div::array_merge_recursive_overrule($this->LL_files_cache[$parts[0]],$ORarray);
 334                                         }
 335                                 }
 336                                 $this->LL_labels_cache[$this->lang][$input] = $this->getLLL($parts[1],$this->LL_files_cache[$parts[0]]);
 337                         }
 338                         $output = $hsc ? t3lib_div::deHSCentities(htmlspecialchars($this->LL_labels_cache[$this->lang][$input])) : $this->LL_labels_cache[$this->lang][$input]; // For the cached output charset conversion has already happend! So perform HSC right here.
 339                         return $output.($this->debugKey ? ' ['.$input.']':'');
 340                 }
 341         }
 342
 343         /**
 344          * Loading $TCA_DESCR[$table]['columns'] with content from locallang files as defined in $TCA_DESCR[$table]['refs']
 345          * $TCA_DESCR is a global var
 346          *
 347          * @param       string          Table name found as key in global array $TCA_DESCR
 348          * @return      void
 349          */
 350         function loadSingleTableDescription($table)     {
 351                 global $TCA_DESCR;
 352
 353                 if (is_array($TCA_DESCR[$table])
 354                                 && !isset($TCA_DESCR[$table]['columns'])
 355                                 && is_array($TCA_DESCR[$table]['refs']))         {      // First the 'table' cannot already be loaded in [columns] and secondly there must be a references to locallang files available in [refs]
 356
 357                                 // Init $TCA_DESCR for $table-key
 358                         $TCA_DESCR[$table]['columns']=array();
 359
 360                                 // Get local-lang for each file in $TCA_DESCR[$table]['refs'] as they are ordered.
 361                         foreach ($TCA_DESCR[$table]['refs'] as $llfile) {
 362                                 $LOCAL_LANG = $this->includeLLFile($llfile,0,1);
 363
 364                                         // Traverse all keys
 365                                 if (is_array($LOCAL_LANG['default']))   {
 366                                         foreach($LOCAL_LANG['default'] as $lkey => $lVal)       {
 367
 368                                                         // exploding by '.':
 369                                                         // 0 => fieldname,
 370                                                         // 1 => type from (alttitle,description,details,syntax,image_descr,image,seeAlso),
 371                                                         // 2 => special instruction, see switch construct
 372                                                 $kParts = explode('.',$lkey);
 373
 374                                                         // Detecting 'hidden' labels, converting to normal fieldname
 375                                                 if ($kParts[0]=='_')    $kParts[0]='';
 376                                                 if (substr($kParts[0],0,1)=='_')        { $kParts[0] = substr($kParts[0],1); }
 377
 378                                                         // Add label:
 379                                                 switch((string)$kParts[2])      {
 380                                                         case '+':       // adding
 381                                                                 $TCA_DESCR[$table]['columns'][$kParts[0]][$kParts[1]].= chr(10).$lVal;
 382                                                         break;
 383                                                         default:        // Substituting:
 384                                                                 $TCA_DESCR[$table]['columns'][$kParts[0]][$kParts[1]] = $lVal;
 385                                                         break;
 386                                                 }
 387                                         }
 388                                 }
 389                         }
 390                 }
 391         }
 392
 393         /**
 394          * Includes locallang file (and possibly additional localized version if configured for)
 395          * Read language labels will be merged with $LOCAL_LANG (if $setGlobal=1).
 396          *
 397          * @param       string          $fileRef is a file-reference (see t3lib_div::getFileAbsFileName)
 398          * @param       boolean         Setting in global variable $LOCAL_LANG (or returning the variable)
 399          * @param       boolean         If $mergeLocalOntoDefault is set the local part of the $LOCAL_LANG array is merged onto the default part (if the local part exists) and the local part is unset.
 400          * @return      mixed           If $setGlobal is true the LL-files will set the $LOCAL_LANG in the global scope. Otherwise the $LOCAL_LANG array is returned from function
 401          */
 402         function includeLLFile($fileRef,$setGlobal=1,$mergeLocalOntoDefault=0)  {
 403                         // Configure for global flag:
 404                 if ($setGlobal) {
 405                         global $LOCAL_LANG;
 406                 }
 407
 408                         // Get default file:
 409                 $llang = $this->readLLfile($fileRef);
 410
 411                 if (count($llang))      {
 412
 413                         $LOCAL_LANG = t3lib_div::array_merge_recursive_overrule($LOCAL_LANG,$llang);
 414
 415                                 // Localized addition?
 416                         $lFileRef = $this->localizedFileRef($fileRef);
 417                         if ($lFileRef && (string)$LOCAL_LANG[$this->lang]=='EXT')       {
 418                                 $llang = $this->readLLfile($lFileRef);
 419                                 $LOCAL_LANG = t3lib_div::array_merge_recursive_overrule($LOCAL_LANG,$llang);
 420                         }
 421
 422                                 // Overriding file?
 423                         if (isset($GLOBALS['TYPO3_CONF_VARS']['BE']['XLLfile'][$fileRef]))      {
 424                                 $ORarray = $this->readLLfile($GLOBALS['TYPO3_CONF_VARS']['BE']['XLLfile'][$fileRef]);
 425                                 $LOCAL_LANG = t3lib_div::array_merge_recursive_overrule($LOCAL_LANG,$ORarray);
 426                         }
 427
 428                                 // Merge local onto default:
 429                         if ($mergeLocalOntoDefault && strcmp($this->lang,'default') && is_array($LOCAL_LANG[$this->lang]) && is_array($LOCAL_LANG['default']))  {
 430                                 $LOCAL_LANG['default'] = array_merge($LOCAL_LANG['default'],$LOCAL_LANG[$this->lang]);  // array_merge can be used so far the keys are not numeric - which we assume they are not...
 431                                 unset($LOCAL_LANG[$this->lang]);
 432                         }
 433                 }
 434
 435                         // Return value if not global is set.
 436                 if (!$setGlobal)        {
 437                         return $LOCAL_LANG;
 438                 }
 439         }
 440
 441         /**
 442          * Includes a locallang file and returns the $LOCAL_LANG array found inside.
 443          *
 444          * @param       string          Input is a file-reference (see t3lib_div::getFileAbsFileName) which, if exists, is included. That file is expected to be a 'local_lang' file containing a $LOCAL_LANG array.
 445          * @return      array           Value of $LOCAL_LANG found in the included file. If that array is found it's returned. Otherwise an empty array
 446          */
 447         function readLLfile($fileRef)   {
 448                 return t3lib_div::readLLfile($fileRef,$this->lang);
 449         }
 450
 451         /**
 452          * Returns localized fileRef (.[langkey].php)
 453          *
 454          * @param       string          Filename/path of a 'locallang.php' file
 455          * @return      string          Input filename with a '.[lang-key].php' ending added if $this->lang is not 'default'
 456          */
 457         function localizedFileRef($fileRef)     {
 458                 if ($this->lang!='default' && substr($fileRef,-4)=='.php')      {
 459                         return substr($fileRef,0,-4).'.'.$this->lang.'.php';
 460                 }
 461         }
 462 }
 463
 464 // Include extension to the template class?
 465 if (defined('TYPO3_MODE') && $TYPO3_CONF_VARS[TYPO3_MODE]['XCLASS']['ext/lang/lang.php'])       {
 466         include_once($TYPO3_CONF_VARS[TYPO3_MODE]['XCLASS']['ext/lang/lang.php']);
 467 }
 468 ?>