typo3/sysext/lang/lang.php

   1 <?php
   2 /***************************************************************
   3 *  Copyright notice
   4 *
   5 *  (c) 1999-2011 Kasper Skårhøj (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  * @author      Kasper Skårhøj <kasperYYYY@typo3.com>
  31  */
  32
  33 /**
  34  * Contains the TYPO3 Backend Language class
  35  *
  36  * For detailed information about how localization is handled,
  37  * please refer to the 'Inside TYPO3' document which descibes this.
  38  *
  39  * This class is normally instantiated as the global variable $LANG in typo3/template.php
  40  * It's only available in the backend and under certain circumstances in the frontend
  41  *
  42  * @author      Kasper Skårhøj <kasperYYYY@typo3.com>
  43  * @package TYPO3
  44  * @subpackage core
  45  * @see typo3/template.php, template
  46  */
  47 class language {
  48
  49         /**
  50          * This is set to the language that is currently running for the user
  51          *
  52          * @var string
  53          */
  54         public $lang = 'default';
  55
  56         /**
  57          * Default charset in backend
  58          *
  59          * @var string
  60          */
  61         public $charSet = 'utf-8';
  62
  63         /**
  64          * Array with alternative charsets for other languages.
  65          * Moved to t3lib_cs, set internally from csConvObj!
  66          *
  67          * @var array
  68          */
  69         public $charSetArray = array();
  70
  71         /**
  72          * This is the url to the TYPO3 manual
  73          *
  74          * @var string
  75          */
  76         public $typo3_help_url= 'http://typo3.org/documentation/document-library/';
  77
  78         /**
  79          * If TRUE, will show the key/location of labels in the backend.
  80          * @var bool
  81          */
  82         public $debugKey = FALSE;
  83
  84         /**
  85          * Can contain labels and image references from the backend modules.
  86          * Relies on t3lib_loadmodules to initialize modules after a global instance of $LANG has been created.
  87          *
  88          * @var array
  89          */
  90         public $moduleLabels = array();
  91
  92         /**
  93          * Internal cache for read LL-files
  94          *
  95          * @var array
  96          */
  97         public $LL_files_cache = array();
  98
  99         /**
 100          * Internal cache for ll-labels (filled as labels are requested)
 101          *
 102          * @var array
 103          */
 104         public $LL_labels_cache = array();
 105
 106         /**
 107          * instance of the "t3lib_cs" class. May be used by any application.
 108          *
 109          * @var t3lib_cs
 110          */
 111         public $csConvObj;
 112
 113         /**
 114          * instance of the parser factory
 115          * @var t3lib_l10n_Factory
 116          */
 117         public $parserFactory;
 118
 119         /**
 120          * Initializes the backend language.
 121          * This is for example done in typo3/template.php with lines like these:
 122          *
 123          * require (PATH_typo3 . 'sysext/lang/lang.php');
 124          * $LANG = t3lib_div::makeInstance('language');
 125          * $LANG->init($GLOBALS['BE_USER']->uc['lang']);
 126          *
 127          * @throws RuntimeException
 128          * @param  string $lang         The language key (two character string from backend users profile)
 129          * @return void
 130          */
 131         public function init($lang) {
 132
 133                         // Initialize the conversion object:
 134                 $this->csConvObj = t3lib_div::makeInstance('t3lib_cs');
 135                 $this->charSetArray = $this->csConvObj->charSetArray;
 136
 137                         // Initialize the parser factory object
 138                 $this->parserFactory = t3lib_div::makeInstance('t3lib_l10n_Factory');
 139
 140                         // Finding the requested language in this list based
 141                         // on the $lang key being inputted to this function.
 142                 $ls = explode('|', TYPO3_languages);
 143
 144                         // Language is found. Configure it:
 145                 if (in_array($lang, $ls)) {
 146                                 // The current language key
 147                         $this->lang = $lang;
 148                         if ($this->charSetArray[$this->lang]) {
 149                                         // The charset if different from the default.
 150                                 $this->charSet = $this->charSetArray[$this->lang];
 151                         }
 152                 }
 153
 154                 if ($GLOBALS['TYPO3_CONF_VARS']['BE']['lang']['debug']) {
 155                         $this->debugKey = TRUE;
 156                 }
 157
 158                         // If a forced charset is used and different from the charset otherwise used:
 159                 if ($GLOBALS['TYPO3_CONF_VARS']['BE']['forceCharset'] && $GLOBALS['TYPO3_CONF_VARS']['BE']['forceCharset'] != $this->charSet) {
 160                                 // Set the forced charset:
 161                         $this->charSet = $GLOBALS['TYPO3_CONF_VARS']['BE']['forceCharset'];
 162
 163                         if ($this->charSet != 'utf-8' && !$this->csConvObj->initCharset($this->charSet)) {
 164                                 throw new RuntimeException('Forced charset not found: The forced character set "'. $this->charSet . '" was not found in t3lib/csconvtbl/', 1294587487);
 165                         }
 166                 }
 167         }
 168
 169         /**
 170          * Gets the parser factory.
 171          *
 172          * @return t3lib_l10n_Factory
 173          */
 174         public function getParserFactory() {
 175                 return $this->parserFactory;
 176         }
 177
 178         /**
 179          * Adds labels and image references from the backend modules to the internal moduleLabels array
 180          *
 181          * @param  array $arr           Array with references to module labels, keys: ['labels']['tablabel'],
 182          *                                                      ['labels']['tabdescr'], ['tabs']['tab']
 183          * @param  string $prefix       Module name prefix
 184          * @return void
 185          * @see    t3lib_loadModules
 186          */
 187         public function addModuleLabels($arr, $prefix) {
 188                 if (is_array($arr)) {
 189                         foreach ($arr as $k => $larr) {
 190                                 if (!isset($this->moduleLabels[$k])) {
 191                                         $this->moduleLabels[$k] = array();
 192                                 }
 193                                 if (is_array($larr)) {
 194                                         foreach ($larr as $l => $v) {
 195                                                 $this->moduleLabels[$k][$prefix . $l] = $v;
 196                                         }
 197                                 }
 198                         }
 199                 }
 200         }
 201
 202         /**
 203          * Will htmlspecialchar() the input string and before that any charset conversion
 204          * will also have taken place if needed (see init())
 205          * Used to pipe language labels through just before they are returned.
 206          *
 207          * @param  string $lStr The string to process
 208          * @param  boolean $hsc If set, then the string is htmlspecialchars()'ed
 209          * @return string               The processed string
 210          * @deprecated since TYPO3 4.6, will be removed in TYPO3 4.8 - Use htmlspecialchars() instead.
 211          * @see    init()
 212          * @access public
 213          */
 214         public function hscAndCharConv($lStr, $hsc) {
 215                 t3lib_div::logDeprecatedFunction();
 216                         // labels returned from a locallang file used to be in the language of the charset.
 217                         // Since TYPO3 4.1 they are always in the charset of the BE.
 218                 if ($hsc) {
 219                         return htmlspecialchars($lStr);
 220                 } else {
 221                         return $lStr;
 222                 }
 223         }
 224
 225         /**
 226          * Will convert the input strings special chars (all above 127) to entities.
 227          * The string is expected to be encoded in the charset, $this->charSet
 228          * This function is used to create strings that can be used in the Click Menu
 229          * (Context Sensitive Menus). The reason is that the values that are dynamically
 230          * written into the <div> layer is decoded as iso-8859-1 no matter what charset
 231          * is used in the document otherwise (only MSIE, Mozilla is OK).
 232          * So by converting we by-pass this problem.
 233          *
 234          * @param  string $str  Input string
 235          * @return string               Output string
 236          * @access      public
 237          */
 238         public function makeEntities($str) {
 239                         // Convert string to UTF-8:
 240                 if ($this->charSet != 'utf-8') {
 241                         $str = $this->csConvObj->utf8_encode($str, $this->charSet);
 242                 }
 243
 244                         // Convert string back again, but using the full entity conversion:
 245                 return $this->csConvObj->utf8_to_entities($str);
 246         }
 247
 248         /**
 249          * Converts the input string to a JavaScript function returning the same string, but charset-safe.
 250          * Used for confirm and alert boxes where we must make sure that any string content
 251          * does not break the script AND want to make sure the charset is preserved.
 252          * Originally I used the JS function unescape() in combination with PHP function
 253          * rawurlencode() in order to pass strings in a safe way. This could still be done
 254          * for iso-8859-1 charsets but now I have applied the same method here for all charsets.
 255          *
 256          * @param       string $str             Input string, encoded with $this->charSet
 257          * @return      string                  Output string, a JavaScript function: "String.fromCharCode(......)"
 258          * @access      public
 259          */
 260         public function JScharCode($str) {
 261
 262                         // Convert string to UTF-8:
 263                 if ($this->charSet != 'utf-8') {
 264                         $str = $this->csConvObj->utf8_encode($str, $this->charSet);
 265                 }
 266
 267                         // Convert the UTF-8 string into a array of char numbers:
 268                 $nArr = $this->csConvObj->utf8_to_numberarray($str);
 269
 270                 return 'String.fromCharCode(' . implode(',', $nArr) . ')';
 271         }
 272
 273         /**
 274          * Debugs localization key.
 275          *
 276          * @param $value Value to debug
 277          * @return string
 278          */
 279         public function debugLL($value) {
 280                 return ($this->debugKey ? '[' . $value . ']' : '');
 281         }
 282
 283         /**
 284          * Returns the label with key $index form the globally loaded $LOCAL_LANG array.
 285          * Mostly used from modules with only one LOCAL_LANG file loaded into the global space.
 286          *
 287          * @param       string $index   Label key
 288          * @param       boolean $hsc    If set, the return value is htmlspecialchar'ed
 289          * @return      string
 290          * @access      public
 291          */
 292         public function getLL($index, $hsc = FALSE) {
 293                         // Get Local Language
 294                 if (isset($GLOBALS['LOCAL_LANG'][$this->lang][$index][0]['target'])) {
 295                         $output = $GLOBALS['LOCAL_LANG'][$this->lang][$index][0]['target'];
 296                 } else {
 297                         $output = $GLOBALS['LOCAL_LANG']['default'][$index][0]['target'];
 298                 }
 299                 if ($hsc) {
 300                         $output = htmlspecialchars($output);
 301                 }
 302                 return $output . $this->debugLL($index);
 303         }
 304
 305         /**
 306          * Works like ->getLL() but takes the $LOCAL_LANG array
 307          * used as the second argument instead of using the global array.
 308          *
 309          * @param       string  $index                  Label key
 310          * @param       array   $localLanguage  $LOCAL_LANG array to get label key from
 311          * @param       boolean $hsc                    If set, the return value is htmlspecialchar'ed
 312          * @return      string
 313          * @access      public
 314          */
 315         public function getLLL($index, $localLanguage, $hsc = FALSE) {
 316                         // Get Local Language. Special handling for all extensions that
 317                         // read PHP LL files and pass arrays here directly.
 318                 $value = is_string($localLanguage[$this->lang][$index]) ? $localLanguage[$this->lang][$index] : $localLanguage[$this->lang][$index][0]['target'];
 319
 320                         // Fallback to default language
 321                 if (trim($value) === '') {
 322                         $value = is_string($localLanguage['default'][$index]) ? $localLanguage['default'][$index] : $localLanguage['default'][$index][0]['target'];
 323                 }
 324
 325                 if ($hsc) {
 326                         $value = htmlspecialchars($value);
 327                 }
 328                 return $value . $this->debugLL($index);
 329         }
 330
 331         /**
 332          * splitLabel function
 333          * Historically labels were exploded by '|' and each part would correspond
 334          * to the translation of the language found at the same 'index' in the TYPO3_languages constant.
 335          * Today all translations are based on $LOCAL_LANG variables.
 336          * 'language-splitted' labels can therefore refer to a local-lang file + index instead!
 337          * It's highly recommended to use the 'local_lang' method
 338          * (and thereby it's highly deprecated to use 'language-splitted' label strings)
 339          * Refer to 'Inside TYPO3' for more details
 340          *
 341          * @param       string $input   Label key/reference
 342          * @param       boolean $hsc    If set, the return value is htmlspecialchar'ed
 343          * @return      string
 344          * @access      public
 345          */
 346         public function sL($input, $hsc = FALSE) {
 347                         // If cached label
 348                 if (!isset($this->LL_labels_cache[$this->lang][$input]) && substr($input, 0, 4) === 'LLL:') {
 349                         $restStr = trim(substr($input, 4));
 350                         $extPrfx = '';
 351
 352                                 // ll-file refered to is found in an extension.
 353                         if (!strcmp(substr($restStr, 0, 4), 'EXT:')) {
 354                                 $restStr = trim(substr($restStr, 4));
 355                                 $extPrfx = 'EXT:';
 356                         }
 357                         $parts = explode(':', $restStr);
 358                         $parts[0] = $extPrfx . $parts[0];
 359
 360                                 // Getting data if not cached
 361                         if (!isset($this->LL_files_cache[$parts[0]])) {
 362                                 $this->LL_files_cache[$parts[0]] = $this->readLLfile($parts[0]);
 363
 364                                         // If the current language is found in another file, load that as well:
 365                                 $lFileRef = $this->localizedFileRef($parts[0]);
 366                                 if ($lFileRef && is_string($this->LL_files_cache[$parts[0]][$this->lang])
 367                                                 && $this->LL_files_cache[$parts[0]][$this->lang] == 'EXT') {
 368                                         $tempLL = $this->readLLfile($lFileRef);
 369                                         $this->LL_files_cache[$parts[0]][$this->lang] = $tempLL[$this->lang];
 370                                 }
 371                         }
 372                         $this->LL_labels_cache[$this->lang][$input] = $this->getLLL($parts[1], $this->LL_files_cache[$parts[0]]);
 373                 }
 374                         // For the cached output charset conversion has already happened!
 375                         // So perform HSC right here.
 376                 if (isset($this->LL_labels_cache[$this->lang][$input])) {
 377                         $output = $this->LL_labels_cache[$this->lang][$input];
 378                 } else {
 379                                 // Use a constant non-localizable label
 380                         $output = $input;
 381                 }
 382
 383                 if ($hsc) {
 384                         $output = t3lib_div::deHSCentities(htmlspecialchars($output));
 385                 }
 386                 return $output . $this->debugLL($input);
 387         }
 388
 389         /**
 390          * Loading $TCA_DESCR[$table]['columns'] with content from locallang files
 391          * as defined in $TCA_DESCR[$table]['refs']
 392          * $TCA_DESCR is a global var
 393          *
 394          * @param       string $table   Table name found as key in global array $TCA_DESCR
 395          * @return      void
 396          * @access      public
 397          */
 398         public function loadSingleTableDescription($table) {
 399
 400                         // First the 'table' cannot already be loaded in [columns]
 401                         // and secondly there must be a references to locallang files available in [refs]
 402                 if (is_array($GLOBALS['TCA_DESCR'][$table])
 403                                 && !isset($GLOBALS['TCA_DESCR'][$table]['columns'])
 404                                 && is_array($GLOBALS['TCA_DESCR'][$table]['refs'])) {
 405
 406                                 // Init $TCA_DESCR for $table-key
 407                         $GLOBALS['TCA_DESCR'][$table]['columns'] = array();
 408
 409                                 // Get local-lang for each file in $TCA_DESCR[$table]['refs'] as they are ordered.
 410                         foreach ($GLOBALS['TCA_DESCR'][$table]['refs'] as $llfile) {
 411                                 $localLanguage = $this->includeLLFile($llfile, 0, 1);
 412
 413                                         // Traverse all keys
 414                                 if (is_array($localLanguage['default'])) {
 415                                         foreach ($localLanguage['default'] as $lkey => $lVal) {
 416                                                 $type = '';
 417                                                 $fieldName = '';
 418
 419                                                         // Exploding by '.':
 420                                                         // 0-n => fieldname,
 421                                                         // n+1 => type from (alttitle, description, details, syntax, image_descr,image,seeAlso),
 422                                                         // n+2 => special instruction, if any
 423                                                 $keyParts = explode('.', $lkey);
 424                                                 $keyPartsCount = count($keyParts);
 425                                                         // Check if last part is special instruction
 426                                                         // Only "+" is currently supported
 427                                                 $specialInstruction = ($keyParts[$keyPartsCount - 1] == '+') ? TRUE : FALSE;
 428                                                 if ($specialInstruction) {
 429                                                         array_pop($keyParts);
 430                                                 }
 431
 432                                                         // If there are more than 2 parts, get the type from the last part
 433                                                         // and merge back the other parts with a dot (.)
 434                                                         // Otherwise just get type and field name straightaway
 435                                                 if ($keyPartsCount > 2) {
 436                                                         $type = array_pop($keyParts);
 437                                                         $fieldName = implode('.', $keyParts);
 438                                                 } else {
 439                                                         $fieldName = $keyParts[0];
 440                                                         $type = $keyParts[1];
 441                                                 }
 442
 443                                                         // Detecting 'hidden' labels, converting to normal fieldname
 444                                                 if ($fieldName == '_') {
 445                                                         $fieldName = '';
 446                                                 }
 447                                                 if (substr($fieldName, 0, 1) == '_') {
 448                                                         $fieldName = substr($fieldName, 1);
 449                                                 }
 450
 451                                                         // Append label
 452                                                 if ($specialInstruction) {
 453                                                         $GLOBALS['TCA_DESCR'][$table]['columns'][$fieldName][$type] .= LF . $lVal[0]['source'];
 454                                                 } else {
 455                                                                 // Substitute label
 456                                                         $GLOBALS['TCA_DESCR'][$table]['columns'][$fieldName][$type] = $lVal[0]['source'];
 457                                                 }
 458                                         }
 459                                 }
 460                         }
 461                 }
 462         }
 463
 464         /**
 465          * Includes locallang file (and possibly additional localized version if configured for)
 466          * Read language labels will be merged with $LOCAL_LANG (if $setGlobal = TRUE).
 467          *
 468          * @param       string $fileRef                                 $fileRef is a file-reference (see t3lib_div::getFileAbsFileName)
 469          * @param       boolean $setGlobal                              Setting in global variable $LOCAL_LANG (or returning the variable)
 470          * @param       boolean $mergeLocalOntoDefault  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.
 471          * @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
 472          * @access      public
 473          */
 474         public function includeLLFile($fileRef, $setGlobal = TRUE, $mergeLocalOntoDefault = FALSE) {
 475
 476                 $globalLanguage = array();
 477
 478                         // Get default file
 479                 $localLanguage = $this->readLLfile($fileRef);
 480
 481                 if (is_array($localLanguage) && count($localLanguage)) {
 482
 483                                 // it depends on, whether we should return the result or set it in the global $LOCAL_LANG array
 484                         if ($setGlobal) {
 485                                 $globalLanguage = t3lib_div::array_merge_recursive_overrule((array)$GLOBALS['LOCAL_LANG'], $localLanguage);
 486                         } else {
 487                                 $globalLanguage = $localLanguage;
 488                         }
 489
 490                                 // Localized addition?
 491                         $lFileRef = $this->localizedFileRef($fileRef);
 492                         if ($lFileRef && (string)$globalLanguage[$this->lang] == 'EXT') {
 493                                 $localLanguage = $this->readLLfile($lFileRef);
 494                                 $globalLanguage = t3lib_div::array_merge_recursive_overrule($globalLanguage, $localLanguage);
 495                         }
 496
 497                                 // Merge local onto default
 498                         if ($mergeLocalOntoDefault && $this->lang !== 'default'
 499                                 && is_array($globalLanguage[$this->lang]) && is_array($globalLanguage['default'])) {
 500                                         // array_merge can be used so far the keys are not
 501                                         // numeric - which we assume they are not...
 502                                 $globalLanguage['default'] = array_merge($globalLanguage['default'], $globalLanguage[$this->lang]);
 503                                 unset($globalLanguage[$this->lang]);
 504                         }
 505                 }
 506
 507                         // Return value if not global is set.
 508                 if (!$setGlobal) {
 509                         return $globalLanguage;
 510                 } else {
 511                         $GLOBALS['LOCAL_LANG'] = $globalLanguage;
 512                 }
 513         }
 514
 515         /**
 516          * Includes a locallang file and returns the $LOCAL_LANG array found inside.
 517          *
 518          * @param       string $fileRef 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.
 519          * @return      array                   Value of $LOCAL_LANG found in the included file. If that array is found it's returned. Otherwise an empty array
 520          * @access      private
 521          */
 522         protected function readLLfile($fileRef) {
 523                 return t3lib_div::readLLfile($fileRef, $this->lang, $this->charSet);
 524         }
 525
 526         /**
 527          * Returns localized fileRef (.[langkey].php)
 528          *
 529          * @param       string $fileRef Filename/path of a 'locallang.php' file
 530          * @return      string                  Input filename with a '.[lang-key].php' ending added if $this->lang is not 'default'
 531          * @access      private
 532          */
 533         protected function localizedFileRef($fileRef) {
 534                 if ($this->lang != 'default' && substr($fileRef, -4) == '.php') {
 535                         return substr($fileRef, 0, -4) . '.' . $this->lang . '.php';
 536                 }
 537         }
 538
 539         /**
 540          * Overrides a label.
 541          *
 542          * @param string $index
 543          * @param string $value
 544          * @param boolean $overrideDefault Overrides default language
 545          * @return void
 546          */
 547         public function overrideLL($index, $value, $overrideDefault = TRUE) {
 548                 if (isset($GLOBALS['LOCAL_LANG']) === FALSE) {
 549                         $GLOBALS['LOCAL_LANG'] = array();
 550                 }
 551
 552                 $GLOBALS['LOCAL_LANG'][$this->lang][$index][0]['target'] = $value;
 553
 554                 if ($overrideDefault) {
 555                         $GLOBALS['LOCAL_LANG']['default'][$index][0]['target'] = $value;
 556                 }
 557         }
 558 }
 559
 560
 561 if (defined('TYPO3_MODE') && isset($GLOBALS['TYPO3_CONF_VARS'][TYPO3_MODE]['XCLASS']['ext/lang/lang.php'])) {
 562         include_once($GLOBALS['TYPO3_CONF_VARS'][TYPO3_MODE]['XCLASS']['ext/lang/lang.php']);
 563 }
 564
 565 ?>