Fully featured translation manager to be used with any application that requires text internationalization.
package |
Default |
---|
__get(string $name) : void
string
The property name
__set(string $name, string $value) : void
string
The property name
string
The property value
activeBundle() : string
string
The name for the currently active bundle
get(string $key, string $bundle = '', string $path = '', mixed $toReplace = array()) : string
string
The key we want to read from the specified resource bundle and path
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.
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.
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.
string
The localized text
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 |
\org\turbocommons\src\main\php\managers\string
\org\turbocommons\src\main\php\managers\string
\org\turbocommons\src\main\php\managers\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 |
\org\turbocommons\src\main\php\managers\string
\org\turbocommons\src\main\php\managers\string
\org\turbocommons\src\main\php\managers\string
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 |
\org\turbocommons\src\main\php\managers\string
\org\turbocommons\src\main\php\managers\string
\org\turbocommons\src\main\php\managers\string
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 |
\org\turbocommons\src\main\php\managers\string
\org\turbocommons\src\main\php\managers\string
\org\turbocommons\src\main\php\managers\string
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.
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.
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:
$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.
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.
callable
A method that can be used to track the loading progress when lots of bundles and locales are used.
isInitialized()
isLanguageLoaded(string $language) : boolean
string
A language to check. For example 'en'
boolean
True if the language is currently loaded on the class, false if not.
isLocaleLoaded(string $locale) : boolean
string
A locale to check. For example 'en_US'
boolean
True if the locale is currently loaded on the class, false if not.
languages()
Each string is formatted as a 2 digit language code, like: en, fr
see | \org\turbocommons\src\main\php\managers\LocalizationManager::locales() |
---|---|
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() |
---|
string
The path where the extra bundles to load are located. See initialize method for information about the path format.
array
List of bundles to load from the specified path
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.
callable
A method that can be used to track the loading progress when lots of bundles and locales are used.
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.
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.
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.
callable
A method that can be used to track the loading progress when lots of bundles and locales are used.
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. |
---|---|
primaryLanguage() : string
string
The 2 digit language code that is defined as the primary one. For example: en, es, ..
primaryLocale() : string
string
The locale that is defined as the primary one. For example: en_US, es_ES, ..
setActiveBundle(string $bundle) : void
string
A currently loaded bundle to be used as the active one
setLocalesOrder(array $locales) : void
array
A list with the new locales translation priority
setPrimaryLanguage(string $language) : void
This will be the first language to use when trying to get a translation.
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.
setPrimaryLocale(string $locale) : void
This will be the first locale to use when trying to get a translation.
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.
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:
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.
isBundleMandatory :