SimpleSAML\Locale\Translate Class Reference

Collaboration diagram for SimpleSAML\Locale\Translate:

Public Member Functions
	__construct (\SimpleSAML_Configuration $configuration, $defaultDictionary=null)
	Constructor. More...
	getLanguage ()
	Return the internal language object used by this translator. More...
	getTag ($tag)
	This method retrieves a tag as an array with language => string mappings. More...
	getPreferredTranslation ($translations)
	Retrieve the preferred translation of a given text. More...
	getAttributeTranslation ($name)
	Translate the name of an attribute. More...
	t ( $tag, $replacements=array(), $fallbackdefault=true, $oldreplacements=array(), $striptags=false)
	Translate a tag into the current language, with a fallback to english. More...
	includeInlineTranslation ($tag, $translation)
	Include a translation inline instead of putting translations in dictionaries. More...
	includeLanguageFile ($file, $otherConfig=null)
	Include a language file from the dictionaries directory. More...

Static Public Member Functions
static	noop ($tag)
	Mark a string for translation without translating it. More...
static	translateSingularGettext ($original)
static	translatePluralGettext ($original, $plural, $value)
static	translateFromArray ($context, $translations)
	Pick a translation from a given array of translations for the current language. More...

Private Member Functions
	getDictionary ($name)
	This method retrieves a dictionary with the name given. More...
	getStringNotTranslated ($tag, $fallbacktag)
	Return the string that should be used when no translation was found. More...
	readDictionaryJSON ($filename)
	Read a dictionary file in JSON format. More...
	readDictionaryPHP ($filename)
	Read a dictionary file in PHP format. More...
	readDictionaryFile ($filename)
	Read a dictionary file. More...

Private Attributes
	$configuration
	$langtext = array()
	$dictionaries = array()
	Associative array of dictionaries. More...
	$defaultDictionary = null
	The default dictionary. More...
	$language

Detailed Description

Definition at line 13 of file Translate.php.

Constructor & Destructor Documentation

__construct()

SimpleSAML\Locale\Translate::__construct	(	\SimpleSAML_Configuration	$configuration,
			$defaultDictionary = null
	)

Constructor.

Parameters

\SimpleSAML_Configuration	$configuration	Configuration object
string | null	$defaultDictionary	The default dictionary where tags will come from.

Definition at line 49 of file Translate.php.

References SimpleSAML\Locale\Translate\$configuration, SimpleSAML\Locale\Translate\$defaultDictionary, and SimpleSAML\Logger\warning().

    {
        $this->configuration = $configuration;
        $this->language = new Language($configuration);

        if ($defaultDictionary !== null && substr($defaultDictionary, -4) === '.php') {
            // TODO: drop this entire if clause for 2.0
            // for backwards compatibility - print warning
            $backtrace = debug_backtrace();
            $where = $backtrace[0]['file'].':'.$backtrace[0]['line'];
            \SimpleSAML\Logger::warning(
                'Deprecated use of new SimpleSAML\Locale\Translate(...) at '.$where.
                '. The last parameter is now a dictionary name, which should not end in ".php".'
            );

            $this->defaultDictionary = substr($defaultDictionary, 0, -4);
        } else {
            $this->defaultDictionary = $defaultDictionary;
        }
    }

Here is the call graph for this function:

Member Function Documentation

getAttributeTranslation()

SimpleSAML\Locale\Translate::getAttributeTranslation

(

$name

)

Translate the name of an attribute.

Parameters

string

$name

The attribute name.

Returns

string The translated attribute name, or the original attribute name if no translation was found.

Definition at line 198 of file Translate.php.

References $name, SimpleSAML\Locale\Translate\getDictionary(), and SimpleSAML\Locale\Translate\getPreferredTranslation().

    {
        // normalize attribute name
        $normName = strtolower($name);
        $normName = str_replace(":", "_", $normName);

        // check for an extra dictionary
        $extraDict = $this->configuration->getString('attributes.extradictionary', null);
        if ($extraDict !== null) {
            $dict = $this->getDictionary($extraDict);
            if (array_key_exists($normName, $dict)) {
                return $this->getPreferredTranslation($dict[$normName]);
            }
        }

        // search the default attribute dictionary
        $dict = $this->getDictionary('attributes');
        if (array_key_exists('attribute_'.$normName, $dict)) {
            return $this->getPreferredTranslation($dict['attribute_'.$normName]);
        }

        // no translations found
        return $name;
    }

