Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

Laravel shows messages.welcome instead of the translated text

Errormessages.welcome

Short 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.

  • Applies to Laravel 11, Laravel 12, PHP 8.3
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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')
  2. 2Match what you see, then jump to its fix

    1. 1__('messages.welcome') prints messages.welcomeThe key does not match the file or the arrayFix
    2. 2ls: lang: No such file or directoryThe lang folder was never createdFix
    3. 3The key works for one language and prints raw for anotherThe active locale has no file for this keyFix
    4. 4__('Action') returns a whole array, or the English text appears in another languageA JSON key clashes with a PHP translation fileFix
    5. 5APP_LOCALE changed in .env, but the site keeps the old languageCached config still holds the old localeFix

What does the error look like?

  • messages.welcome
  • The page prints the key you passed to __() instead of the translated sentence
  • A 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.php

2Fix

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

Did this fix it?

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 lang

2Fix

Publish the default language files. This creates the lang directory, and you can add your own files next to them.

php artisan lang:publish

3Verify

The folder now exists.

ls lang

Confirmed by laravel.com

Did this fix it?

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 lang

2Fix

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=en

3Verify

Switch the locale for one request and translate again.

php artisan tinker
>>> app()->setLocale('en_GB'); __('messages.welcome')

Confirmed by laravel.com

Did this fix it?

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/nl

2Fix

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

Did this fix it?

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.php

2Fix

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:clear

3Verify

Check the locale Laravel now uses.

php artisan tinker
>>> app()->getLocale()

Confirmed by laravel.com

Did this fix it?

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 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 fix

Back 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 fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.