<?php
/**
 * @copyright Copyright (C) 2005 eZ systems as. All rights reserved.
 * @license http://ez.no/licenses/new_bsd New BSD License
 * @version 1.0beta1
 * @filesource
 * @package Translation
 */
/**
 * A container to request translatable strings from.
 *
 * This object is returned by the TranslationManager for every requested
 * context.
 *
 * Example:
 * @see ezcTranslationManager for an example.
 *
 * @package Translation
 */
class ezcTranslation
{
    /**
     * @var array Contains an array where the key is the original string (often
     *      English) and the element is an object of the class
     *      ezcTranslationData (a struct).
     */
    private $translationMap;

    /**
     * Constructs the ezcTranslation object.
     *
     * The constructor receives an array containing the map between the
     * original string and the translation. This array is then stored for later
     * use.
     *
     * @param array[ezcTranslationData] $data The translation map.
     */
    function __construct( array $data )
    {
        $this->translationMap = array();
        foreach ( $data as $translationElement )
        {
            $this->translationMap[$translationElement->original] = $translationElement;
        }
    }

    /**
     * Returns the replacement for the passed in key
     *
     * This is a callback function used by the getString() method for each
     * matched parameter in the translated string.
     *
     * @param string $key    The key to lookup in the parameter array
     * @param array  $params The array with parameters for this translatable string
     * @returns string The parameter value that belongs to the $key
     */
    private function parameter_callback( $key, $params )
    {
        if ( !isset( $params[strtolower( $key )] ) )
        {
            throw new ezcTranslationException( "The parameter <%{$key}> does not exist.", ezcTranslationException::PARAMETER_MISSING );
        }
        $string = $params[strtolower( $key )];
        if ( ctype_upper( $key[0] ) )
        {
            $string = ucfirst( $string );
        }
        return $string;
    }

    /**
     * Returns a translated string.
     *
     * This method returns a translated string and substitutes parameters in
     * the localized string.
     *
     * @param string $key     The original translation.
     * @param array  $params  An associative or indexed array containing
     *                        parameters to the localized string.
     * @return string The translated string
     * @throws TranslationException when the key is not available
     * @throws TranslationException when not enough parameters are passed for a
     *                              parameterized string
     */
    public function getString( $key, $params = array() )
    {
        if ( !isset( $this->translationMap[$key] ) )
        {
            throw new ezcTranslationException( "The key <{$key}> does not exist in the translation map", ezcTranslationException::KEY_NOT_AVAILABLE );
        }
        $translatedString = $this->translationMap[$key]->translation;
        // Little optimization to prevent preg if not needed, it bails out too
        // if there is just a percent sign in the string without a valid
        // parameter-identifier, but we can live with that.
        if ( strstr( $translatedString, '%' ) === false )
        {
            return $translatedString;
        }
        // So we do have a possibility of a parameterized string, replace those
        // with the parameters. The callback function can actually throw the
        // Exception to tell that there was a missing parameter.
        return preg_replace( '@%(([A-Za-z][a-z_]*[a-z])|[1-9])@e', '$this->parameter_callback("\\1", $params)', $translatedString );
    }
}
?>