Here is the call graph for this function:

getDictionary()

SimpleSAML\Locale\Translate::getDictionary (   $name )

private

This method retrieves a dictionary with the name given.

Parameters

string

$name

The name of the dictionary, as the filename in the dictionary directory, without the '.php' ending.

Returns

array An associative array with the dictionary.

Definition at line 90 of file Translate.php.

References $module, $name, SimpleSAML\Module\getModuleDir(), and SimpleSAML\Locale\Translate\readDictionaryFile().

Referenced by SimpleSAML\Locale\Translate\getAttributeTranslation(), and SimpleSAML\Locale\Translate\getTag().

    {
        assert(is_string($name));

        if (!array_key_exists($name, $this->dictionaries)) {
            $sepPos = strpos($name, ':');
            if ($sepPos !== false) {
                $module = substr($name, 0, $sepPos);
                $fileName = substr($name, $sepPos + 1);
                $dictDir = \SimpleSAML\Module::getModuleDir($module).'/dictionaries/';
            } else {
                $dictDir = $this->configuration->getPathValue('dictionarydir', 'dictionaries/');
                $fileName = $name;
            }

            $this->dictionaries[$name] = $this->readDictionaryFile($dictDir.$fileName);
        }

        return $this->dictionaries[$name];
    }

Here is the call graph for this function:

Here is the caller graph for this function:

getLanguage()

SimpleSAML\Locale\Translate::getLanguage

(

)

Return the internal language object used by this translator.

Returns

Definition at line 76 of file Translate.php.

References SimpleSAML\Locale\Translate\$language.

    {
        return $this->language;
    }

getPreferredTranslation()

SimpleSAML\Locale\Translate::getPreferredTranslation

(

$translations

)

Retrieve the preferred translation of a given text.

Parameters

array

$translations

The translations, as an associative array with language => text mappings.

Returns

string The preferred translation.

Exceptions

Definition at line 159 of file Translate.php.

References $languages.

Referenced by SimpleSAML\Locale\Translate\getAttributeTranslation(), and SimpleSAML\Locale\Translate\t().

    {
        assert(is_array($translations));

        // look up translation of tag in the selected language
        $selected_language = $this->language->getLanguage();
        if (array_key_exists($selected_language, $translations)) {
            return $translations[$selected_language];
        }

        // look up translation of tag in the default language
        $default_language = $this->language->getDefaultLanguage();
        if (array_key_exists($default_language, $translations)) {
            return $translations[$default_language];
        }

        // check for english translation
        if (array_key_exists('en', $translations)) {
            return $translations['en'];
        }

        // pick the first translation available
        if (count($translations) > 0) {
            $languages = array_keys($translations);
            return $translations[$languages[0]];
        }

        // we don't have anything to return
        throw new \Exception('Nothing to return from translation.');
    }

Here is the caller graph for this function:

getStringNotTranslated()

SimpleSAML\Locale\Translate::getStringNotTranslated (   $tag,   $fallbacktag  )

private

Return the string that should be used when no translation was found.

Parameters

string	$tag	A name tag of the string that should be returned.
boolean	$fallbacktag	If set to true and string was not found in any languages, return the tag itself. If false return null.

Returns

string The string that should be used, or the tag name if $fallbacktag is set to false.

Definition at line 335 of file Translate.php.

References $tag.

Referenced by SimpleSAML\Locale\Translate\t().

    {
        if ($fallbacktag) {
            return 'not translated ('.$tag.')';
        } else {
            return $tag;
        }
    }

Here is the caller graph for this function:

getTag()

SimpleSAML\Locale\Translate::getTag

(

$tag

)

This method retrieves a tag as an array with language => string mappings.

Parameters

string

$tag

The tag name. The tag name can also be on the form '{<dictionary>:<tag>}', to retrieve a tag from the specific dictionary.

Returns

array An associative array with language => string mappings, or null if the tag wasn't found.

Definition at line 120 of file Translate.php.

References SimpleSAML\Locale\Translate\$defaultDictionary, $tag, and SimpleSAML\Locale\Translate\getDictionary().

