<?php
/* $Id$ */
namespace Mammut\Locale;

(defined('MAMMUT') && (basename(__FILE__) != basename($_SERVER['PHP_SELF']))) or die('ACCESS DENIED');

/**
 * Translator interface
 *
 * @author Stefan Daurer <s.daurer@q-spot.org>
 * @package Mammut\Locale
 */
interface iTranslate {
	
	/**
	 * Genderfree variant of text (family/company/undefined)
	 * @var string
	 */
	const UNDEF = 'u';
	/**
	 * Male variant of text
	 * @var string
	 */
	const MALE = 'm';
	/**
	 * Female variant of text
	 * @var string
	 */
	const FEMALE = 'f';

	/**
	 * Add a lookup fallback.
	 *
	 * Add a fallback in the case that the requested is not avaible in the current implementation.
	 *
	 * @param iTranslate $fallback
	 *        	a iTranslate object
	 */
	public function addFallback(iTranslate $fallback);
	
	/**
	 * Remove all fallbacks
	 */
	public function clearFallbacks();
	
	/**
	 * Searches the selected key in the translation.
	 *
	 * @param string $key
	 *        	text base or key to search
	 * @param array $values
	 *        	count parameter value for the lookup
	 * @return string the translated text or the key itself
	 */
	public function tr($key, array $param = [], $nullOnFail = false);

	/**
	 * Searches the genderized selected key in the translation.
	 *
	 * @param string $key
	 *        	text base or key to search
	 * @param string $gender
	 *        	genderized selection value for the lookup
	 * @param array $values
	 *        	count parameter value for the lookup
	 * @return string the translated text or the key itself
	 */
	public function trg($key, $gender, array $param = [], $nullOnFail = false);
	
	/**
	 * Searches the numberized selected key in the translation.
	 *
	 * @param string $key
	 *        	text base or key to search
	 * @param int $count
	 *        	count parameter value for the lookup
	 * @param array $values
	 *        	count parameter value for the lookup
	 * @return string the translated text or the key itself
	 */
	public function trn($key, $count, array $param = [], $nullOnFail = false);
}