Trans.php

Go to the documentation of this file.

<?php
 
namespace Rsi\Fred;
 
/**
 *  Translations component.
 */
class Trans extends Component{
 
  const TYPE_TAG = '+'; //!< Add a tag to to the tags: [+tag|value].
  const TYPE_OPTIONAL = '?'; //!< Optional sub-string (defaults to empty; no error): [?strId].
  const TYPE_SUBSTR = '@'; //!< Points to a sub-string: [\@strId].
  const TYPE_TRUE = '%'; //!< Show section when tag value is true: {[%tag]show when tag is not empty}.
  const TYPE_FALSE = '!'; //!< Show section when tag value is false: {[!tag]show when tag is empty}.
  const TYPE_COUNT = '#'; //!< Insert number of items in array: Array has [\#arrayTag] items.
  const TYPE_SUM = '='; //!< Sum of an array column: [=array|column|formatting].
  const TYPE_ARRAY = '*'; //!< Repeat section for each item (item aded to tags, including k = key, v = value - when record is
    // not an array, i = index, r = reverse index): Values: [*arrayTag|{\\[i\\], }\\[v\\]].
  const TYPE_DECODE = ':'; //!< Decode a value: [:intTag|1:foo|2:bar|default]. Set the value to '?' for a random selection.
  const TYPE_JSON = '$'; //!< Insert a JSON encoded value.
  const TYPE_HTML = '&'; //!< Insert an HTML block: [&contentTag|htmlTag|params].
  const TYPE_RAW = '~'; //!< Insert value without inserting a conditional tag: [[~intTag],number].
 
  const MACRO_ESCAPE = 'escape'; //!< Escape the text between these tags (pre processing).
  const MACRO_SECTION = 'section'; //!< Define a section which content can be redefined later on (use the 'id' attribute). The
    // content is processed afterwards.
  const MACRO_FRAGMENT = 'fragment'; //!< Replace the tag with a placeholder and replace it with the fragment later on (with
    // 'delay' attribute) or on demand (set the 'id' attribute).
  const MACRO_SPACE = 'space'; //!< Remove white-space between tags.
  const MACRO_REPLACE = 'replace'; //!< Replace the text in attribute 'from' (regex) to 'to'.
  const MACRO_UNITS = 'units'; //!< Split the value of the tag name into units, so it can be used as an array (units in desired
    // order in the 'units' tag - e.g. 'km=1000,m=1,cm=0.01'; use the 'tolerance' tag to set a cut-off percentage; set the 'tag'
    // attribute to choose a custom result tag - defaults to current tag + 'Units'; add an 'empty' attribute to include units
    // without values, if there is a higher unit with a value; pre processing).
  const MACRO_CONST = 'const'; //!< Replace the text with the value of the constant between the tags (pre processing).
  const MACRO_CACHE = 'cache'; //!< Cache the (processed) text (set the 'ttl' tag to use the main cache; use the 'key'
    // attribute to define a custom cache key, otherwise one is generated; the key can contain tags).
  const MACRO_ROUTE = 'route'; //!< Create a (reverse) route for the controller name between the tags (attributes are params).
  const MACRO_LOCATION = 'location'; //!< Rewrite the location between the tags (pre processing).
  const MACRO_IMAGE = 'image'; //!< Generate an image tag for the image between the tags (the content is cached, set the 'ttl'
    // attribute to deviate from the default $imageTtl).
  const MACRO_URL = 'url'; //!< Load external content from the address between the tags (the content is cached, set the 'ttl'
    // attribute to deviate from the default $urlTtl; pre processing)).
  const MACRO_RIGHT = 'right'; //<! Only include the text when the user is authorized for the 'right' attribute (set an
    // optional 'level'; add a 'not' attribute for the other way round; pre processing).
 
  const EVENT_FORMAT = 'trans:format:';
 