Referenced by SimpleSAML\Locale\Translate\t().

    {
        assert(is_string($tag));

        // first check translations loaded by the includeInlineTranslation and includeLanguageFile methods
        if (array_key_exists($tag, $this->langtext)) {
            return $this->langtext[$tag];
        }

        // check whether we should use the default dictionary or a dictionary specified in the tag
        if (substr($tag, 0, 1) === '{' && preg_match('/^{((?:\w+:)?\w+?):(.*)}$/D', $tag, $matches)) {
            $dictionary = $matches[1];
            $tag = $matches[2];
        } else {
            $dictionary = $this->defaultDictionary;
            if ($dictionary === null) {
                // we don't have any dictionary to load the tag from
                return null;
            }
        }

        $dictionary = $this->getDictionary($dictionary);
        if (!array_key_exists($tag, $dictionary)) {
            return null;
        }

        return $dictionary[$tag];
    }

Here is the call graph for this function:

Here is the caller graph for this function:

includeInlineTranslation()

SimpleSAML\Locale\Translate::includeInlineTranslation	(		$tag,
			$translation
	)

Include a translation inline instead of putting translations in dictionaries.

This function is recommended to be used ONLU from variable data, or when the translation is already provided by an external source, as a database or in metadata.

Parameters

string	$tag	The tag that has a translation
array | string	$translation	The translation array

Exceptions

Definition at line 355 of file Translate.php.

References $tag, and SimpleSAML\Logger\debug().

    {
        if (is_string($translation)) {
            $translation = array('en' => $translation);
        } elseif (!is_array($translation)) {
            throw new \Exception("Inline translation should be string or array. Is ".gettype($translation)." now!");
        }

        \SimpleSAML\Logger::debug('Template: Adding inline language translation for tag ['.$tag.']');
        $this->langtext[$tag] = $translation;
    }

Here is the call graph for this function:

includeLanguageFile()

SimpleSAML\Locale\Translate::includeLanguageFile	(		$file,
			$otherConfig = null
	)

Include a language file from the dictionaries directory.

Parameters

string	$file	File name of dictionary to include
\SimpleSAML_Configuration | null	$otherConfig	Optionally provide a different configuration object than the one provided in the constructor to be used to find the directory of the dictionary. This allows to combine dictionaries inside the SimpleSAMLphp main code distribution together with external dictionaries. Defaults to null.

Definition at line 377 of file Translate.php.

References $lang, SimpleSAML\Logger\debug(), and SimpleSAML\Locale\Translate\readDictionaryFile().

    {
        if (!empty($otherConfig)) {
            $filebase = $otherConfig->getPathValue('dictionarydir', 'dictionaries/');
        } else {
            $filebase = $this->configuration->getPathValue('dictionarydir', 'dictionaries/');
        }

        $lang = $this->readDictionaryFile($filebase.$file);
        \SimpleSAML\Logger::debug('Template: Merging language array. Loading ['.$file.']');
        $this->langtext = array_merge($this->langtext, $lang);
    }

Here is the call graph for this function:

noop()

static SimpleSAML\Locale\Translate::noop (   $tag )

static

Mark a string for translation without translating it.

Parameters

string

$tag

A tag name to mark for translation.

Returns

string The tag, unchanged.

Definition at line 231 of file Translate.php.

References $tag.

    {
        return $tag;
    }

readDictionaryFile()

SimpleSAML\Locale\Translate::readDictionaryFile (   $filename )

private

Read a dictionary file.

Parameters

string

$filename

The absolute path to the dictionary file.

Returns

array An array holding all the translations in the file.

Definition at line 453 of file Translate.php.

References $_SERVER, $filename, SimpleSAML\Logger\debug(), SimpleSAML\Logger\error(), SimpleSAML\Locale\Translate\readDictionaryJSON(), and SimpleSAML\Locale\Translate\readDictionaryPHP().

Referenced by SimpleSAML\Locale\Translate\getDictionary(), and SimpleSAML\Locale\Translate\includeLanguageFile().

    {
        assert(is_string($filename));

        \SimpleSAML\Logger::debug('Template: Reading ['.$filename.']');

        $jsonFile = $filename.'.definition.json';
        if (file_exists($jsonFile)) {
            return $this->readDictionaryJSON($filename);
        }

        $phpFile = $filename.'.php';
        if (file_exists($phpFile)) {
            return $this->readDictionaryPHP($filename);
        }

        \SimpleSAML\Logger::error(
            $_SERVER['PHP_SELF'].' - Template: Could not find dictionary file at ['.$filename.']'
        );
        return array();
    }

Here is the call graph for this function:

Here is the caller graph for this function:

