spunQ_Language Class Reference

Performs language localization. More...

List of all members.

Public Member Functions

__construct ()

Constructor.

setLocale (spunQ_Locale $locale)

getLocale ()

setFallbackLocale ($locale)

translate ($string, $parameters=array())

Translates a string as described in the class doc.

loadFolder ($folder, $overlay, $prefix)

loadFile (spunQ_File $file, $prefix= '')

Loads the translation from a language file.

doTranslation ($string, $args)

Does the actual translation.

Static Public Member Functions

static getSystemLanguage ()

Will get the system language.

static get (spunQ_Locale $locale)

static readTranslations ($file, $prefix)

Processes a file line by line.

Public Attributes

const MAX_RECURSION = 10

Maximum level of recursion during translation.

Protected Member Functions

loadFilesForKey ($key)

replaceUsingIntl ($string, $args)

Inject arguments using the intl extension.

replaceUsingStrReplace ($string, $args)

Inject arguments using the php function str_replace().

Static Protected Member Functions

static adjustVariables (&$translations, $prefix)

Will alter variables to reference the prefixed keys.

Protected Attributes

$locale

The locale of this language.

$fallbackLocale

The fallback locale.

$cache

A short-term cache for translations and already-issued warnings.

Static Protected Attributes

static $system = NULL

The language to output the system's messages in.

static $instances = array()

Private Member Functions

replaceVariables ($string, $callCount=0)

Replaces all variables in a target string.

replaceVariable (&$string, $name, $value)

Replaces a variable with its value.

Private Attributes

$dictionary = array()

An associative array containing string mappings.

Detailed Description

Performs language localization.

After being configured, language objects can be used to do mappings from strings to other strings with variable substitution. A variable is defined as a string encapsulated in curly brackets. A variable may reference other keys in the dictionary or parameters as a numeric value starting at 1. Example:

   $language->addTranslation('tellname', 'my name is {1}');
   $language->addTranslation('introduce', 'hi, {tellname}');
   echo $language->translate('introduce', 'Richard');
   # -> 'hi, my name is Richard'.

To avoid variable substitution use a backslash before the first bracket: Strings that have not been defined will be returned unprocessed. Any additional parameters to the translation will be appended to the string in brackets.

   $language->translate('undefined');
   # -> 'undefined'
   $language->translate('undefined', 'param1', 'param2');
   # -> 'undefined(param1, param2)'

Todo:: docs are outdated
move system language into the spunQ class.

Definition at line 65 of file Language.class.php.

Member Function Documentation

static spunQ_Language::adjustVariables	(	&$	translations,
		$	prefix
	)			`[static, protected]`

Will alter variables to reference the prefixed keys.

When all keys are prefixed, the variables in the translations will not reference the altered keys anymore. This function corrects that state by altering variable names.

   prefix.key=translation with {var}
   # will become
   prefix.key=translation with {prefix.var}

Parameters:

	$translations	The translations that were extracted.
	$prefix	The strign that was prefixed to all keys.

Returns:: void Note: The first parameter is taken as a reference.

Definition at line 164 of file Language.class.php.

spunQ_Language::doTranslation	(	$	string,
		$	args
	)

Does the actual translation.

Parameters:

	$string	The string to be translated
	$args	The arguments to the translated string.

Returns:: string

Definition at line 297 of file Language.class.php.

static spunQ_Language::getSystemLanguage ( ) [static]

Will get the system language.

The locale of the system language is defined by spunQ_Locale::getSystemLocale().

Returns:: spunQ_Language

Definition at line 86 of file Language.class.php.

spunQ_Language::loadFile	(	spunQ_File $	file,
		$	prefix = `''`
	)

Loads the translation from a language file.

Parameters:

	$file	The file conatining the translations.
	$prefix	The string to prepend to each key. The prefix will be seperated from the actual key with a dot.

Returns:: void

Exceptions:

spunQ.FileFormatException

Todo:: implement caching

Definition at line 286 of file Language.class.php.

static spunQ_Language::readTranslations	(	$	file,
		$	prefix
	)			`[static]`

Processes a file line by line.

Parameters:

	$file	The file to process.
	$prefix	The string to prepend to all translation keys.

Returns:: map<string,string> All found translations, with adjusted keys.

Definition at line 111 of file Language.class.php.

spunQ_Language::replaceUsingIntl	(	$	string,
		$	args
	)			`[protected]`

Inject arguments using the intl extension.

Parameters:

	$string	A string, that was sucessfully found in the dictionary.
	$args	The translation arguments.

Returns:: string $string with replaced parameters.

