LocalizationManager

Extends \org\turbocommons\src\main\php\model\BaseStrictClass

Fully featured translation manager to be used with any application that requires text internationalization.

package

Default

Methods

Protection to prevent accessing undefined properties to this class

__get(string $name) : void
inherited

Arguments

$name

string

The property name

Protection to prevent creating extra properties to this class

__set(string $name, string $value) : void
inherited

Arguments

$name

string

The property name

$value

string

The property value

Get the bundle that is currently being used by default when traslating texts

activeBundle() : string

Response

string

The name for the currently active bundle

Get the translation for the given key, bundle and path

get(string $key, string $bundle = '', string $path = '', mixed $toReplace = array()) : string

Arguments

$key

string

The key we want to read from the specified resource bundle and path

$bundle

string

The name for the resource bundle file. If not specified, the value that was used on the inmediate previous call of this method will be used. This can save us lots of typing if we are reading multiple consecutive keys from the same bundle.

$path

string

In case we have multiple bundles with the same name on different paths, we can set this parameter with the path value to uniquely reference the bundle and resolve the conflict. If all of our bundles have different names, this parameter can be ignored. Just like the bundle parameter, this one is remembered between get() calls.

$toReplace

mixed

A list of values that will replace the wildcards that are found on the translated text. Each wildcard will be replaced with the element whose index on the list matches it. Check the documentation for this.wildCardsFormat property to know more about how to setup wildcards.

Response

string

The localized text

Get the translation for the given key and bundle as an all lower case string

getAllLowerCase(\org\turbocommons\src\main\php\managers\string $key, \org\turbocommons\src\main\php\managers\string $bundle = '', \org\turbocommons\src\main\php\managers\string $path = '',  $toReplace = array()) 
see \org\turbocommons\src\main\php\managers\LocalizationManager::get \org\turbocommons\src\main\php\utils\StringUtils::formatCase
returns

string The localized and case formatted text

Arguments

$key

\org\turbocommons\src\main\php\managers\string

$bundle

\org\turbocommons\src\main\php\managers\string

$path

\org\turbocommons\src\main\php\managers\string

$toReplace

Get the translation for the given key and bundle as an all upper case string

getAllUpperCase(\org\turbocommons\src\main\php\managers\string $key, \org\turbocommons\src\main\php\managers\string $bundle = '', \org\turbocommons\src\main\php\managers\string $path = '',  $toReplace = array()) 
see \org\turbocommons\src\main\php\managers\LocalizationManager::get \org\turbocommons\src\main\php\utils\StringUtils::formatCase
returns

string The localized and case formatted text

Arguments

$key

\org\turbocommons\src\main\php\managers\string

$bundle

\org\turbocommons\src\main\php\managers\string

$path

\org\turbocommons\src\main\php\managers\string

$toReplace

Get the translation for the given key and bundle as a string with the first character as Upper case and all the rest as lower case

getFirstUpperRestLower(\org\turbocommons\src\main\php\managers\string $key, \org\turbocommons\src\main\php\managers\string $bundle = '', \org\turbocommons\src\main\php\managers\string $path = '',  $toReplace = array()) 
see \org\turbocommons\src\main\php\managers\LocalizationManager::get \org\turbocommons\src\main\php\utils\StringUtils::formatCase
returns

string The localized and case formatted text

Arguments

$key

\org\turbocommons\src\main\php\managers\string

$bundle

\org\turbocommons\src\main\php\managers\string

$path

\org\turbocommons\src\main\php\managers\string

$toReplace

Get the translation for the given key and bundle as a string with all words first character capitalized and all the rest of the word with lower case

getStartCase(\org\turbocommons\src\main\php\managers\string $key, \org\turbocommons\src\main\php\managers\string $bundle = '', \org\turbocommons\src\main\php\managers\string $path = '',  $toReplace = array()) 
see \org\turbocommons\src\main\php\managers\LocalizationManager::get \org\turbocommons\src\main\php\utils\StringUtils::formatCase
returns

string The localized and case formatted text

Arguments

$key

\org\turbocommons\src\main\php\managers\string

$bundle

\org\turbocommons\src\main\php\managers\string

$path

\org\turbocommons\src\main\php\managers\string

$toReplace

Performs the initial data load by looking for resource bundles on all the specified paths.

initialize( $pathsManager, array $locales, array $bundles, callable $finishedCallback = null, callable $progressCallback = null) : void

All the translations will be loaded for each of the specified locales.

Calling this method is mandatory before starting to use this class.

Arguments

$pathsManager

$locales

array

List of languages for which we want to load the translations. The list also defines the preferred translation order when a specified key is not found for a locale.

$bundles

array

A structure containing a list with the association between paths and their respective bundles. Each path is a relative or absolute string that defines a location where resourcebundles reside and must contain wildcards to define how locales and bundles are structured:

  • $locale wildcard will be replaced by each specific locale when trying to reach a path
  • $bundle wildcard will be replaced by each specific bundle name when trying to reach a path

     Example1: 'myFolder/$locale/$bundle.txt' will resolve to
               'myFolder/en_US/Customers.txt' when trying to load the Customers bundle for US english locale.
    
     Example2: 'myFolder/$bundle_$locale.properties' will resolve to
               'myFolder/Customers_en_US.properties' when trying to load the Customers bundle for US english locale.

$finishedCallback

callable

A method that will be executed once the initialization ends. An errors variable will be passed to this method containing an array with information on errors that may have happened while loading the data.

