Создавайте многоязычные приложения на Laravel, Vue 3, React или Svelte, используя один набор файлов переводов.

В Laravel локализация всегда была довольно простой. Вы создаете языковые файлы, определяете ключи переводов и используете хелпер Laravel __() везде, где вам нужен переведенный текст.

Но всё меняется, когда ваш фронтенд использует Inertia.js с Vue, React или Svelte.

Laravel понимает ваши PHP-файлы переводов. Компоненты вашего фронтенда не имеют к ним автоматического доступа.

Именно здесь простая задача мультиязычности может потребовать больше усилий, чем ожидалось.

В этой статье я покажу вам, как использовать существующие языковые файлы Laravel прямо в компонентах Inertia.js, не поддерживая отдельные файлы переводов для фронтенда.

Проблема локализации в Laravel + Inertia.js

Представьте, что вы создаете дашборд на Laravel и Vue 3.

В вашем приложении на Laravel есть файл перевода:

lang/en/messages.php

<?phpreturn [
    'welcome' => 'Welcome back!',
    'dashboard' => 'Dashboard',
    'settings' => 'Settings',
];

В Laravel использовать эти переводы очень просто:

__('messages.welcome');

Но что происходит, когда вам нужен тот же перевод в компоненте Vue?

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

Это не будет работать автоматически. Vue ничего не знает о файлах переводов Laravel.

Вы можете установить отдельную библиотеку интернационализации, поддерживать JavaScript-объекты переводов или вручную передавать переводы через middleware Inertia.

Все эти подходы имеют право на жизнь.

Проблема в том, что в итоге вы можете управлять одним и тем же текстом в двух разных местах.

Когда вы добавляете новый язык или обновляете перевод, у вас появляется больше файлов для поддержки.

Для приложений с десятками страниц и сотнями ключей переводов это становится сложно поддерживать.

Более простой подход: Laravel Lang Sync Inertia

Чтобы упростить эту задачу, я создал пакет с открытым исходным кодом под названием  Laravel Lang Sync Inertia.

Идея проста: Laravel уже знает, какой язык использует ваше приложение, и в нем уже есть ваши файлы переводов.

Почему бы не переиспользовать эти переводы на фронтенде?

С помощью этого пакета вы можете выбрать языковые файлы Laravel и передать их в Inertia.js, используя всего один хелпер:

syncLangFiles('messages');

Затем ваш фронтенд сможет получать доступ к этим переводам с помощью привычных хелперов:

__('messages.welcome')

В настоящее время пакет поддерживает:

  • Файлы переводов Laravel, передаваемые через Inertia.js.
  • Фронтенд-компоненты Vue 3, React и Svelte.
  • Динамические плейсхолдеры, такие как :name.
  • Плюрализацию с использованием transChoice().
  • Вложенные файлы переводов и ключи через точку (dot-notation).
  • Автоматическую загрузку на основе активной локали Laravel.
  • TypeScript-совместимые хелперы фронтенда.
  • Опциональный экспорт переводов из PHP в JSON.

Давайте создадим рабочий пример.

Шаг 1: Установка пакета

Сначала установите пакет Laravel с помощью Composer.

composer require erag/laravel-lang-sync-inertia

Затем установите сопутствующий фронтенд-пакет:

npm install @erag/lang-sync-inertia

Если в вашем приложении на Laravel еще не опубликованы языковые файлы, выполните:

php artisan lang:publish

Затем выполните команду установки пакета:

php artisan erag:install-lang

Это опубликует конфигурацию пакета и необходимые ассеты.

Теперь у вас есть все необходимое, чтобы начать передавать переводы Laravel во фронтенд на Inertia.

Шаг 2: Создание языковых файлов

Давайте добавим поддержку английского и хинди в наше приложение.

В директории lang вашего приложения Laravel создайте следующие файлы:

lang/
├── en/
│   └── messages.php
└── hi/
    └── messages.php

 Английский:  lang/en/messages.php

<?phpreturn [
    'dashboard' => 'Dashboard',
    'welcome' => 'Welcome back, :name!',
    'settings' => 'Settings',
    'notifications' => '{0} No notifications|{1} One notification|[2,*] :count notifications',
];

 Хинди:  lang/hi/messages.php

