Add typed translation helpers trans()->string() and trans()->array()

[dansan92]

Laravel currently provides two main translation helpers:

__(): array|string|null and trans(): Translator|array|string.

My suggestion is to introduce trans()->string() and trans()->array() typed translation accessors. This would lead to type safe, explicit code, as array|string should not be cast to string. Such an addition would be very simple, as trans() defaults to Translator already.

This proposal also aligns with Laravel's typed helper API recently added to request() and config(), which introduced expressive, type-specific accessors such as: request()->string(), request()->integer() and so on.

[dansan92]

Some examples:

// Use it anywhere
trans()->string('Hello world');

// Support replacements while preserving a strict string return type.
Flux::toast(
    trans()->string(':model updated successfully!', ['model' => $modelName]),
    null,
    5000,
    'success',
);

// Respect function return type without hassle (for example in backed enums)
public function label(): string
{
    return trans()->string($this->name);
}

// Retrieve translation arrays without broad array|string|null handling.
$customValidationMessages = trans()->array('validation.custom');

// PHP 8.4 property hooks, so you never forget to translate! (unorthodox, but cool?)
public string $label = 'Some label' {
    get => trans()->string($this->label);
}

[shaedrich]

While the naming works well for the places you mentioned that already have these typed helpers, translations are another animal. vue-i18n, for example, has a separate method called rt() to retrieve arrays (arguably a bad naming, but the well-intentioned imho). Also, another difference is that PHP has two types of array: lists and associative array or hash maps, which have a vastly different meaning in translation files. So, therefore, I would suggest something along the lines of

• trans()->message('greetings.general') // 'Hello world'
• trans()->messages('greetings') // ['general' => 'Hello world', 'laravel' => Hello artisans']
• trans()->list('rating') // ['low', 'medium', 'high']

However, the naming would, other than, for example string(), not necessarily indicate that it throws when the key is not found and the normal translation would return null. So, I'm not sure if this would require us to, similar to Eloquent, have messageOrFail() and the other counterparts.

Language file

{
    "greetings": {
        "general": "Hello world",
        "laravel": "Hello artisans"
    },
    "ratings": [
        "low",
        "medium",
        "high"
    ]
}

Usage

<h1>{{ trans()->message('greetings.general') }}</h1>
<strong>Current rating:</strong> {{ trans()->list('ratings')[$userRating->score] }}

<div class="flex">
    @foreach (trans()->list('ratings') as $score => $label)
        <label>
            <input type="radio" name="rating" value="{{ $score }}" />
            {{ $label }}
        </label>
    @endforeach
</duv>

[dansan92]

Yep, agree, assoc() is very clear.

[shaedrich]

trans()->list();   // list<string> or perhaps list<mixed>?
trans()->map();   // array<string, string> or perhaps array<string, mixed>?

Following your philosophy of narrowing types sufficiently down, this can only be list<string> or list<scalar> as this is meant for the array version of a single message that is retrieved via string(). assoc() is a little different here as its value type can be either string or an array nested in itself.

{
    "foo": [
        "bar", // ✓ makes sense
        { "baz": "quux" } // ✖ doesn't make sense
    ]
}

{
    "foo": {
        "bar", // ✓ makes sense
        "baz": {  // ✓ also makes sense
            "quux": "qux
        }
    ]
}

So, trans()->assoc('foo') would result in array<string, string|array<string, string>. Since recursiveness can't be expressed via PHPStan, we can only narrow it down thus far.

[dansan92]

Gave it some thought.

I think allowing assoc() to return array<string, string|array<...>> may slightly undermine the purpose of these typed accessors.

The main benefit of trans()->string(), trans()->list(), and trans()->assoc() would be that the caller gets a predictable value type without having to branch again afterwards.

For example, if assoc() may contain nested arrays, this still leaves the caller with:

foreach (trans()->assoc('foo') as $key => $value) {
    // $value is string|array, so this still needs another type check
}

The question would be whether assoc() narrows enough over array() to be worth a separate helper. To me, assoc() would be most useful if it meant the associative counterpart to list():

trans()->list('ratings'); // list<string>
trans()->assoc('messages'); // array<string, string>

Then nested translation groups could still be retrieved through the broader accessor:

trans()->array('foo'); // array (aka. array<array-key, mixed>)

[shaedrich]

The question would be whether assoc() narrows enough over array() to be worth a separate helper. […] I think allowing assoc() to return array<string, string|array<...>> may slightly undermine the purpose of these typed accessors. […] Then nested translation groups could still be retrieved through the broader accessor

You are right—I'd say, this sells your point perfectly 👍🏻

[dansan92]

See PR #60443.

I intentionally left out assoc() and list() there to keep the first PR focused on the base API. I figured string() and array() would be an easier sell than the more opinionated shape-specific helpers, and that those could be explored separately if there is interest.

That said, while thinking about a follow-up PR, I started wondering whether one narrower helper might be enough:

list(): list<string> // Do we care that the keys are integers?
assoc(): array<string, string> // Do we care that the keys are strings?

strings(): array<string> // Or is the valuable part simply knowing that all values are strings?

For translation arrays, I think the most useful guarantee is usually that the values are strings. Whether the array is technically a list or an associative map may matter in some cases, but I’m not sure it is worth baking both shapes into the API unless people have concrete use cases for that distinction. My concern is that it may be considered feature creep.

So perhaps the follow-up API could be:

trans()->strings('ratings'); // array<string>

What do you think?