  public $namespace = 'trans';
  public $maxNested = 10; //!< Maximum number of times a sub-string may be nested.
  public $logPrio = Log::INFO; //!< Prio for translation related errors (invalid tags, format, etc).
  public $minLogSteps = 5; //!< Only log translation steps with more than this number of steps.
  public $imageTtl = 86400; //!< Default cache TTL for image tag generation.
  public $imageKeyPrefix = 'trans-image-';
  public $urlTtl = 86400; //!< Default cache TTL for external content.
  public $urlKeyPrefix = 'trans-url-';
  public $cacheKeyPrefix = 'trans-cache-';
 
  protected $_langId = null;
  protected $_filename = null; //!< Filename for the translations (asterisk will be replace by the langId).
  protected $_prefix = null;
  protected $_strs = [];
  protected $_tags = []; //!< Default tags to use with every translation.
 
  protected $_section = [];
  protected $_sectionIndex = 0;
  protected $_escape = [];
  protected $_unescape = [];
  protected $_cache = [];
 
  protected $_types = null;
  protected $_regex = null;
 
  protected function init(){
    parent::init();
    if(!$this->_prefix) $this->_prefix = \Rsi\Str::random();
    foreach(['{','[',']','}'] as $char) $this->_unescape[$this->_escape['\\' . $char] = $this->_prefix . bin2hex($char)] = $char;
    $this->publish(['langId'],self::READWRITE);
  }
  /**
   * Available languages.
   * @return array  Key = ID, value = description.
   */
  public function langs(){
    return [$this->langId => null];
  }
 
  protected function error($message,$file = null,$line_no = null,$context = null){
    $this->component('log')->add($this->logPrio,$message,$file,$line_no,$context);
    return 'error';
  }
  /**
   * Get all strings.
   * @param string $lang_id  Language ID.
   * @return array  Key = string ID, value = string.
   */
  protected function getStrs($lang_id){
    return require(str_replace('*',$lang_id,$this->_filename));
  }
  /**
   * Basic string getter.
   * @param string $id  String ID.
   * @param string $default  Default string when ID is not found.
   * @return string
   */
  public function getStr($id,$default = false){
    $id = explode('.',$id);
    $lang_id = $id[1] ?? $this->langId;
    if(!array_key_exists($lang_id,$this->_strs)) $this->_strs[$lang_id] = array_change_key_case($this->getStrs($lang_id));
    return array_key_exists($id = strtolower($id[0]),$this->_strs[$lang_id]) ? $this->_strs[$lang_id][$id] : $default;
  }
 
  protected function macro($str,$type,&$tags,$callback){
    if(
      (strpos($str,'<' . ($tag = $this->namespace . ':' . $type)) !== false) &&
      preg_match_all("/<$tag(?<attribs>(" . \Rsi\Str::ATTRIBUTES_PATTERN . ")*)>(?<str>.*?)<\\/$tag>/s",$str,$matches,PREG_SET_ORDER)
    ) foreach($matches as $match) try{
      $str = str_replace($match[0],call_user_func_array($callback,[$match['str'],\Rsi\Str::attributes($match['attribs']),&$tags]),$str);
    }
    catch(\Exception $e){
      return $this->error($e,['macro' => $type]);
    }
    return $str;
  }
 
