DEV Community

Cover image for Laravel Starter Kit Localization Is Surprisingly Painful
catatsumuri
catatsumuri

Posted on

Laravel Starter Kit Localization Is Surprisingly Painful

#laravel #inertiajs #php

About Laravel Starter Kits Since Laravel 12

These are meant to rapidly deploy functionality that is almost essential during the initial launch of an application, including the following:

  • Layouts
    • A typical sidebar layout
    • Or a typical header layout
    • Breadcrumbs
  • Authentication
    • Basic session management
    • Password reminders
    • Self-registration
    • TOTP-based 2FA
  • User settings
    • Profile
    • Light mode / dark mode switching
    • Account deletion
  • Simple dashboard


Provided authentication screen


Part of the user settings

As you can see, this is extremely convenient for getting a project off the ground. However, especially in Japanese-speaking regions, adoption does not seem to be progressing very well. One reason is probably that the functionality is somewhat difficult to understand, but another major factor is likely the effort required for Japanese localization. Nowadays, with AI programming, identifying and rewriting English interfaces is not especially difficult, but not everyone has access to AI development agents, repeatedly translating everything with AI is exhausting, and if you are making an ambitious attempt to support multilingualization as OSS, then Laravel Starter Kits will inevitably run into localization issues.

Laravel Starter Kits Actually Come in About Four Flavors

Even when we say “Laravel Starter Kit,” there are currently about four flavors. First, I want to organize them.

  • Livewire-based
  • Inertia.js-based
    • React
    • Vue
    • Svelte

At a broad level, things first split into Livewire and Inertia.js, and under Inertia.js there are three more flavors, each with branches beneath them... This huge number of variations is itself one of the characteristics of this project. Since the localization situation differs between Livewire and Inertia.js, you first need to understand that distinction.

To give the conclusion up front: if you intend to complete your project with Livewire, multilingualization is not especially difficult, and there is already some infrastructure in place. However, if you try to localize Inertia.js, there is no translation mechanism in the Starter Kit’s default state.

Projects for i18n in Laravel

Laravel’s Built-in Translation Mechanism

On the backend side, Laravel itself already has localization functionality, which is reinforced through additional resources provided by Laravel Lang.

Laravel 13 Localization Documentation:

https://laravel.com/docs/13.x/localization

About Laravel-Lang

There has actually been a project called Laravel-Lang for quite a while, and it already provides some multilingualization mechanisms.

https://laravel-lang.com/basic-usage.html

Following the documentation:

composer require laravel-lang/common
Enter fullscreen mode Exit fullscreen mode

This resolves and installs the following dependencies:

  • laravel-lang/publisher
  • laravel-lang/lang
  • laravel-lang/attributes
  • laravel-lang/http-statuses
  • laravel-lang/starter-kits

At first glance, it seems like this package might somehow magically handle Starter Kit localization, but reality is not so simple. We’ll look at that later. Simply installing the package only expands files under vendor/, so at this stage, nothing is actually usable yet.

Deploying Into the Actual Project With the lang:add Command

You execute it like this. Here, we’ll only deploy ja.

php artisan lang:add ja
Enter fullscreen mode Exit fullscreen mode