readDictionaryJSON()

SimpleSAML\Locale\Translate::readDictionaryJSON (   $filename )

private

Read a dictionary file in JSON format.

Parameters

string

$filename

The absolute path to the dictionary file, minus the .definition.json ending.

Returns

array An array holding all the translations in the file.

Definition at line 398 of file Translate.php.

References $filename, $lang, and SimpleSAML\Logger\error().

Referenced by SimpleSAML\Locale\Translate\readDictionaryFile().

    {
        $definitionFile = $filename.'.definition.json';
        assert(file_exists($definitionFile));

        $fileContent = file_get_contents($definitionFile);
        $lang = json_decode($fileContent, true);

        if (empty($lang)) {
            \SimpleSAML\Logger::error('Invalid dictionary definition file ['.$definitionFile.']');
            return array();
        }

        $translationFile = $filename.'.translation.json';
        if (file_exists($translationFile)) {
            $fileContent = file_get_contents($translationFile);
            $moreTrans = json_decode($fileContent, true);
            if (!empty($moreTrans)) {
                $lang = array_merge_recursive($lang, $moreTrans);
            }
        }

        return $lang;
    }

Here is the call graph for this function:

Here is the caller graph for this function:

readDictionaryPHP()

SimpleSAML\Locale\Translate::readDictionaryPHP (   $filename )

private

Read a dictionary file in PHP format.

Parameters

string

$filename

The absolute path to the dictionary file.

Returns

array An array holding all the translations in the file.

Definition at line 431 of file Translate.php.

References $filename, and $lang.

Referenced by SimpleSAML\Locale\Translate\readDictionaryFile().

    {
        $phpFile = $filename.'.php';
        assert(file_exists($phpFile));

        $lang = null;
        include($phpFile);
        if (isset($lang)) {
            return $lang;
        }

        return array();
    }

Here is the caller graph for this function:

t()

SimpleSAML\Locale\Translate::t	(		$tag,
			$replacements = array(),
			$fallbackdefault = true,
			$oldreplacements = array(),
			$striptags = false
	)

Translate a tag into the current language, with a fallback to english.

This function is used to look up a translation tag in dictionaries, and return the translation into the current language. If no translation into the current language can be found, english will be tried, and if that fails, placeholder text will be returned.

An array can be passed as the tag. In that case, the array will be assumed to be on the form (language => text), and will be used as the source of translations.

This function can also do replacements into the translated tag. It will search the translated tag for the keys provided in $replacements, and replace any found occurrences with the value of the key.

Parameters

string | array	$tag	A tag name for the translation which should be looked up, or an array with (language => text) mappings. The array version will go away in 2.0
array	$replacements	An associative array of keys that should be replaced with values in the translated string.
boolean	$fallbackdefault	Default translation to use as a fallback if no valid translation was found.

Deprecated:

Not used in twig, gettext

Returns

string The translated tag, or a placeholder value if the tag wasn't found.

Definition at line 259 of file Translate.php.

References $tag, SimpleSAML\Locale\Translate\getPreferredTranslation(), SimpleSAML\Locale\Translate\getStringNotTranslated(), SimpleSAML\Locale\Translate\getTag(), SimpleSAML\Logger\info(), and SimpleSAML\Logger\warning().

      {
        $backtrace = debug_backtrace();
        $where = $backtrace[0]['file'].':'.$backtrace[0]['line'];
        if (!$fallbackdefault) {
            \SimpleSAML\Logger::warning(
                'Deprecated use of new SimpleSAML\Locale\Translate::t(...) at '.$where.
                '. This parameter will go away, the fallback will become' .
                ' identical to the $tag in 2.0.'
            );
        }
        if (!is_array($replacements)) {
            // TODO: remove this entire if for 2.0

            // old style call to t(...). Print warning to log
            \SimpleSAML\Logger::warning(
                'Deprecated use of SimpleSAML\Locale\Translate::t(...) at '.$where.
                '. Please update the code to use the new style of parameters.'
            );

            // for backwards compatibility
            if (!$replacements && $this->getTag($tag) === null) {
                \SimpleSAML\Logger::warning(
                    'Code which uses $fallbackdefault === FALSE should be updated to use the getTag() method instead.'
                );
                return null;
            }

            $replacements = $oldreplacements;
        }

        if (is_array($tag)) {
            $tagData = $tag;
            \SimpleSAML\Logger::warning(
                'Deprecated use of new SimpleSAML\Locale\Translate::t(...) at '.$where.
                '. The $tag-parameter can only be a string in 2.0.'
            );
        } else {
            $tagData = $this->getTag($tag);
            if ($tagData === null) {
                // tag not found
                \SimpleSAML\Logger::info('Template: Looking up ['.$tag.']: not translated at all.');
                return $this->getStringNotTranslated($tag, $fallbackdefault);
            }
        }

        $translated = $this->getPreferredTranslation($tagData);

        foreach ($replacements as $k => $v) {
            // try to translate if no replacement is given
            if ($v == null) {
                $v = $this->t($k);
            }
            $translated = str_replace($k, $v, $translated);
        }
        return $translated;
    }