  protected function preProcess($str,&$tags){
    if($str){
      $str = str_replace(array_keys($this->_escape),$this->_escape,$this->macro($str,self::MACRO_ESCAPE,$tags,function($str){
        return str_replace($this->_unescape,array_keys($this->_unescape),$str);
      }));
      if(strpos($str,'<' . $this->namespace . ':') !== false){
        $str = $this->macro($str,self::MACRO_SECTION,$tags,function($str,$attribs){
          if(!array_key_exists($id = $attribs['id'] ?? $this->_prefix . $this->_sectionIndex,$this->_section)) $this->_section[$id] = $str;
          $tag = $this->namespace . ':' . self::MACRO_SECTION;
          return "<$tag id='$id'>" . $this->_sectionIndex++ . "</$tag>";
        });
        $str = $this->macro($str,self::MACRO_CACHE,$tags,function($str,$attribs,&$tags){
          if(!($key = $attribs['key'] ?? null)) $key = md5($str);
          elseif(preg_match_all('/\\[([\\w\\-]+)\\]/',$key,$matches,PREG_SET_ORDER)) foreach($matches as list($full,$tag)){
            if(is_array($value = $this->value($tag,null,$tags))) $value = md5(serialize($value));
            $key = str_replace($full,$value === null ? '' : $value,$key);
          }
          $key .= '-' . ($attribs['lang'] ?? $this->langId);
          if(!is_numeric($ttl = $attribs['ttl'] ?? 0)) $ttl = $this->evaluate($ttl,null,$tags);
          if(!array_key_exists($key,$this->_cache)) $this->_cache[$key] = $ttl ? $this->component('cache')->fetch($this->cacheKeyPrefix . $key) : false;
          $tag = $this->namespace . ':' . self::MACRO_CACHE;
          return "<$tag key='$key' ttl='$ttl'>" . ($this->_cache[$key] === false ? $str : '') . "</$tag>";
        });
        $str = $this->macro($str,self::MACRO_CONST,$tags,function($name){
          return constant($name);
        });
        $str = $this->macro($str,self::MACRO_UNITS,$tags,function($tag,$attribs,&$tags){
          $result = [];
          foreach(\Rsi\Number::units($value = $tags[$tag] ?? 0,\Rsi\Record::explode($attribs['units'] ?? null,',','='),$value * ($attribs['tolerance'] ?? 0) / 100) as $unit => $count)
            if($count || array_key_exists('empty',$attribs)) $result[] = compact('unit','count');
          $tags[$attribs['tag'] ?? $tag . 'Units'] = $result;
          return null;
        });
        $str = $this->macro($str,self::MACRO_LOCATION,$tags,function($str){
          return htmlspecialchars($this->component('location')->rewrite($str));
        });
        $str = $this->macro($str,self::MACRO_URL,$tags,function($url,$attribs){
          return $this->component('cache')->fetch($this->urlKeyPrefix . $url,$attribs['ttl'] ?? $this->urlTtl,function() use ($url){
            $this->component('log')->debug("Loading external content from '$url'",__FILE__,__LINE__);
            return preg_match('/^https?:\\/\\/(?!localhost|127\\.0\\.0\\.|\\[[0:]+1\\])/i',$url) ? file_get_contents($url) : $url;
          });
        });
        $str = $this->macro($str,self::MACRO_RIGHT,$tags,function($str,$attribs){
          return ($this->component('user')->authorized($attribs['right'] ?? null,$attribs['level'] ?? null) xor ($attribs['not'] ?? false)) ? $str : null;
        });
      }
    }
    return $str;
  }
 