The actual implementation of this command comes from the previously resolved dependency laravel-lang/publisher, which performs the following tasks:

  1. Determine the target locale
  2. Select only enabled plugins from the plugin list
  3. Read the key list from source/...
  4. Read values from locales/{locale}/...
  5. Write them into lang/{locale}.json or lang/{locale}/*.php

In any case, once this command is executed, things should expand like this:

   INFO  Collecting translations...

  LaravelLang\Actions\Plugin ............................................................................. 2.37ms DONE
  LaravelLang\Attributes\Plugin .......................................................................... 0.83ms DONE
  LaravelLang\HttpStatuses\Plugin ........................................................................ 1.28ms DONE
  LaravelLang\Lang\Plugin ................................................................................ 5.90ms DONE
  LaravelLang\StarterKits\Plugin ......................................................................... 1.37ms DONE

   INFO  Storing changes...

  ja.json ................................................................................................ 5.04ms DONE
  ja/actions.php ......................................................................................... 4.65ms DONE
  ja/auth.php ............................................................................................ 0.45ms DONE
  ja/http-statuses.php ................................................................................... 2.02ms DONE
  ja/pagination.php ...................................................................................... 0.55ms DONE
  ja/passwords.php ....................................................................................... 0.52ms DONE
  ja/validation.php
Enter fullscreen mode Exit fullscreen mode

Locale Configuration

As described in the official documentation, this is determined by the APP_LOCALE environment variable, and falls back to APP_FALLBACK_LOCALE if unavailable. Therefore, for Japanese localization, the configuration would typically look like this:

#APP_LOCALE=en
APP_LOCALE=ja
APP_FALLBACK_LOCALE=en
APP_FAKER_LOCALE=en_US
Enter fullscreen mode Exit fullscreen mode

This localizes the backend.


For example, after installing the package and configuring the locale, even 404 pages are immediately translated into Japanese. But this is backend functionality.

Frontend Support

This is where the problem begins.

As mentioned earlier, the situation differs between Livewire and Inertia.js. To say it first: the only thing functioning relatively properly at the moment is Livewire. So let’s start with the Livewire side.

Roughly How Laravel-Lang Builds Translation Files

There are actually two major types of translation files: .json and .php types. Since the frontend mainly uses .json files, I’ll focus on those here.

At this point, the dependency resolution from laravel-lang/common should have expanded the following four files:

vendor/laravel-lang/starter-kits/locales/ja/json.json
vendor/laravel-lang/lang/locales/ja/json.json
vendor/laravel-lang/http-statuses/locales/ja/json.json
vendor/laravel-lang/actions/locales/ja/json.json
Enter fullscreen mode Exit fullscreen mode

These are merged together to ultimately form the file lang/ja.json. However, not everything is blindly copied over; there is actually a filtering stage called source defined beforehand. For example, let’s look at the Livewire one.

https://github.com/Laravel-Lang/starter-kits/blob/main/source/livewire/main/livewire.json

Only the keys listed here are picked up and internally expanded, so this mechanism seems intended to filter out unnecessary keys.

Meanwhile, the current React situation looks like this:

https://github.com/Laravel-Lang/starter-kits/blob/main/source/react/main/react.json

…Yeah.

So let’s look at how the Livewire Starter Kit is actually translated by examining the login screen.

Translating the Livewire Starter Kit Login Screen

https://github.com/laravel/livewire-starter-kit/blob/main/resources/views/pages/auth/login.blade.php

In this case, translation hooks are already embedded throughout the UI from the beginning. For example:

<!-- Remember Me -->
<flux:checkbox name="remember" :label="__('Remember me')" :checked="old('remember')" />

<div class="flex items-center justify-end">
  <flux:button variant="primary" type="submit" class="w-full" data-test="login-button">
    {{ __('Log in') }}
  </flux:button>
</div>
Enter fullscreen mode Exit fullscreen mode

As shown, it passes things through PHP’s translation system using __(). Since Livewire is tightly integrated with the backend (essentially operating in a pure Blade-like manner), this approach is possible.

The Quality of Livewire’s Japanese Resources

So does installing the language pack solve everything? Unfortunately, no. At present, the translation quality is extremely poor, or rather, most of it is untranslated.

https://github.com/Laravel-Lang/starter-kits/blob/main/locales/ja/json.json

Since translation files are generated based on this, there’s honestly no way around fixing it. I’ve been sending PRs and discussing things, so maybe it’ll improve somewhat, but who knows...

https://github.com/Laravel-Lang/starter-kits/pull/1902

https://livewire-starter-kit-ja.catatsumuri.org/login

You can view the current proposal using test@example.com / password

As for Inertia.js UIs Like React

Let’s look at the login screen again. Since we compared the Remember me section earlier, here’s just the corresponding part.

https://github.com/laravel/react-starter-kit/blob/main/resources/js/pages/auth/login.tsx#L76-L94

The strings are written directly into the source code, meaning that whether it’s Japanese or any other language, nothing gets translated as-is (naturally).

Conclusion

That is the current state of localization (i18n) in Laravel Starter Kits. Outside of Livewire, things are honestly pretty rough. For English-speaking users, this tends not to become a major issue, but outside that environment... the problems become extremely apparent. I suspect everyone is just aggressively rewriting UIs using AI or similar tools, but I really wish things were handled a little better. For now, I’ve at least tried contributing Japanese resources through PRs, but in the end, what’s actually going to happen here?

Top comments (0)