<?phpreturn [
    'dashboard' => 'डैशबोर्ड',
    'welcome' => 'वापस आने पर स्वागत है, :name!',
    'settings' => 'सेटिंग्स',
    'notifications' => '{0} कोई सूचना नहीं|{1} एक सूचना|[2,*] :count सूचनाएं',
];

Мы используем стандартную структуру PHP-переводов Laravel.

Никаких дополнительных JavaScript-файлов переводов поддерживать не нужно.

И если у вас уже есть переводы Laravel в проекте, вы можете их переиспользовать.

Шаг 3: Передача переводов из контроллера Laravel

Теперь откройте контроллер, который рендерит вашу страницу Inertia.

Например, DashboardController.php:

<?phpnamespace App\Http\Controllers;use Inertia\Inertia;
use Inertia\Response;class DashboardController extends Controller
{
    public function index(): Response
    {
        syncLangFiles('messages');        return Inertia::render('Dashboard');
    }
}

Вот это ключевой момент:

syncLangFiles('messages');

Этот хелпер загружает выбранный языковой файл на основе активной локали Laravel и передает его переводы через Inertia.

Вам не нужно создавать отдельный API-эндпоинт или вручную прокидывать каждый перевод через ответ контроллера.

При необходимости вы также можете передавать несколько языковых файлов:

syncLangFiles([
    'messages',
    'auth',
    'validation',
]);

Это полезно для крупных приложений, где у вас могут быть разные файлы переводов для аутентификации, дашбордов, настроек и других модулей.

Вместо того чтобы загружать всё и везде, вы можете выбирать файлы, необходимые для каждой конкретной страницы.

Шаг 4: Использование переводов Laravel во Vue 3

Теперь давайте выведем эти переводы в нашем дашборде на Vue.

Откройте resources/js/Pages/Dashboard.vue.

<script setup lang="ts">
import { vueLang } from '@erag/lang-sync-inertia';const { __, trans, transChoice } = vueLang();
</script><template>
    <main>
        <h1>{{ __('messages.dashboard') }}</h1>        <p>
            {{ trans('messages.welcome', {
                name: 'Amit'
            }) }}
        </p>        <p>{{ __('messages.settings') }}</p>        <p>
            {{ transChoice('messages.notifications', 3) }}
        </p>
    </main>
</template>

Когда активной локалью Laravel является английская, на странице отображается:

DashboardWelcome back, Amit!Settings3 notifications

Когда активной локалью является хинди, тот же компонент отображает:

डैशबोर्डवापस आने पर स्वागत है, Amit!सेटिंग्स3 सूचनाएं

Обратите внимание на важную деталь.

 Мы не меняли компонент Vue для поддержки хинди.

Ключи переводов остались абсолютно теми же.

Laravel определяет активный язык, а пакет делает соответствующие переводы доступными для Vue.

Именно такого поведения я добивался, создавая этот пакет.

Шаг 5: Как работает переключение языков

Важно понимать, что Laravel Lang Sync Inertia использует текущую локаль Laravel.

Например:

use Illuminate\Support\Facades\App;App::setLocale('hi');syncLangFiles('messages');

Это загружает переводы на хинди для данного запроса.

В реальном приложении вы, как правило, будете хранить выбранный пользователем язык в сессии, настройках пользователя или другом подобном хранилище.

Затем ваш middleware в Laravel может устанавливать локаль для каждого запроса до того, как контроллер загрузит переводы.

Пакет берет на себя передачу нужных переводов. Ваше приложение по-прежнему отвечает за то, чтобы определить, какой язык выбрал пользователь.

Когда Inertia получает обновленные пропсы страницы для новой локали, хелперы фронтенда могут использовать новые значения переводов.

Это позволяет отделить выбор языка от доставки самих переводов.

Шаг 6: Что насчет React и Svelte?

Хотя в этом примере мы использовали Vue 3, пакет не ограничивается только Vue.

Реализация на стороне Laravel остается прежней.

Вам понадобится лишь фронтенд-хелпер для выбранного вами фреймворка.

 Пример для React

import { reactLang } from '@erag/lang-sync-inertia';export default function Dashboard() {
    const { __, trans } = reactLang();    return (
        <main>
            <h1>{__('messages.dashboard')}</h1>            <p>
                {trans('messages.welcome', {
                    name: 'Amit'
                })}
            </p>
        </main>
    );
}

 Пример для Svelte 5

