Apache Zeta Components Manual :: File Source for translation.php

Source for file translation.php

Documentation is available at translation.php

  1. <?php
  2. /**
  3.  *
  4.  * Licensed to the Apache Software Foundation (ASF) under one
  5.  * or more contributor license agreements.  See the NOTICE file
  6.  * distributed with this work for additional information
  7.  * regarding copyright ownership.  The ASF licenses this file
  8.  * to you under the Apache License, Version 2.0 (the
  9.  * "License"); you may not use this file except in compliance
  10.  * with the License.  You may obtain a copy of the License at
  11.  * 
  12.  *   http://www.apache.org/licenses/LICENSE-2.0
  13.  * 
  14.  * Unless required by applicable law or agreed to in writing,
  15.  * software distributed under the License is distributed on an
  16.  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  17.  * KIND, either express or implied.  See the License for the
  18.  * specific language governing permissions and limitations
  19.  * under the License.
  20.  *
  21.  * @license http://www.apache.org/licenses/LICENSE-2.0 Apache License, Version 2.0
  22.  * @version //autogentag//
  23.  * @filesource
  24.  * @package Translation
  25.  */
  26.  
  27. /**
  28.  * ezcTranslation is a container that holds the translated strings for a
  29.  * specific context.
  30.  *
  31.  * ezcTranslation objects are returned by the ezcTranslationManager for every
  32.  * requested context.
  33.  *
  34.  * For an example see {@link ezcTranslationManager}.
  35.  *
  36.  * @package Translation
  37.  * @version //autogentag//
  38.  * @mainclass
  39.  */
  40. {
  41.     /**
  42.      * Contains an array where the key is the original string (often
  43.      * English) and the element is an object of the class
  44.      * ezcTranslationData (a struct).
  45.      *
  46.      * @var array(string=>ezcTranslationData) 
  47.      */
  48.     private $translationMap;
  49.  
  50.     /**
  51.      * Constructs the ezcTranslation object.
  52.      *
  53.      * The constructor receives an array containing the translation elements,
  54.      * and builds up an internal map between the original string and the
  55.      * accompanying translation data.
  56.      *
  57.      * @param array(ezcTranslationData) $data 
  58.      */
  59.     function __constructarray $data )
  60.     {
  61.         $this->translationMap array();
  62.         foreach $data as $translationElement )
  63.         {
  64.             $this->translationMap[$translationElement->original$translationElement;
  65.         }
  66.     }
  67.  
  68.     /**
  69.      * Returns the replacement for the key $key from the parameters $params.
  70.      *
  71.      * The params array is an associative array in the form array('key'=>'value').
  72.      *
  73.      * This is a callback function used by the getTranslation() method for each
  74.      * matched parameter in the translated string.
  75.      *
  76.      * @param string $key 
  77.      * @param array  $params 
  78.      * @return string 
  79.      */
  80.     private function parameterCallback$keyarray $params )
  81.     {
  82.         if !isset$params[strtolower$key )) )
  83.         {
  84.             throw new ezcTranslationParameterMissingException$key );
  85.         }
  86.         $string $params[strtolower$key )];
  87.         // We use ctype_upper() here to check if the first character of the key
  88.         // is an uppercase letter. If it is then we make the first character of
  89.         // the returned translation also an upper case character. With this
  90.         // mechanism we can correctly upper case translated strings if word
  91.         // order changes. See
  92.         // {@link ezcTranslationTest::testGetStringWithParameters} for an
  93.         // example of this.
  94.         if ctype_upper$key[0) )
  95.         {
  96.             $string ucfirst$string );
  97.         }
  98.         return $string;
  99.     }
  100.  
  101.     /**
  102.      * Returns the translated version of the original string $key.
  103.      *
  104.      * This method returns a translated string and substitutes the parameters $param
  105.      * in the localized string.
  106.      *
  107.      * @throws ezcTranslationKeyNotAvailableException when the key is not
  108.      *          available in the translation definitions
  109.      * @throws ezcTranslationParameterMissingException when not enough
  110.      *          parameters are passed for a parameterized string
  111.      * @param string $key 
  112.      * @param array(string=>string)  $params 
  113.      * @return string 
  114.      */
  115.     public function getTranslation$keyarray $params array() )
  116.     {
  117.         if !isset$this->translationMap[$key) )
  118.         {
  119.             throw new ezcTranslationKeyNotAvailableException$key );
  120.         }
  121.         $translatedString $this->translationMap[$key]->translation;
  122.         // Little optimization to prevent preg if not needed, it bails out too
  123.         // if there is just a percent sign in the string without a valid
  124.         // parameter-identifier, but we can live with that.
  125.         if strstr$translatedString'%' === false )
  126.         {
  127.             return $translatedString;
  128.         }
  129.         // So we do have a possibility of a parameterized string, replace those
  130.         // with the parameters. The callback function can actually throw an
  131.         // exception to tell that there was a missing parameter.
  132.         return (string) preg_replace'@%(([A-Za-z][a-z_]*[a-z])|[1-9])@e''$this->parameterCallback("\\1", $params)'$translatedString );
  133.     }
  134.  
  135.     /**
  136.      * Returns the replacement for the key $key from the parameters $params.
  137.      *
  138.      * The params array is an associative array in the form array('key'=>'value').
  139.      *
  140.      * This is a callback function used by the compileTranslation() method for each
  141.      * matched parameter in the translated string.
  142.      *
  143.      * @param string $key 
  144.      * @param array  $params 
  145.      * @return string 
  146.      */
  147.     private function parameterCallbackCompile$keyarray $params )
  148.     {
  149.         if !isset$params[strtolower$key )) )
  150.         {
  151.             throw new ezcTranslationParameterMissingException$key );
  152.         }
  153.         // We use ctype_upper() here to check if the first character of the key
  154.         // is an uppercase letter. If it is then we make the first character of
  155.         // the returned translation also an upper case character. With this
  156.         // mechanism we can correctly upper case translated strings if word
  157.         // order changes. See
  158.         // {@link ezcTranslationTest::testGetStringWithParameters} for an
  159.         // example of this.
  160.         if ctype_upper$key[0) )
  161.         {
  162.             $string "' . ucfirst("$params[strtolower$key )") . '";
  163.         }
  164.         else
  165.         {
  166.             $string "' . "$params[strtolower$key )" . '";
  167.         }
  168.         return $string;
  169.     }
  170.  
  171.     /**
  172.      * Returns the translated version of the original string $key.
  173.      *
  174.      * This method returns a translated string and substitutes the parameters $param
  175.      * in the localized string with PHP code to place the variable data into
  176.      * the string at a later moment. Instead of the values for each of the
  177.      * parameters, an expression to get to the data should be sumbitted into
  178.      * the $params array.
  179.      *
  180.      * <code>
  181.      * echo $translation->compileTranslation( "Hello #%nr", array( "nr" => '$this->send->nr' ) );
  182.      * </code>
  183.      *
  184.      * Will return something like:
  185.      * <code>
  186.      * 'Hallo #' . $this->send->nr . ''
  187.      * </code>
  188.      *
  189.      * @param string $key 
  190.      * @param array(string=>string)  $params 
  191.      * @return string 
  192.      */
  193.     public function compileTranslation$keyarray $params array() )
  194.     {
  195.         if !isset$this->translationMap[$key) )
  196.         {
  197.             throw new ezcTranslationKeyNotAvailableException$key );
  198.         }
  199.         $translatedString var_export$this->translationMap[$key]->translationtrue );
  200.         // Little optimization to prevent preg if not needed, it bails out too
  201.         // if there is just a percent sign in the string without a valid
  202.         // parameter-identifier, but we can live with that.
  203.         if strstr$translatedString'%' === false )
  204.         {
  205.             return $translatedString;
  206.         }
  207.         // So we do have a possibility of a parameterized string, replace those
  208.         // with the parameters. The callback function can actually throw an
  209.         // exception to tell that there was a missing parameter.
  210.         return (string) preg_replace'@%(([A-Za-z][a-z_]*[a-z])|[1-9])@e''$this->parameterCallbackCompile("\\1", $params)'$translatedString );
  211.     }
  212. }
  213. ?>
Documentation generated by phpDocumentor 1.4.3