Laravel shows messages.welcome instead of the translated text
messages.welcomeShort answer
When Laravel cannot find a translation, __() returns the key you gave it. So the page shows messages.welcome instead of the text. Check four things: the key matches the file and array name, the lang folder exists, the active locale has that file, and the cached config is not holding an old locale.
Fix it fast
1Find out which cause you have
Ask Laravel which locale and fallback locale are active, then translate one key in tinker. If the output equals the key, Laravel did not find it.
php artisan tinker >>> app()->getLocale() >>> app()->getFallbackLocale() >>> __('messages.welcome')2Match what you see, then jump to its fix
- 1
__('messages.welcome') prints messages.welcomeThe key does not match the file or the arrayFix - 2
ls: lang: No such file or directoryThe lang folder was never createdFix - 3
The key works for one language and prints raw for anotherThe active locale has no file for this keyFix - 4
__('Action') returns a whole array, or the English text appears in another languageA JSON key clashes with a PHP translation fileFix - 5
APP_LOCALE changed in .env, but the site keeps the old languageCached config still holds the old localeFix
- 1
What does the error look like?
messages.welcomeThe page prints the key you passed to __() instead of the translated sentenceA JSON translation works in English but prints the English text in other languages
Cause 1 of 5
The key does not match the file or the array
1Check
With short keys, the first part is the file name and the rest is the array key. messages.welcome means lang/<locale>/messages.php must return an array with a welcome entry.
ls lang/en
grep -n "welcome" lang/en/messages.php2Fix
Make the file name, the array key and the string you pass to __() agree. Each language file must return a keyed array.
<?php
// lang/en/messages.php
return [
'welcome' => 'Welcome to our application!',
];3Verify
Translate the key again.
php artisan tinker
>>> __('messages.welcome')Confirmed by laravel.com
Cause 2 of 5
The lang folder was never created
1Check
The application skeleton does not ship a lang directory. Without it, only the framework's own strings exist.
ls -d lang2Fix
Publish the default language files. This creates the lang directory, and you can add your own files next to them.
php artisan lang:publish3Verify
The folder now exists.
ls langConfirmed by laravel.com
Cause 3 of 5
The active locale has no file for this key
1Check
Compare the active locale with the folders and JSON files in lang. Region locales use the ISO 15897 form, so British English is the en_GB folder, not en-gb.
grep -n "locale" config/app.php
ls lang2Fix
Create the missing folder or JSON file for that locale, or rename the folder to the ISO 15897 spelling. Set the fallback locale so a missing string falls back to a language you do translate.
# .env
APP_LOCALE=en_GB
APP_FALLBACK_LOCALE=en3Verify
Switch the locale for one request and translate again.
php artisan tinker
>>> app()->setLocale('en_GB'); __('messages.welcome')Confirmed by laravel.com
Cause 4 of 5
A JSON key clashes with a PHP translation file
1Check
JSON files use the default sentence as the key. If you call __('Action') for locale nl, a lang/nl/action.php file exists and lang/nl.json does not, Laravel returns the whole contents of action.php.
ls lang
ls lang/nl2Fix
Create the JSON file for that locale, or rename the PHP file or the JSON key so they no longer share a name.
// lang/nl.json
{
"Action": "Actie"
}3Verify
Translate the sentence again with the locale set to nl.
php artisan tinker
>>> app()->setLocale('nl'); __('Action')Confirmed by laravel.com
Cause 5 of 5
Cached config still holds the old locale
1Check
config:cache merges all config files into one cached file. After that, the app reads the cache, not .env.
ls bootstrap/cache/config.php2Fix
Rebuild the config cache after every .env change, or clear it while you work.
php artisan config:cache
# or, to remove all optimize caches
php artisan optimize:clear3Verify
Check the locale Laravel now uses.
php artisan tinker
>>> app()->getLocale()Confirmed by laravel.com
How do I stop it coming back?
- Use one style per project, short keys or JSON sentence keys, and do not give a PHP file and a JSON key the same name.
- Set APP_FALLBACK_LOCALE so a missing string shows a real sentence instead of a key.
- Run php artisan config:cache as a deploy step, after .env is in place.
- Add a test that translates one key per locale and fails when the output equals the key.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
Related fixes
Back end
Composer says the gd extension is missing on a Laravel project
composer install or composer update stops on a package that requires ext-gd
Composer refuses to install a package that requires ext-gd when the PHP binary running Composer has no GD extension.
4 causes, each with a fixBack end
composer require maatwebsite/excel fails to install
Composer says the package needs an older PHP than the one installed
Composer refuses maatwebsite/excel when the PHP version or a PHP extension does not match what the package and PhpSpreadsheet need.
3 causes, each with a fixBack end
composer install says the lock file is not compatible and asks for update
Your lock file does not contain a compatible set of packages. Please run composer update.
composer install checked the locked packages against this machine's PHP and extensions and found a conflict.
3 causes, each with a fixBack end
composer require laravel/horizon fails: ext-pcntl is missing
laravel/horizon v1.1.0 requires ext-pcntl * -> the requested PHP extension pcntl is missing from your system
Horizon needs the pcntl extension, and Composer refuses to install it where PHP lacks that extension.
3 causes, each with a fixBack end
composer require laravel/passport stops with 'requirements could not be resolved'
... but these were not loaded, likely because it conflicts with another require.
Composer found no Passport release that fits your project at once.
4 causes, each with a fixBack end
Composer says the root composer.json requires a PHP version your PHP does not satisfy
Your requirements could not be resolved to an installable set of packages.
Composer compares the php constraint in your composer.json, or in a package, with the PHP that runs Composer.
3 causes, each with a fix