Languages
Central language selection, locale normalization and a zero-configuration global fallback.
Active language resolution
Core\Languages loads active documents from the mapped language collection and chooses the
active
language using the first valid candidate in the following order.
Language keys are normalized to lowercase with underscores: de-DE becomes de_de.
Browser header entries are processed in header order; this controller does not independently sort them
by
q weights.
Language and main language
A regional language has both an active locale key and a main-language key. For example,
de_de
produces de as its main language. The main key is derived from the locale and does not
require
a separate active document.
Virtual global mode
If no language collection is mapped, the controller initializes a virtual global entry. The
active, active main, default and default main keys are all global. This is useful for
single-language applications or projects that manage their own text in templates. No MongoDB language
collection is required.
Public API
$languages = Registry::get(\Core\Languages::class);
$active = $languages->getActive();
$main = $languages->getActiveMain();
$default = $languages->getDefault();
$fallback = $languages->getFallbackKeys();
$available = $languages->getAll();
if ($languages->has('de_de')) {
$languages->setActive('de_de');
}
get() retrieves the active or requested language document; getDefaultMain()
returns
the default main-language key. getFlag() resolves an SVG flag path where available, a
no-flag
image otherwise, and an empty string for global.
Cookie persistence
setActive() accepts only available language keys and persists a valid choice using the
logical
LANGUAGE cookie. The default timeout is 31,536,000 seconds (365 days).
Core\Cookie
determines the actual browser cookie name and scope. A change to the active language updates the
language
controller's runtime state; the translations controller is separately initialized and cached by
language, so
applications should plan reinitialization or a subsequent request when switching languages.
Configured languages
The supplied MongoDB language template includes 438 language and locale entries. Only activated documents returned by the mapped collection are selectable. An explicitly marked default takes precedence; otherwise the first available language becomes the default.
Public API Reference
Core\Languages
Class & Registry
Class:
Core\Languages
Extends:
Core\Languages\Base
use Core\Languages;
use Core\Registry;
$languages = Registry::get(Languages::class);
| Method | Description |
|---|---|
setActive(string $key): bool |
Select an available language and persist the LANGUAGE cookie; returns false for an unavailable key. |
has(string $key): bool |
Check whether a normalized language key is available. |
get(string|null $key = null): object|null |
Return the selected or currently active language object, if present. |
getAll(): array |
Return all available active languages, indexed by normalized key. |
getActive(): string |
Return the active language key. |
getActiveMain(): string |
Return the main language key derived from the active locale. |
getDefault(): string |
Return the configured or resolved default language key. |
getDefaultMain(): string |
Return the main language key of the default language. |
getFallbackKeys(): array |
Return unique fallback keys in global → active main → active order. |
getFlag(string|null $key = null): string |
Return a flag asset path, an unavailable-flag image, or an empty string for global. |