Для Svelte используйте @inertiajs/svelte v3.

<script module lang="ts">
    import { svelteLang } from '@erag/lang-sync-inertia';    const { __, trans } = svelteLang();
</script><main>
    <h1>{__('messages.dashboard')}</h1>    <p>
        {trans('messages.welcome', {
            name: 'Amit'
        })}
    </p>
</main>

Ключи переводов, языковые файлы и контроллер Laravel остаются без изменений.

Таким образом, создаете ли вы фронтенд на Vue, React или Svelte, вы можете продолжать использовать ту же структуру локализации Laravel.

Шаг 7: Организация переводов в крупных приложениях

По мере роста вашего приложения держать все переводы в одном файле становится сложно.

Вам может захотеться использовать такую структуру:

lang/
└── en/
    ├── auth.php
    ├── messages.php
    └── admin/
        ├── users.php
        └── settings.php

Laravel Lang Sync Inertia поддерживает вложенные языковые директории.

Например:

syncLangFiles('admin.users');

Затем во Vue:

__('admin.users.title')

Это позволяет организовывать переводы по фичам или модулям, а не сваливать всё в один огромный файл.

Для приложений с несколькими дашбордами, административными панелями или сложными рабочими процессами такая организация имеет большое значение.

Бонус: Экспорт PHP-переводов Laravel в JSON

Иногда вам могут понадобиться именно JSON-файлы переводов для отдельного процесса сборки или фронтенд-воркфлоу.

В пакете также предусмотрена Artisan-команда для этого:

php artisan erag:generate-lang

По умолчанию она генерирует готовые для фронтенда JSON-файлы по пути:

resources/js/lang/

Пути к исходным файлам и результату можно настроить в config/inertia-lang.php.

Эта функция опциональна. Вам не нужно генерировать JSON-файлы, чтобы использовать стандартный рабочий процесс передачи переводов в Inertia.

Почему бы просто не использовать Vue I18n?

Это справедливый вопрос.

Vue I18n — это зрелое решение с возможностями, которые выходят за рамки простой передачи переводов Laravel. Если в вашем приложении уже настроена архитектура интернационализации, ориентированная на фронтенд, это может быть именно то, что вам нужно.

Laravel Lang Sync Inertia решает более узкую задачу.

Если Laravel уже является вашим источником истины для переводов, вы, возможно, не захотите поддерживать еще один набор языковых файлов специально для Vue.

С этим пакетом Laravel продолжает управлять данными переводов, в то время как Inertia делает выбранные переводы доступными для фронтенда.

Дело не в том, чтобы заменить каждую библиотеку интернационализации.

Дело в том, чтобы избавиться от дублирования работы для разработчиков, использующих Laravel и Inertia вместе.

Несколько вещей, о которых стоит помнить

Перед тем как использовать локализацию в продакшн-приложении, держите в голове несколько практических нюансов:

  • Убедитесь, что запрашиваемая локаль поддерживается вашим приложением.
  • Используйте middleware или другой механизм для каждого запроса, чтобы восстанавливать выбранную пользователем локаль.
  • Передавайте только те группы переводов, которые необходимы для вашей страницы.
  • Для новых переводов отдавайте предпочтение синтаксису плейсхолдеров Laravel :name.
  • При смене языка убедитесь, что Inertia получает свежие пропсы страницы для выбранной локали.

Эти небольшие решения облегчают поддержку многоязычных приложений по мере их роста.

Заключение

Добавление нового языка в приложение не должно означать переписывание одних и тех же переводов в нескольких местах.

Если вы уже используете Laravel с Inertia.js, у вас уже есть большая часть необходимой инфраструктуры для локализации.

Недостающий элемент — сделать эти переводы доступными для вашых фронтенд-компонентов чистым и последовательным образом.

Именно поэтому я создал Laravel Lang Sync Inertia.

Это проект с открытым исходным кодом, и я надеюсь, что он избавит других разработчиков на Laravel от рутинной настройки при создании многоязычных приложений.

Если вы работаете с Laravel, Vue 3, React или Svelte, обязательно попробуйте его.

 Ресурсы

Если вы сочтете его полезным, поставьте звездочку репозиторию на GitHub. А если вы столкнетесь с проблемой или у вас появится идея по улучшению, смело создавайте issue.

Спасибо за чтение!