$progressCallback

callable

A method that can be used to track the loading progress when lots of bundles and locales are used.

Checks if the specified 2 digit language is currently loaded for the currently defined bundles and paths.

isLanguageLoaded(string $language) : boolean

Arguments

$language

string

A language to check. For example 'en'

Response

boolean

True if the language is currently loaded on the class, false if not.

Checks if the specified locale is currently loaded for the currently defined bundles and paths.

isLocaleLoaded(string $locale) : boolean

Arguments

$locale

string

A locale to check. For example 'en_US'

Response

boolean

True if the locale is currently loaded on the class, false if not.

A list of strings containing the languages that are used by this class to translate the given keys, sorted by preference.

languages() 

Each string is formatted as a 2 digit language code, like: en, fr

see \org\turbocommons\src\main\php\managers\LocalizationManager::locales()

Adds extra bundles to the currently loaded translation data

loadBundles(string $path, array $bundles, callable $finishedCallback = null, callable $progressCallback = null) : void

This method can only be called after the class has been initialized in case we need to add more bundles to the loaded translations.

see \org\turbocommons\src\main\php\managers\LocalizationManager::initialize()

Arguments

$path

string

The path where the extra bundles to load are located. See initialize method for information about the path format.

$bundles

array

List of bundles to load from the specified path

$finishedCallback

callable

A method that will be executed once the load ends. An errors variable will be passed to this method containing an array with information on errors that may have happened while loading the data.

$progressCallback

callable

A method that can be used to track the loading progress when lots of bundles and locales are used.

Adds extra languages to the list of currently loaded translation data.

loadLocales(array $locales, callable $finishedCallback = null, callable $progressCallback = null) : void

This method can only be called after the class has been initialized in case we need to add more translations.

Arguments

$locales

array

List of languages for which we want to load the translations. The list will be appended to any previously loaded locales and included in the preferred translation order.

$finishedCallback

callable

A method that will be executed once the load ends. An errors variable will be passed to this method containing an array with information on errors that may have happened while loading the data.

$progressCallback

callable

A method that can be used to track the loading progress when lots of bundles and locales are used.

A list of strings containing the locales that are used by this class to translate the given keys, sorted by preference.

locales() 

Each string is formatted as a standard locale code with language and country joined by an underscore, like: en_US, fr_FR

When a key and bundle are requested for translation, the class will check on the first language of this list for a translated text. If missing, the next one will be used, and so. This list is constructed after the initialize or loadLocales methods are called.

example

After loading the following list of locales ['en_US', 'es_ES', 'fr_FR'] if we call localizationManager.get('HELLO', 'Greetings') the localization manager will try to locate the en_US value for the HELLO tag on the Greetings bundle. If the tag is not found for the specified locale and bundle, the same search will be performed for the es_ES locale, and so, till a value is found or no more locales are defined.

Get the first language from the list of loaded locales, which is the currently used to search for translated texts.

primaryLanguage() : string

Response

string

The 2 digit language code that is defined as the primary one. For example: en, es, ..

Get the first locale from the list of loaded locales, which is the currently used to search for translated texts.

primaryLocale() : string

Response

string

The locale that is defined as the primary one. For example: en_US, es_ES, ..

Define the bundle that is used by default when no bundle is specified on the get methods

setActiveBundle(string $bundle) : void

Arguments

$bundle

string

A currently loaded bundle to be used as the active one

Change the loaded locales translation preference order. The same locales that are currently loaded must be passed but with a different order to change the translation priority.

setLocalesOrder(array $locales) : void

Arguments

$locales

array

A list with the new locales translation priority

Define the 2 digit language that will be placed at the front of the currently loaded locales list.

setPrimaryLanguage(string $language) : void

This will be the first language to use when trying to get a translation.

Arguments

$language

string

A 2 digit language code that matches with any of the currently loaded locales, which will be moved to the first position of the loaded locales list. If the specified language does not match with a locale that is not currently loaded, an exception will happen.

Define the locale that will be placed at the front of the currently loaded locales list.

setPrimaryLocale(string $locale) : void

This will be the first locale to use when trying to get a translation.

Arguments

$locale

string

A currently loaded locale that will be moved to the first position of the loaded locales list. If the specified locale is not currently loaded, an exception will happen.

Properties

Defines the behaviour for get(), getStartCase(), etc.

missingKeyFormat : 

.. methods when a key is not found on a bundle or the bundle does not exist

If this value is empty, all missing keys will return an empty value If this value contains a string, all missing keys will return that string If this value contains a string with some of the following wildcards:

  • $key will be replaced with the key name. For example: get("NAME") will output [NAME] if the key is not found and missingKeyFormat = '[$key]'
  • $exception (This is the default value) will throw an exception with the problem cause description.

Type(s)

Wildcards are string fragments that are placed inside the translated texts. Their main purpose is to be replaced at runtime by custom values like for example a user name, a date, a numeric value, etc.

wildCardsFormat : 

.

This class helps with this process by including a parameter called 'toReplace' on all .get methods which allows us to specify a string or list of strings that will replace the respective wildcards on the translated text. Each wildcard must follow the format specified here, and contain a numeric digit that will be used to find the replacement text at the 'toReplace' list. For example, if we define $N as the wildcard format, and we have a translation that contains $0, $1, $2, $0 will be replaced with the first element on toReplace, $1 with the second and so.

Note that N is mandayory on the wildcards format and the first index value is 0.

Type(s)