Definition at line 345 of file Language.class.php.

spunQ_Language::replaceUsingStrReplace	(	$	string,
		$	args
	)			`[protected]`

Inject arguments using the php function str_replace().

Parameters:

	$string	A string, that was sucessfully found in the dictionary.
	$args	The translation arguments.

Returns:: string $string with replaced parameters.

Definition at line 392 of file Language.class.php.

spunQ_Language::replaceVariable	(	&$	string,
		$	name,
		$	value
	)			`[private]`

Replaces a variable with its value.

No recursion is done here, just simple string replacement.

Parameters:

	$string	the string to do the substituion for. Note that this is a string reference and that this method does not return anything.
	$name	Name of the variable to substitute.
	$value	The value to set the variable to.

Returns:: void

Definition at line 445 of file Language.class.php.

spunQ_Language::replaceVariables	(	$	string,
		$	callCount = `0`
	)			`[private]`

Replaces all variables in a target string.

Parameters:

	$string	The string to do the variable replacements for.
	$callCount	Incremented at each recursive call to identify nesting level. Once this value reaches the value defined in MAX_RECURSION, the translation will issue a warning to the logger and abort the translation. This is implemented to circumvent self-referencing variables or variable pairs that reference each other.

Returns:: string

Exceptions:

InfiniteRecursionException

if MAX_RECURSION is hit

Definition at line 409 of file Language.class.php.

spunQ_Language::translate	(	$	string,
		$	parameters = `array()`
	)

Translates a string as described in the class doc.

See also:: http://icu-project.org/apiref/icu4c/classMessageFormat.html#_details
http://icu-project.org/apiref/icu4c/classSimpleDateFormat.html

Parameters:

	$string	The string to be translated
	$parameters	The parameters to use for the translation.

Returns:: The translated string.

Definition at line 244 of file Language.class.php.

Member Data Documentation

spunQ_Language::$cache [protected]

A short-term cache for translations and already-issued warnings.

Type:: spunQ_VariableCache

Definition at line 204 of file Language.class.php.

spunQ_Language::$dictionary = array() [private]

An associative array containing string mappings.

This will possibly be substituted by a spunQ_Map in the future.

Definition at line 198 of file Language.class.php.

spunQ_Language::$fallbackLocale [protected]

The fallback locale.

Will be used if there is no translation for the locale.

Type:: string

Definition at line 192 of file Language.class.php.

spunQ_Language::$locale [protected]

The locale of this language.

Will be passed to the intl extension for translations.

Type:: spunQ_Locale

Definition at line 185 of file Language.class.php.

spunQ_Language::$system = NULL [static, protected]

The language to output the system's messages in.

Exception messages are translated into this language.

Type:: spunQ_Language

Definition at line 78 of file Language.class.php.

const spunQ_Language::MAX_RECURSION = 10

Maximum level of recursion during translation.

See also:: doTranslation()

Definition at line 71 of file Language.class.php.

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

Language.class.php


Public Member Functions
	__construct ()
	Constructor.
	setLocale (spunQ_Locale $locale)
	getLocale ()
	setFallbackLocale ($locale)
	translate ($string, $parameters=array())
	Translates a string as described in the class doc.
	loadFolder ($folder, $overlay, $prefix)
	loadFile (spunQ_File $file, $prefix= '')
	Loads the translation from a language file.
	doTranslation ($string, $args)
	Does the actual translation.
Static Public Member Functions
static	getSystemLanguage ()
	Will get the system language.
static	get (spunQ_Locale $locale)
static	readTranslations ($file, $prefix)
	Processes a file line by line.
Public Attributes
const	MAX_RECURSION = 10
	Maximum level of recursion during translation.
Protected Member Functions
	loadFilesForKey ($key)
	replaceUsingIntl ($string, $args)
	Inject arguments using the intl extension.
	replaceUsingStrReplace ($string, $args)
	Inject arguments using the php function str_replace().
Static Protected Member Functions
static	adjustVariables (&$translations, $prefix)
	Will alter variables to reference the prefixed keys.
Protected Attributes
	$locale
	The locale of this language.
	$fallbackLocale
	The fallback locale.
	$cache
	A short-term cache for translations and already-issued warnings.
Static Protected Attributes
static	$system = NULL
	The language to output the system's messages in.
static	$instances = array()
Private Member Functions
	replaceVariables ($string, $callCount=0)
	Replaces all variables in a target string.
	replaceVariable (&$string, $name, $value)
	Replaces a variable with its value.
Private Attributes
	$dictionary = array()
	An associative array containing string mappings.