NestedNativeArray

Translation adapter backed by a nested PHP array.

Phalcon's NativeArray adapter supports flat translation maps. This adapter adds delimiter-based nested lookup, while still preserving exact flat-key lookup precedence. A flat key such as button.save wins over a nested path button => ['save' => ...] when both exist.

Missing keys return the original key by default. Set triggerError to true when development/test environments should fail fast on missing translations.

Usage example:

$interpolator = new InterpolatorFactory();
$options = [
    'content' => [
        'en' => [
            'welcome' => 'Welcome to our website!',
            'goodbye' => 'Goodbye!',
        ],
        'fr' => [
            'welcome' => 'Bienvenue sur notre site web!',
            'goodbye' => 'Au revoir!',
        ],
    ],
    'triggerError' => false,
    'delimiter' => '.',
];

$translator = new NestedNativeArray($interpolator, $options);

// Check if translation exists
$translator->has('en.welcome'); // returns true

// Get translated string
$translator->query('fr.goodbye'); // returns 'Au revoir!'

// Get translated string with placeholders
$translator->query('en.welcome', ['name' => 'John']); // returns 'Welcome to our website, John!'

• Full name: \PhalconKit\Translate\Adapter\NestedNativeArray
• Parent class: AbstractAdapter
• This class implements: ArrayAccess

See Also:

• https://docs.phalcon.io/latest/translate/

Properties

translate

Translation content indexed by flat keys or nested arrays.

private array<string,mixed> $translate

delimiter

Delimiter used when resolving nested translation paths.

protected non-empty-string $delimiter

Methods

__construct

Create a nested-array translation adapter.

public __construct(\Phalcon\Translate\InterpolatorFactory $interpolator, array<string,mixed> $options): mixed

Supported options: - content: translation content as flat keys, nested arrays, or both. - triggerError: throw a RuntimeException when a key is missing. - delimiter: non-empty delimiter used for nested lookup.

Parameters:

exists

Check whether a translation exists for the given key.

public exists(string $index): bool

• Warning: this method is deprecated. This means that this method will likely be removed in a future version. Parameters:

Return Value:

True when the key exists.

See Also:

• \PhalconKit\Translate\Adapter\has()

has

Return true when a flat or nested translation key exists.

public has(string $index): bool

Exact flat keys are checked first. If no exact key exists, the key is split by the configured delimiter and resolved through nested arrays.

Parameters:

Return Value:

True when the key resolves to a configured translation.

notFound

Return the missing key fallback or throw when strict mode is enabled.

public notFound(string $index): string

Parameters:

Return Value:

Original key when triggerError is false.

Throws:

When triggerError is true. - RuntimeException

query

Return a translated string for a flat or nested key.

public query(string $translateKey, array<string,mixed> $placeholders = []): string

Exact flat keys are returned before nested lookup is attempted. Nested values are resolved with the configured delimiter and then passed through Phalcon's placeholder interpolator.

Parameters:

Return Value:

Translated string, or the missing-key fallback.

Throws:

When the key is missing and triggerError is true. - RuntimeException

toArray

Return the raw translation content.

public toArray(): array<string,mixed>

Return Value:

Translation content exactly as configured.