LanguagesTrait
Provides helper methods to manage multilingual (i18n) content in controllers.
This trait allows a controller to:
- Initialize and store a list of valid languages (
$languages) from an array or a PSR-11 container. - Filter client-provided arrays of translations to keep only supported languages.
- Retrieve the appropriate translation for a given language, with fallback to the default language.
Example usage:
// Initialize with an array of supported languages
$this->initializeLanguages(['languages' => ['fr', 'en']]);
// Filter a multilingual array to keep only supported languages
$input =
[
'fr' => 'Bonjour <span style="color:red">monde</span>',
'en' => 'Hello <span style="color:red">world</span>',
'de' => 'Hallo Welt'
];
$filtered = $this->filterLanguages($input);
// $filtered =
// [
// 'fr' => 'Bonjour <span style="color:red">monde</span>',
// 'en' => 'Hello <span style="color:red">world</span>'
// ]
// Filter and remove inline styles for HTML output
$filteredHtml = $this->filterLanguages($input, true);
// $filteredHtml = [
// 'fr' => 'Bonjour <span>monde</span>',
// 'en' => 'Hello <span>world</span>'
// ]
// Retrieve translation for a given language
$textEn = $this->translate($filtered, 'en'); // 'Hello <span>world</span>'
// Retrieve translation with fallback to default language if requested language is missing
$textDe = $this->translate($filtered, 'de'); // 'Bonjour <span>monde</span>' (fallback to 'fr')
Table of Contents
Properties
- $languages : array<string|int, string>
- The enumeration of all valid languages used by the controller.
Methods
- filterLanguages() : array<string, mixed>|null
- Filter an array of translations according to the available languages.
- initializeLanguages() : static
- Initialize the internal `$languages` property from an array or a PSR-11 container.
- translate() : mixed
- Retrieve the translation for a specific language, or fallback to the default language.
Properties
$languages
The enumeration of all valid languages used by the controller.
public
array<string|int, string>
$languages
= []
Methods
filterLanguages()
Filter an array of translations according to the available languages.
public
filterLanguages(array<string, mixed>|null $field[, bool $html = false ]) : array<string, mixed>|null
This helper transforms an input array from the client to prepare a multilingual (i18n) property.
Example input: [ 'fr' => 'bonjour', 'en' => 'hello' ]
Parameters
- $field : array<string, mixed>|null
-
The input array of translations.
- $html : bool = false
-
If true, strip inline styles from HTML content.
Return values
array<string, mixed>|null —Filtered translations matching available languages, or null if input is empty.
initializeLanguages()
Initialize the internal `$languages` property from an array or a PSR-11 container.
public
initializeLanguages([array<string|int, mixed> $init = [] ][, ContainerInterface|null $container = null ]) : static
Parameters
- $init : array<string|int, mixed> = []
-
Optional initialization array, expected key: ControllerParam::LANGUAGES
- $container : ContainerInterface|null = null
-
Optional PSR-11 container for fallback configuration
Tags
Return values
statictranslate()
Retrieve the translation for a specific language, or fallback to the default language.
public
translate(array<string, mixed> $texts[, string|null $lang = null ]) : mixed
Parameters
- $texts : array<string, mixed>
-
Array of translations keyed by language codes.
- $lang : string|null = null
-
The desired language code. If null, returns the full array.
Return values
mixed —The translated text for the requested language, fallback, or full array if no match.