  protected function postProcess($str,&$tags){
    if($str && (strpos($str,'<' . $this->namespace . ':') !== false)){
      $str = $this->macro($str,self::MACRO_SECTION,$tags,function($str,$attribs,$tags){
        $str = $this->_section[$id = $attribs['id']];
        $this->_section[$id] = null;
        return $this->trans($str,$tags);
      });
      $str = $this->macro($str,self::MACRO_FRAGMENT,$tags,function($str,$attribs){
        $fragments = $this->session->fragments ?: [];
        $fragments[$id = $attribs['id'] ?? 'fragment-' . \Rsi\Str::random()] = $str;
        $this->session->fragments = $fragments;
        return ($delay = $attribs['delay'] ?? null)
          ? "<div class='fred-fragment' id='$id'><script>document.addEventListener('DOMContentLoaded',function(){" .
              "setTimeout(function(){ fred.controller.fragment('#$id','$id') },$delay * 1000)" .
            "},true)</script></div>"
          : null;
      });
      $str = $this->macro($str,self::MACRO_CACHE,$tags,function($str,$attribs){
        $key = $attribs['key'];
        if(($this->_cache[$key] ?? false) !== false) return $this->_cache[$key];
        if($ttl = $attribs['ttl'] ?? false) $this->component('cache')->save($this->cacheKeyPrefix . $key,$str,$ttl);
        return $this->_cache[$key] = $str;
      });
      $str = $this->macro($str,self::MACRO_ROUTE,$tags,function($controller_name,$params){
        $controller_name = explode('.',$controller_name);
        if(array_key_exists('_',$params)){
          foreach(($params['_'] == '*' ? array_keys($_GET) : explode(',',$params['_'])) as $key)
            if(!array_key_exists($key,$params) && ($value = $this->component('request')->complex($key))) $params[$key] = $value;
          unset($params['_']);
        }
        return htmlspecialchars($this->component('router')->reverse($controller_name[0],$controller_name[1] ?? null,$params));
      });
      $str = $this->macro($str,self::MACRO_SPACE,$tags,function($str){
        return trim(preg_replace('/\\s*\\n\\s*/',"\n",preg_replace('/>\\s+</','><',$str)));
      });
      $str = $this->macro($str,self::MACRO_REPLACE,$tags,function($str,$attribs){
        if(!array_key_exists('from',$attribs)) return $str;
        if(substr($from = $attribs['from'],0,1) != '/') $from = '/' . preg_quote($from,'/') . '/';
        return preg_replace($from,$attribs['to'] ?? null,$str);
      });
      $str = $this->macro($str,self::MACRO_IMAGE,$tags,function($url,$attribs){
        return $this->component('cache')->fetch($this->imageKeyPrefix . $url . '?' . http_build_query($attribs),$attribs['ttl'] ?? $this->imageTtl,function() use ($url,$attribs){
          unset($attribs['ttl']);
          foreach(['width','height','background'] as $key) if(array_key_exists($key,$attribs) && ($attribs[$key] == 'auto')) $attribs[$key] = true;
          return $this->component('html')->img($url,$attribs);
        });
      });
    }
    return $str;
  }
  /**
   * Escape tag values (convert special characters to HTML entities).
   * @param array $tags  Tags with raw values (keys starting with '!' are not escaped - '!' is removed from key).
   * @return array  Escaped tags
   */
  public function escape($tags){
    $escaped = [];
    if($tags) foreach($tags as $tag => $value){
      switch(substr($tag,0,1)){
        case '!': $tag = substr($tag,1); //raw
        case '@': break; //callback
        default: if(!is_object($value)) $value = is_array($value) ? $this->escape($value) : ($value ? htmlspecialchars($value) : $value);
      }
      $escaped[$tag] = $value;
    }
    return $escaped;
  }
 
  protected function value($tag,$params,&$tags){
    if(\Rsi\Str::numeric($tag)) return $tag;
    $value = $tags;
    $found = true;
    foreach(($keys = explode('.',$tag)) as $key){
      if(is_object($value)) try{
        $value = $this->escape([$value->$key])[0];
      }
      catch(\Exception $e){
        $this->error("Property '$key' does not exists for tag '$tag'",__FILE__,__LINE__,compact('value'));
        $found = false;
        break;
      }
      elseif(!is_array($value) || !array_key_exists($key,$value)){
        $found = false;
        break;
      }
      else $value = $value[$key];
    }
    if($found) try{
       return is_object($value) ? strval($value) : $value;
    }
    catch(\Exception $e){
      $this->error("Could not convert object for tag '$tag' to string",__FILE__,__LINE__,compact('value'));
    }
    foreach($tags as $key => $value) if((substr($key,0,1) == '@') && !strcasecmp($keys[0],trim($key,'@!'))){
      $value = [$keys[0] => call_user_func($value,$tag,$tags,$params)];
      $tags += substr($key,1,1) == '!' ? $value : $this->escape($value);
      return \Rsi\Record::iget($tags,$keys);
    }
    \Rsi\Record::set($tags,$keys,null);
    return null;
  }
 
