turbocommons-php-3.12.0
Back to top  

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 location

get(string $key,string $bundle = '',string $location = '',string|array $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.

$location

string

In case we have multiple bundles with the same name on different locations, we can set this parameter with the location label 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

string|array

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 $location = '', $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

$location

\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 $location = '', $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

$location

\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 $location = '', $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

$location

\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 $location = '', $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

$location

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

$toReplace

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

initialize(mixed $locationsLoader,array $locales,array $locations,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

$locationsLoader

mixed

An instance of HTTPManager or FilesManager that will be used to load the provided locations. If we are working with paths that are urls, we will pass here an HTTPManager. If we are working with file system paths, we will pass a FilesManager. (Note that FilesManager class is part of the TurboDepot library)

$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.

$locations

array

A list (sorted by preference) where each item defines a translations location and must have three properties:

  • label: A name that will be used to reference the location
  • path: A relative or absolute string that defines a location where resourcebundles reside. It must contain some wildcards:
    • $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/enUS/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.
  • bundles: The list of bundles to be loaded from the specified path

$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.

Check if the class has been correctly initialized

isInitialized()

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

This list is the same as the locales() one, but containing only the language part of each locale (the first two digits)

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

Loads on the specified location the translation data for the specified bundles.

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

This method can only be called after the class has been initialized in case we need to refresh or add more bundles to an already loaded location.

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

Arguments

$bundles

array

List of bundles to load from the specified location

$location

string

The label for an already defined location. The extra bundles translation data will be added to the already loaded ones. If not defined, the current active location will be used.

$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 locales to the end of the list of currently active locales and load its related 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 load the translations for more languages. If any of the provided new locales is already loaded, its translation data will be refreshed

Arguments

$locales

array

List of languages for which we want to load the translations. The list will be appended at the end of any previously loaded locales and included in the preferred translation order. The translation data will be loaded from all the currently defined locations.

$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 (moving all the others one position to the right).

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 currently loaded, an exception will happen.

Moves the locales that match the specified languages to the beginning of the locales list.

setPrimaryLanguages(array $languages): void

Works the same as setPrimaryLocales() but with a list of the 2 digit language codes that match the respective locales.

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

Arguments

$languages

array

A list of 2 digit language codes to be moved to the beginning of the translation priority. If any of the specified languages does not match with a locale that is currently loaded, an exception will happen.

Define the locale that will be placed at the front of the currently loaded locales list (moving all the others one position to the right).

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.

Moves the specified locales to the beginning of the locales list. This also alters the translation priority by setting the first provided locale as the most prioritary, the second as the next one and so.

setPrimaryLocales(array $locales): void

This method basically works exactly the same way as setPrimaryLocale but letting us add many locales at once.

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

Arguments

$locales

array

A list of locales to be moved to the beginning of the translation priority. First locales item will be the prefered locale for translation, second will be the next one in case some key is not translated for the first one and so. If any of the specified locales 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)

If set to true, when we call any get method from this class to retrieve a translated text, we will be forced to provide the bundle for the key we are looking for. If set to false, only the key parameter will be required.

isBundleMandatory :

Type(s)