Laravel Localization: How to Translate Your Laravel App

Laravel localization lets you serve your application in several languages by storing translations in language files and retrieving them with the __() helper, which returns the right string for the current locale. Laravel supports two formats: PHP array files organized by key, and JSON files that use the source text as the key. This guide explains how to set up localization in Laravel, handle placeholders and plurals, switch locales and manage translations at scale.

Step 1: Publish the Language Files

Newer Laravel applications do not include a lang directory by default. Run php artisan lang:publish to create it with Laravel's default language files. The official Laravel localization documentation describes every option.

Step 2: Choose a File Format

Many teams use JSON files for UI text because they are easy to send to translators and import into translation tools without conversion.

Step 3: Retrieve Translated Strings

• In PHP: __('messages.welcome') or __('Welcome to our app').
• In Blade templates: {{ __('messages.welcome') }} or the @lang directive.
• If a key is missing, Laravel returns the key itself, which makes untranslated strings easy to spot.

Step 4: Use Placeholders

Placeholders start with a colon, for example 'welcome' => 'Welcome, :name', and are filled with __('messages.welcome', ['name' => $user->name]). Translators can move placeholders to where they belong in their language, but must never translate or delete them.

Step 5: Handle Plurals

Laravel separates plural forms with a pipe character and selects the right one with trans_choice(). You can also define ranges, for example '{0} No messages|{1} One message|[2,*] :count messages'. Languages such as Polish, Russian or Arabic have more plural forms than English, so translators need to know how many forms each string supports.

Step 6: Set and Switch the Locale

1. Set the default and fallback locales in your configuration or environment file.
2. Change the locale at runtime with App::setLocale('de'), for example in a middleware based on the URL, user profile or browser language.
3. Check the current locale with App::currentLocale().
4. Use URL prefixes such as /de/ for public pages, so search engines can index each language. Add hreflang tags as explained in our hreflang guide.

Translating Laravel Language Files

Editing language files by hand works for one or two languages. As the app grows, manual work leads to missing keys, broken placeholders and inconsistent terminology. A better workflow is to export language files, translate them in a dedicated tool with translation memory and QA, and import them back. If you use JSON files, read our guide on how to translate a JSON file. PHP array files can be converted to JSON or CSV with a short script before translation.

Best Practices

• Never hard-code user-facing text in controllers or views.
• Use descriptive keys and add context comments for translators.
• Do not concatenate translated fragments; use full sentences with placeholders.
• Format dates and numbers with locale-aware tools, not string manipulation.
• Check for missing keys in every language before each release.
• Automate translation sync as part of continuous localization.

Translate Laravel Apps With WordBeam

WordBeam imports Laravel JSON language files directly, protects :placeholders and keys, and lets translators work with translation memory, a glossary and AI engines such as DeepL, GPT and Claude. QA checks flag missing placeholders before export, and on the Studio plan GitHub and GitLab integrations keep language files in sync with your repository. Learn more about WordBeam for software localization.

Frequently Asked Questions

Where are translation files stored in Laravel?

In the lang directory at the root of the project, created with php artisan lang:publish.

Should I use PHP or JSON translation files in Laravel?

PHP files suit structured keys; JSON files are simpler for large amounts of UI text and easier to hand off for translation. Many apps use both.

How do I translate validation messages in Laravel?

Validation messages live in lang/{locale}/validation.php. Publish the language files and add a folder for each target language.