  protected function evaluate($expr,$tag,&$tags){
    $expr = strtr($expr,[$this->_prefix . true => '','?' => is_array($tag) ? implode(',',$tag) : $tag]);
    foreach($tags as $key => $value) if(preg_match($mask = '/\\b' . preg_quote($tag = trim($key,'@!'),'/') . '\\b/',$expr)){
      if(is_array($value = $this->value($tag,null,$tags))) $value = implode(',',$value);
      elseif(preg_match('/^\\d{4}-\\d{2}-\\d{2}/',$value)) $value = "'$value'";
      elseif(!is_numeric($value)) $value = $value ? 1 : 0;
      $expr = preg_replace($mask,$value,$expr);
    }
    return \Rsi\Number::evaluate($expr);
  }
 
  protected function formatSubstr($value,$start,$length = null){
    return $length === null ? substr($value,$start) : substr($value,$start,$length);
  }
 
  protected function formatReplace($value,$search,$replace){
    return str_replace($search,$replace,$value);
  }
 
  protected function formatRegex($value,$pattern,$replace){
    return preg_replace($pattern,$replace,$value);
  }
 
  protected function formatHash($value,$algo,$prefix = null,$suffix = null){
    return hash($algo,$prefix . $value . $suffix);
  }
  /**
   * Format a value.
   * @param string $tag  Tag name.
   * @param mixed $value  Tag value.
   * @param string $params  Formatting params.
   * @param array $tags  Other tags.
   * @return string  Formatted value.
   */
  protected function format($tag,$value,$params,&$tags){
    foreach(explode('|',$params) as $format) if($format) try{
      if(substr($format,0,1) == '=') $value = $this->evaluate(substr($format,1),$tag,$tags);
      elseif(preg_match('/(\w+)\\((.*)\\)$/',$format,$match)){
        $func_name = 'format' . ucfirst($match[1]);
        $params = array_merge([$value],strlen($match[2]) ? array_map('urldecode',explode(',',$match[2])) : []);
        if(method_exists($component = $this,$func_name) || method_exists($component = $this->component('local'),$func_name))
          $value = call_user_func_array([$component,$func_name],$params);
        else $value = call_user_func_array(
          [$this->component('event'),'trigger'],
          array_merge([self::EVENT_FORMAT . $match[1],$this],$params)
        );
      }
      else{
        $value = \Rsi\Str::transform($value,$format,$count);
        if(!$count) $value = date($format,is_numeric($value) ? $value : strtotime($value));
      }
    }
    catch(\Exception $e){
      $value = $this->error($e,compact('tag','value','params'));
      break;
    }
    return is_array($value) ? false : $value;
  }
  /**
   * Replace a tag with its value.
   * @param string $str  String to replace tag in.
   * @param string $full  Full match for the tag (including brackets).
   * @param int $index  Position in string.
   * @param string $type  Type of tag (see TYPE_* constants).
   * @param string $tag  Name of the tag.
   * @param string $operator  Operator for the tag (e.g. '==').
   * @param string $params  Extra parameters in the tag.
   * @param mixed $value  Value for the tag.
   * @param array $tags  All available tags (values).
   * @param array $strs  Loaded sub-strings.
   * @return string  Original input string with the full tag replaced with its value.
   */
  protected function replace($str,$full,$index,$type,$tag,$operator,$params,$value,&$tags,&$strs){
    $default = $replace = $raw = false;
    if($type) switch($type){
      case self::TYPE_TAG:
        $tags[$tag] = substr($params,1);
        $raw = true;
        break;
      case self::TYPE_OPTIONAL:
        $default = null; //fall through
      case self::TYPE_SUBSTR:
        if(!in_array($tag,$strs)) $strs[] = $tag;
        $replace = \Rsi\Str::transform($this->preProcess($this->getStr($tag,$default),$tags),$params = explode('|',$params));
        $raw = !in_array(self::MACRO_ESCAPE,$params);
        break;
      case self::TYPE_TRUE:
        if(substr($params,0,2) == '|=') $value = $this->evaluate(substr($params,2),$tag,$tags);
        if($value) $replace = $this->_prefix . true;
        $raw = true;
        break;
      case self::TYPE_FALSE:
        if(substr($params,0,2) == '|=') $value = $this->evaluate(substr($params,2),$tag,$tags);
        if(!$value) $replace = $this->_prefix . true;
        $raw = true;
        break;
      case self::TYPE_COUNT:
        $replace = count((array)$value);
        $raw = true;
        break;
      case self::TYPE_SUM:
        if(is_array($value)){
          $params = explode('|',substr($params,1),2);
          $replace = $this->format($tag,array_sum(\Rsi\Record::column($value,$params[0])),$params[1] ?? null,$tags) . $this->_prefix . true;
        }
        break;
      case self::TYPE_ARRAY:
        if($value && (is_array($value) || (is_numeric($value) && ($value > 0) && ($value = range(1,$value))))){
          $replace = $this->_prefix . true;
          $sub = str_replace(array_keys($this->_unescape),$this->_unescape,substr($params,1));
          $i = 0; //index
          $r = count($value); //reverse
          foreach($value as $key => $record) $replace .=
            $this->trans($sub,(is_array($record) ? $record : []) + ['v' => $record,'k' => $key,'i' => $i++,'r' => --$r] + $tags);
        }
        break;
      case self::TYPE_DECODE:
        $options = explode('|',substr($params,1));
        $random = $value == '?' ? rand(0,count($options) - 1) : false;
        foreach($options as $key => $option){
          $i = strpos($option,':');
          if($i === false) $replace = $option; //default
          elseif($random === false ? \Rsi\Str::operator($value,$operator ?: '==',substr($option,0,$i)) : $key == $random){
            $replace = substr($option,$i + 1);
            break;
          }
        }
        if(!\Rsi::nothing($replace)) $replace = $this->trans(str_replace(array_keys($this->_unescape),$this->_unescape,$replace),$tags) . $this->_prefix . true;
        break;
      case self::TYPE_JSON:
        $replace = json_encode($value);
        break;
      case self::TYPE_HTML:
        try{
          $params = explode('|',substr($params,1));
          $html = $this->component('html');
          $html->escape = false; //escaping done here
          $replace = call_user_func_array([$html,array_shift($params)],array_merge([$value],$params));
        }
        catch(\Exception $e){
          $replace = $this->error($e,compact('tag','params'));
        }
        break;
      case self::TYPE_RAW:
        $replace = $this->format($tag,$value,$params,$tags);
        break;
    }
    elseif($operator){
      if(\Rsi\Str::operator(is_array($value) ? count($value) : str_replace($this->_unescape,array_keys($this->_unescape),$value ?? ''),$operator,$params)) $replace = $this->_prefix . true;
      $raw = true;
    }
    elseif(!\Rsi::nothing($value)) //standard tag
      $replace = $this->format($tag,$value,$params,$tags) . $this->_prefix . true;
    return substr($str,0,$index) . ($raw ? $replace : str_replace($this->_unescape,array_keys($this->_unescape),$replace ?? '')) . substr($str,$index + strlen($full));
  }
  /**
   * Elaborate conditional parts.
   * @param string $str  String with conditional parts.
   * @return string  String with elaborated conditional parts.
   */
  protected function brush($str){
    while(($end = strpos($str,'}')) && (($start = strrpos($str,'{',$end - strlen($str))) !== false)) $str =
      substr($str,0,$start) .
      (strpos($replace = substr($str,$start + 1,$end - $start - 1),$this->_prefix . true) === false ? '' : str_replace($this->_prefix . true,'',$replace)) .
      substr($str,$end + 1);
    return $str;
  }
  /**
   * Translate a string.
   * @param string $str  Basic string with tags.
   * @param array $tags  Tags to use when translating the string. Values are automatically escaped, except when the key starts
   *   with a '!'. For keys starting with a '@' the value is used as a callback function (only called when the tag is present
   *   in the string; use '@!' prefix for callback values that should not be escaped).
   * @param array $steps  Save translations steps when non empty.
   * @return string  Translated string.
   */
  protected function trans($str,$tags,&$steps = null){
    if(!$str) return $str;
    $count = $strs = [];
    $step = 0;
    $str = $this->preProcess($str,$tags);
    if($steps) $steps['after pre-processing'] = $str;
    while($str && preg_match_all($this->regex,$str,$matches,PREG_SET_ORDER | PREG_OFFSET_CAPTURE)){
      foreach($strs as $id){
        if(!array_key_exists($id,$count)) $count[$id] = 0;
        elseif(++$count[$id] >= $this->maxNested){
          $this->error("Sub-string '$id' nested more than {$this->maxNested} times",__FILE__,__LINE__,compact('str','tags'));
          break 2;
        }
      }
      $strs = [];
      foreach(array_reverse($matches) as $match){ //0=full,1=type,2=tag,3=operator,4=params
        if(substr($type = $match[1][0],0,1) == '{') $type = $this->types[substr($type,1,-1)] ?? null;
        $tag = $match[2][0];
        $params = $match[4][0];
        $value = in_array($type,[self::TYPE_TAG,self::TYPE_OPTIONAL,self::TYPE_SUBSTR]) ? null : $this->value($tag,$params,$tags);
        $str = $this->replace($str,$match[0][0],$match[0][1],$type,$tag,$match[3][0],$params,$value,$tags,$strs);
      }
      if($steps) $steps['step ' . ++$step] = $str;
    }
    return str_replace($this->_prefix . true,'',str_replace(array_keys($this->_unescape),$this->_unescape,$this->brush($str)));
  }
  /**
   * Translate a string.
   * @param string $str  Basic string with tags.
   * @param array $tags  Tags to use when translating the string.
   * @return string  Translated string.
   */
  public function str($str,$tags = null){
    if(!$str) return $str;
    $tags = $this->escape(array_merge($this->_tags,$tags ?: []));
    $steps = $this->_fred->debug ? ['original string' => $orig = $str] : null;
    $str = $this->trans($str,$tags,$steps);
    if($steps) $steps['before post-processing'] = $str;
    $str = $this->postProcess($str,$tags);
    if($steps && count($steps) >= $this->minLogSteps) $this->component('log')->debug(__CLASS__ . "::trans('$orig',...)",__FILE__,__LINE__,[
      'steps' => $steps + ['result' => $str],
      'tags' => $tags,
      'prefix' => $this->_prefix,
      'unescape' => $this->_unescape + [$this->_prefix . true => 'true']
    ]);
    return $str;
  }
  /**
   * Translate a string by ID.
   * @param string $id  String ID.
   * @param array $tags  Tags to use when translating the string.
   * @param string $default  Default string when ID is not found.
   * @return string  Translated string.
   */
  public function id($id,$tags = null,$default = false){
    return $this->str($this->getStr($id,$default),$tags);
  }
 
