Class TranslatorRegistry
Constructs and stores instances of translators that can be retrieved by name and locale.
Constants
-
stringDEFAULT_BUCKET ¶'_default_'Bucket key used for in-memory lookups when no cache key prefix is set.
-
stringFALLBACK_LOADER ¶'_fallback'Fallback loader name.
-
stringPREFIX_PATTERN ¶'/^[A-Za-z0-9._-]+$/'Pattern of characters allowed in a cache key prefix.
Restricted to the subset that every built-in CakePHP cache engine accepts and that never collides with PSR-16 reserved characters.
Property Summary
-
$_cacher protected
(Psr\SimpleCache\CacheInterface&Cake\Cache\CacheEngineInterface)|nullA CacheEngine object that is used to remember translator across requests.
-
$_defaultFormatter protected
stringThe name of the default formatter to use for newly created translators from the fallback loader
-
$_loaders protected
array<callable>A list of loader functions indexed by domain name. Loaders are callables that are invoked as a default for building translation packages where none can be found for the combination of translator name and locale.
-
$_useFallback protected
boolUse fallback-domain for translation loaders.
-
$cacheKeyPrefix protected
Closure|stringCache key prefix segment used to isolate translations, e.g. per tenant.
-
$formatters protected
Cake\I18n\FormatterLocatorA formatter locator.
-
$locale protected
stringThe current locale code.
-
$packages protected
Cake\I18n\PackageLocatorA package locator.
-
$registry protected
array<string, array<string, array<string, \Cake\I18n\Translator>>>A registry to retain translator objects, keyed by prefix bucket, name and locale.
Method Summary
-
__construct() public
Constructor.
-
_getTranslator() protected
Gets a translator from the registry by package for a locale.
-
assertValidPrefix() protected
Validates a prefix string.
-
clear() public
Drops all in-memory translator instances.
-
createInstance() protected
Create translator instance.
-
defaultFormatter() public
Sets the name of the default messages formatter to use for future translator instances.
-
get() public
Gets a translator from the registry by package for a locale.
-
getFormatters() public
An object of type FormatterLocator
-
getLocale() public
Returns the default locale code.
-
getPackages() public
Returns the translator packages
-
registerLoader() public
Registers a loader function for a package name that will be used as a fallback in case no package with that name can be found.
-
resolveCacheKeyPrefix() protected
Resolves the current cache key prefix value.
-
setCacheKeyPrefix() public
Sets a prefix segment added to translator cache keys and in-memory lookup buckets.
-
setCacher() public
Sets the CacheEngine instance used to remember translators across requests.
-
setFallbackPackage() public
Set fallback domain for package.
-
setLoaderFallback() public
Set domain fallback for loader.
-
setLocale() public
Sets the default locale code.
-
useFallback() public
Set if the default domain fallback is used.
Method Detail
__construct() ¶ public
__construct(Cake\I18n\PackageLocator $packages, Cake\I18n\FormatterLocator $formatters, string $locale)Constructor.
Parameters
-
Cake\I18n\PackageLocator$packages The package locator.
-
Cake\I18n\FormatterLocator$formatters The formatter locator.
-
string$locale The default locale code to use.
_getTranslator() ¶ protected
_getTranslator(string $name, string $locale): Cake\I18n\TranslatorGets a translator from the registry by package for a locale.
Parameters
-
string$name The translator package to retrieve.
-
string$locale The locale to use; if empty, uses the default locale.
Returns
Cake\I18n\TranslatorA translator object.
assertValidPrefix() ¶ protected
assertValidPrefix(string $prefix): voidValidates a prefix string.
Parameters
-
string$prefix The value to check.
Returns
voidThrows
InvalidArgumentExceptionWhen the value does not match the allowed pattern.
clear() ¶ public
clear(): voidDrops all in-memory translator instances.
Does not touch the persistent cache or any configured prefix/cacher. Intended for long-running workers that switch tenants between jobs and want to bound memory growth.
Returns
voidcreateInstance() ¶ protected
createInstance(string $name, string $locale): Cake\I18n\TranslatorCreate translator instance.
Parameters
-
string$name The translator package to retrieve.
-
string$locale The locale to use; if empty, uses the default locale.
Returns
Cake\I18n\TranslatorA translator object.
defaultFormatter() ¶ public
defaultFormatter(string|null $name = null): stringSets the name of the default messages formatter to use for future translator instances.
If called with no arguments, it will return the currently configured value.
Parameters
-
string|null$name optional The name of the formatter to use.
Returns
stringThe name of the formatter.
get() ¶ public
get(string $name, string|null $locale = null): Cake\I18n\Translator|nullGets a translator from the registry by package for a locale.
Parameters
-
string$name The translator package to retrieve.
-
string|null$locale optional The locale to use; if empty, uses the default locale.
Returns
Cake\I18n\Translator|nullA translator object.
Throws
Cake\I18n\Exception\I18nExceptionIf no translator with that name could be found for the given locale.
getFormatters() ¶ public
getFormatters(): Cake\I18n\FormatterLocatorAn object of type FormatterLocator
Returns
Cake\I18n\FormatterLocatorgetPackages() ¶ public
getPackages(): Cake\I18n\PackageLocatorReturns the translator packages
Returns
Cake\I18n\PackageLocatorregisterLoader() ¶ public
registerLoader(string $name, callable $loader): voidRegisters a loader function for a package name that will be used as a fallback in case no package with that name can be found.
Loader callbacks will get as first argument the package name and the locale as the second argument.
Parameters
-
string$name The name of the translator package to register a loader for
-
callable$loader A callable object that should return a Package
Returns
voidresolveCacheKeyPrefix() ¶ protected
resolveCacheKeyPrefix(string $name, string $locale): stringResolves the current cache key prefix value.
Parameters
-
string$name The translator package name being resolved.
-
string$locale The locale being resolved.
Returns
stringThe resolved prefix or an empty string when none is set.
Throws
InvalidArgumentExceptionIf a Closure prefix returns an invalid value.
setCacheKeyPrefix() ¶ public
setCacheKeyPrefix(Closure|string $prefix): voidSets a prefix segment added to translator cache keys and in-memory lookup buckets.
Intended for isolating translations in multi-tenant applications where dynamic loaders may produce different messages for the same domain and locale per tenant.
Accepts either a string (static prefix) or a Closure that returns a
string. Closures are resolved on every {@see get()} call so the current
tenant identifier can be pulled from user-land without pushing state
into this class. An empty result disables prefixing and keeps the
legacy cache key format translations.{domain}.{locale}.
The Closure receives the requested package name and resolved locale
(function (string $name, string $locale): string), so callers may
vary the prefix per package (e.g. skip prefixing for shared packages)
or per locale. Each distinct resolved prefix produces its own
in-memory bucket, so closures that vary by $name/$locale will
fragment the registry accordingly.
Prefix values must match [A-Za-z0-9._-]+ to stay safe across every
built-in cache engine.
Unrelated to the gettext message context used by {@see __x()}.
Parameters
-
Closure|string$prefix Static prefix or a Closure returning one.
Returns
voidThrows
InvalidArgumentExceptionIf a non-empty string prefix contains invalid characters.
setCacher() ¶ public
setCacher(Psr\SimpleCache\CacheInterface&Cake\Cache\CacheEngineInterface $cacher): voidSets the CacheEngine instance used to remember translators across requests.
Parameters
-
Psr\SimpleCache\CacheInterface&Cake\Cache\CacheEngineInterface$cacher The cacher instance.
Returns
voidsetFallbackPackage() ¶ public
setFallbackPackage(string $name, Cake\I18n\Package $package): Cake\I18n\PackageSet fallback domain for package.
Parameters
-
string$name The name of the package.
-
Cake\I18n\Package$package Package instance
Returns
Cake\I18n\PackagesetLoaderFallback() ¶ public
setLoaderFallback(string $name, callable $loader): callableSet domain fallback for loader.
Parameters
-
string$name The name of the loader domain
-
callable$loader invokable loader
Returns
callableloader
setLocale() ¶ public
setLocale(string $locale): voidSets the default locale code.
Parameters
-
string$locale The new locale code.
Returns
voiduseFallback() ¶ public
useFallback(bool $enable = true): voidSet if the default domain fallback is used.
Parameters
-
bool$enable optional flag to enable or disable fallback
Returns
voidProperty Detail
$_cacher ¶ protected
A CacheEngine object that is used to remember translator across requests.
Type
(Psr\SimpleCache\CacheInterface&Cake\Cache\CacheEngineInterface)|null$_defaultFormatter ¶ protected
The name of the default formatter to use for newly created translators from the fallback loader
Type
string$_loaders ¶ protected
A list of loader functions indexed by domain name. Loaders are callables that are invoked as a default for building translation packages where none can be found for the combination of translator name and locale.
Type
array<callable>$cacheKeyPrefix ¶ protected
Cache key prefix segment used to isolate translations, e.g. per tenant.
A string is applied as-is. A Closure is invoked on every get() call and must return a string. An empty result disables prefixing and restores the legacy cache key format.
Type
Closure|string$registry ¶ protected
A registry to retain translator objects, keyed by prefix bucket, name and locale.
Type
array<string, array<string, array<string, \Cake\I18n\Translator>>>