Localization

Inertia Start makes it easy to adapt your application to every market.

It builds on Laravel's native localization system, so everything you already know about translation files and the __() helper still applies. On top of that, Inertia Start adds the pieces you'd otherwise have to build yourself.

What you get

• automatic detection of the user's preferred language, and persistence of their choice
• a ready-to-use language switcher component
• translations available in your Vue components, not just in Blade
• dates automatically formatted for the active language
• locale-aware emails (users receive notifications in their own language)
• SEO-friendly localized URLs with Route::localized(...), including automatic hreflang tags
• translated URL segments with Lang::uri(...)

Included translations

Out of the box, Inertia Start ships translations for:

• English (en)
• French (fr)
• Spanish (es)

Adding more languages is straightforward and covered below.

Getting started

How you set things up depends on whether your app needs one language or several.

One language only

If your app only ever needs a single language, you don't have to enable anything. Just set the APP_LOCALE environment variable:

APP_LOCALE=fr
APP_FALLBACK_LOCALE=en

APP_FALLBACK_LOCALE is the language used when a translation is missing in the active language.

That's it. You can still use Laravel's translation files and the __() helper everywhere, but no language switcher or auto-detection will be active.

Multiple languages

If you want to support several languages and let users pick their own, enable the localization feature and follow these steps.

I_S_ENABLE_LOCALIZATION=true

{
    "en": {
        "name": "English",
        "native": "English"
    },
    "es": {
        "name": "Spanish",
        "native": "Español"
    },
    "fr": {
        "name": "French",
        "native": "Français"
    }
}

<?php

return [
    'welcome' => 'Welcome!',
];

<?php

return [
    'welcome' => 'Bienvenue !',
];

{
    "Welcome!": "Bienvenue !"
}

npm run prepare

<div>{{ __('messages.welcome') }}</div>

<template>
  <div>{{ __('messages.welcome') }}</div>
</template>

<script setup lang="ts">
import LanguageSwitcher from '@/components/LanguageSwitcher.vue';
</script>

<template>
  <LanguageSwitcher />
</template>

Translating in Vue components

In a template, the global __() helper (an alias of trans) works without any import:

<template>
  <h1>{{ __('messages.welcome') }}</h1>
</template>

Inside <script setup> (where global helpers aren't available), use the useTrans composable:

<script setup lang="ts">
import { useTrans } from '@/plugins/i18n';

const { __, trans, transChoice } = useTrans();

const title = __('messages.welcome');
</script>

useTrans exposes:

• trans(key, replacements?) — get a translation. __ is an alias of trans.
• transChoice(key, count, replacements?) — get a translation with pluralization.

Replacing placeholders. Pass an object as the second argument to fill :placeholders in your strings:

return [
    'greeting' => 'Hello, :name!',
];

<template>
  <p>{{ __('messages.greeting', { name: 'Anthony' }) }}</p>
</template>

Pluralization. Use transChoice (or the global trans_choice) with a count:

return [
    'apples' => 'There is one apple|There are many apples',
];

<script setup lang="ts">
import { useTrans } from '@/plugins/i18n';

const { transChoice } = useTrans();
</script>

<template>
  <p>{{ transChoice('messages.apples', 5) }}</p>
</template>

How the language is chosen

When localization is enabled, Inertia Start automatically resolves the most appropriate language on each request. It checks the following sources in order and uses the first supported locale it finds:

1. URL — the locale prefix in the path (e.g. /fr/...) or a locale-specific domain.
2. User account — the authenticated user's saved locale.
3. Session — the locale stored in the current session (used for guests).
4. Cookie — a previously stored locale cookie (only if you enable cookie storage).
5. Browser — the Accept-Language header sent by the browser.
6. Application default — falls back to app.locale if nothing else matches.

Once resolved, the locale is persisted so it sticks across requests — by default in the session (and in the user's account when they explicitly switch).

Localized URLs

Localized URLs give each language its own unique address (great for SEO, since search engines can index every language version separately). Register them with the Route::localized(...) macro:

Route::localized(function () {
    Route::get('/', function () {
        return Inertia::render('Home');
    })->name('home');
});

The macro prefixes each URL with its locale, based on localization.locales and localization.localized_urls in config/inertia-start.php. By default en is the omitted locale, so English URLs stay unprefixed while the others get a prefix:

• /login → English
• /fr/login → French
• /es/login → Spanish

If English isn't your primary language, update both localization.localized_urls.fallback_locale and localization.localized_urls.omitted_locale in config/inertia-start.php.

Generating localized URLs

On the frontend, use the global route() helper or the useRoute composable. Both automatically try the localized route name for the current language first (e.g. fr.home) and fall back to the raw name (home) if the route isn't localized — so you can always just write the plain route name.

<script setup lang="ts">
import { useRoute } from '@/composables/useRoute';

const { route } = useRoute();
</script>

<template>
  <!-- resolves to /fr/login when the active language is French -->
  <Link :href="route('login')">Login</Link>
</template>

On the backend, Route::localizedUrl(...) generates the URL of the current page in a given locale — this is what powers the language switcher and the alternate links below.

Automatic SEO alternate links

For localized pages, Inertia Start automatically injects <link rel="alternate" hreflang="..."> tags (including an x-default pointing at your fallback locale) via the AlternateLinks component, which is already wired into the layouts. This tells search engines about every language version of a page — no setup required.

Redirecting URLs without a locale prefix

You can optionally redirect visitors who land on a non-localized URL to the correct localized version. Enable it in config/inertia-start.php:

'localized_urls' => [
    // ...
    'redirect' => [
        'enabled' => true,
        'status_code' => 301,
    ],
],

This relies on a fallback route, which the starter kit already registers at the very end of routes/web.php:

use App\Http\Controllers\FallbackController;
use Illuminate\Support\Facades\Route;

// Keep this at the end of your web routes file.
Route::fallback(FallbackController::class);

If you replace the default fallback route, make sure you still register one at the end of your routes file so these redirects keep working.

Translating URL segments

Beyond prefixing URLs with a locale, you can translate the path segments themselves. Combine Route::localized(...) with Lang::uri(...) and a routes translation file:

use Illuminate\Support\Facades\Lang;
use Illuminate\Support\Facades\Route;

Route::localized(function () {
    Route::get(Lang::uri('login'), function () {
        // ...
    })->name('login');

    Route::get(Lang::uri('products/{product}'), function () {
        // ...
    })->name('products.show');
});

<?php

return [
    'login' => 'login',
    'products' => 'products',
];

<?php

return [
    'login' => 'connexion',
    'products' => 'produits',
];

With the above, the login page is reachable at /login (English) and /fr/connexion (French).

Lang::uri(...) first checks whether the full URI has a translation, then falls back to translating each segment individually. Route parameters such as {product} are preserved automatically.

Configuration & key files

All localization settings live in the localization section of config/inertia-start.php:

The main building blocks, if you want to dig deeper:

• resources/js/plugins/i18n.ts — loads the translations, creates the useTrans composable and the global __ / trans / trans_choice helpers, and keeps the date-fns locale in sync.
• resources/js/plugins/ziggy.ts & resources/js/composables/useRoute.ts — register the locale-aware global route() helper.
• resources/js/components/LanguageSwitcher.vue — the language selector.
• resources/js/components/AlternateLinks.vue — the automatic hreflang SEO tags.