  public function fragment($id){
    $fragments = $this->session->fragments ?: [];
    $fragment = $fragments[$id] ?? false;
    unset($fragments[$id]);
    $this->session->fragments = $fragments;
    return $fragment;
  }
 
  protected function getRegex(){
    if(!$this->_regex){
      $this->_regex = '/\\[(';
      foreach($this->types as $type) $this->_regex .= preg_quote($type,'/') . '|';
      $this->_regex .=
        '\\{\\w+\\})?' . //type
        '(\\w[\\w\\-\\/\\.]*\\w|\\w+)' . //tag
        '(==|!=|>=?|<=?|=?%|-?\\*-?|!\\*|[\\/!]\\/)?' . //operator
        '([^\\[\\]]*)' . //params
        '\\]/';
    }
    return $this->_regex;
  }
 
  protected function setTags($value){
    $this->_tags = $value === false ? [] : array_merge($this->_tags,$value);
  }
 
  protected function getTypes(){
    if(!$this->_types){
      $this->_types = [];
      foreach($this->constants('TYPE_') as $name => $value) $this->_types[strtolower($name)] = $value;
    }
    return $this->_types;
  }
 
  protected function _get($key){
    return $this->id($key);
  }
 
  public function __call($func_name,$params){
    return $this->id($func_name,array_shift($params),$params ? array_shift($params) : false);
  }
 
  public function __invoke($str,$tags = null){
    return $this->str($str,$tags);
  }
 
}