Here is the call graph for this function:

translateFromArray()

static SimpleSAML\Locale\Translate::translateFromArray (   $context,   $translations  )

static

Pick a translation from a given array of translations for the current language.

Parameters

array	$context	An array of options. The current language must be specified as an ISO 639 code accessible with the key "currentLanguage" in the array.
array	$translations	An array of translations. Each translation has an ISO 639 code as its key, identifying the language it corresponds to.

Returns

null|string The translation appropriate for the current language, or null if none found. If the $context or $translations arrays are null, or $context['currentLanguage'] is not defined, null is also returned.

Definition at line 515 of file Translate.php.

References $context, $lang, and SimpleSAML_Configuration\getInstance().

    {
        if (!is_array($translations) || $translations === null) {
            return null;
        }

        if (!is_array($context) || !isset($context['currentLanguage'])) {
            return null;
        }

        if (isset($translations[$context['currentLanguage']])) {
            return $translations[$context['currentLanguage']];
        }

        // we don't have a translation for the current language, load alternative priorities
        $sspcfg = \SimpleSAML_Configuration::getInstance();
        $langcfg = $sspcfg->getConfigItem('language', null);
        $priorities = array();
        if ($langcfg instanceof \SimpleSAML_Configuration) {
            $priorities = $langcfg->getArray('priorities', array());
        }

        foreach ($priorities[$context['currentLanguage']] as $lang) {
            if (isset($translations[$lang])) {
                return $translations[$lang];
            }
        }

        // nothing we can use, return null so that we can set a default
        return null;
    }

Here is the call graph for this function:

translatePluralGettext()

static SimpleSAML\Locale\Translate::translatePluralGettext (   $original,   $plural,   $value  )

static

Definition at line 490 of file Translate.php.

References Gettext\BaseTranslator\$current, and $text.

    {
        $text = \Gettext\BaseTranslator::$current->ngettext($original, $plural, $value);

        if (func_num_args() === 3) {
            return $text;
        }

        $args = array_slice(func_get_args(), 3);

        return strtr($text, is_array($args[0]) ? $args[0] : $args);
    }

translateSingularGettext()

static SimpleSAML\Locale\Translate::translateSingularGettext (   $original )

static

Definition at line 476 of file Translate.php.

References Gettext\BaseTranslator\$current, and $text.

    {
        $text = \Gettext\BaseTranslator::$current->gettext($original);

        if (func_num_args() === 1) {
            return $text;
        }

        $args = array_slice(func_get_args(), 1);

        return strtr($text, is_array($args[0]) ? $args[0] : $args);
    }

Field Documentation

$configuration

SimpleSAML\Locale\Translate::$configuration

private

Definition at line 21 of file Translate.php.

Referenced by SimpleSAML\Locale\Translate\__construct().

$defaultDictionary

SimpleSAML\Locale\Translate::$defaultDictionary = null

private

The default dictionary.

Definition at line 33 of file Translate.php.

Referenced by SimpleSAML\Locale\Translate\__construct(), and SimpleSAML\Locale\Translate\getTag().

$dictionaries

SimpleSAML\Locale\Translate::$dictionaries = array()

private

Associative array of dictionaries.

Definition at line 28 of file Translate.php.

$langtext

SimpleSAML\Locale\Translate::$langtext = array()

private

Definition at line 23 of file Translate.php.

$language

SimpleSAML\Locale\Translate::$language

private

Definition at line 40 of file Translate.php.

Referenced by SimpleSAML\Locale\Translate\getLanguage().

---

The documentation for this class was generated from the following file:

• libs/composer/vendor/simplesamlphp/simplesamlphp/lib/SimpleSAML/Locale/Translate.php