README

This package provides a simple way to manage localization in Laravel with Vue3, React and InertiaJS. While it is very opinionated, it is also very simple to use and requires no additional configuration.

How it works

1. You create your php language files, as you would normally do in Laravel
2. You run the npm run lang command to watch for changes in your language files and generate the corresponding JSON files
3. The ServiceProvider will automatically share the generated JSON file, corresponding to the current locale, with your InertiaJS app
4. You can use the "txt(...)" helper function in your Vue3 components to access the localized strings, like you would with the __() helper function in Laravel
5. That's it! Easy-peasy lemon squeezey!

Installation

composer require antonioprimera/laravel-js-localization

After installing the package, you should run the install command, which will publish the package configuration file and will set up the necessary npm script for watching the language files for changes and generate the corresponding JSON files.

php artisan js-localization:install

This will do the following things:

1. Create a symlink for the language watcher js file in your project's root directory.
2. Add the 'lang' npm script to your package.json file, so you can run 'npm run lang' to start the language watcher.
3. Add the laravel-inertia-vue-translator or laravel-inertia-react-translator depending on your frontend framework, chalk and chokidar npm packages to your package.json file. At the end it runs npm install to install the newly added npm packages.
4. Optionally publish the package configuration file (you can also do this manually with php artisan vendor:publish --tag=js-localization-config).
5. Optionally publish the language files, if no "lang" folder exists in your project's root directory (you can also do this manually with php artisan lang:publish).
6. Provide you with the necessary steps to manually add the corresponding Inertia plugin to your Vue3 app (from package laravel-inertia-vue-translator installed in step 3).

Warning!!!

The install command contains some automated steps, which will inject code into your files. While it tries to be as safe as possible, it is always recommended to check the changes made to your files and to have a clean git history, so you can easily revert the changes if something goes wrong.

Usage

Laravel

In order to use the package, you need to create your language files in the lang directory, as you would normally do in Laravel. You can create several files for each language and each language corresponds to a directory in the lang directory.

At the moment, the package only supports the .php language files, but support for JSON files is planned for the future.

While working with the language files, you should have the file watcher running, using the npm run lang command. The watcher creates a _.json file in the lang directory, for each found locale, which contains all the translations for that locale. These files are automatically shared with your InertiaJS app, so you can access the translations in your Vue3 components (only the translations for the current locale are shared).

This package also handles the pluralization of the strings, as Laravel does. You can use the :count, :value or :n placeholder in your strings to be replaced with the count value, when using the txts(...) helper function.

// resources/lang/en/example.php
return [
    'welcome' => 'Welcome to our application!',
    'apples' => '{0} :name has no apples|{1} :name has one apple|[2,10] :name has :count apples|[11,*] :name has too many apples!',
];

Inertia + Vue3

The laravel-inertia-vue-translator package exports 2 helper functions, registered directly on the Inertia object, which you can use in your Vue3 templates to translate your strings:

• txt(key, replacements = {}): This function is used to access the localized strings. It works similarly to the __() helper function in Laravel.
• txts(key, count, replacements = {}): This function is used to access the pluralized localized strings. It works similarly to the __() helper function in Laravel, but expects a number as the second argument, which is used to determine the plural form of the string.

<template>
  <div>
    <h1>{{ txt("example.welcome") }}</h1>
    <p>{{ txts('example.apples', 5, {name: 'Mary'} }}</p>
  </div>
</template>

In order to use the txt(...) and txts(...) helper functions in your Vue3 script section, you need to import the useTranslator function from the package, which injects the txt(...) and txts(...) functions into the current Vue3 component.

<script setup>
// Import the useTranslator function from the laravel-inertia-vue-translator package
import { useTranslator } from "laravel-inertia-vue-translator";

// Inject the txt(...) and txts(...) functions into the current Vue3 component
const { txt, txts } = useTranslator();

// Use the txt(...) and txts(...) functions to access the localized strings
const welcome = txt("example.welcome");
const apples = txts("example.apples", 5, { name: "Mary" });
</script>

Inertia + React

The laravel-inertia-react-translator package exports a TranslatorProvider component, which you can use to wrap your Inertia app. This component provides the txt(...) helper function to your React components via the useTranslator hook.

import React from "react";
import { TranslatorProvider } from "laravel-inertia-react-translator";
import { usePage } from "@inertiajs/react";

const inertiaDictionary = () => usePage().props.dictionary;

<TranslatorProvider getDictionary={inertiaDictionary}>
  {/* your app */}
</TranslatorProvider>;

You can then use the useTranslator hook in your React components to access the txt(...) helper function.

import React from "react";
import { useTranslator } from "laravel-inertia-react-translator";
const MyComponent = () => {
  const { txt } = useTranslator();

  return (
    <div>
      <h1>{txt("example.welcome")}</h1>
      <p>{txt("example.apples", 5, { name: "Mary" })}</p>
    </div>
  );
};
export default MyComponent;

LocaleManager

The package also provides a LocaleManager facade, which you can use to work with locales in your Laravel app. The facade provides the following methods:

use AntonioPrimera\LaravelJsLocalization\Facades\LocaleManager;

// Get all the available locales via: config('app.available_locales', ['en'])
$locales = LocaleManager::availableLocales();

// Get the default locale via: config('app.locale', 'en')
$defaultLocale = LocaleManager::defaultLocale();

// Get the fallback locale via: config('app.fallback_locale', 'en')
$fallbackLocale = LocaleManager::fallbackLocale();

// Get the current locale via: app()->getLocale()
$locale = LocaleManager::currentLocale();

// Get the locale for the authenticated user, fallback to the session locale and then to the default locale
$userLocale = LocaleManager::authenticatedUserLocale();

// Set the locale for the current request and store it in the session
LocaleManager::setLocale('en');

// Store the locale in the session (will not change the current locale)
LocaleManager::setSessionLocale('en');

// Get the locale from the session
$locale = LocaleManager::sessionLocale();

// Check if a locale is available (checks the available locales)
$available = LocaleManager::isValidLocale('en');

Configuration

The package configuration file is published in the config directory of your Laravel app, after running the install command. You can use this file to configure the package to your needs.

Here is the default configuration file, with the default values explained:

return [
	/**
	 * The folder where the language files are stored, relative to the project root
	 *
	 * By default, the language files are stored in the 'lang' folder in the project root.
	 */
	'language-folder' => 'lang',

	/**
	 * The class that sets the locale in the app
	 *
	 * This class must implement AntonioPrimera\LaravelJsLocalization\Interfaces\LocaleSetter.
	 * By default, the UserSessionLocaleSetter is used, which tries to determine the locale from the authenticated user,
	 * if a user is logged in, then falls back to the session locale, and finally to the default app locale.
	 * Replace this with your own class if you have a different way of determining the locale.
	 */
	'locale-setter' => \AntonioPrimera\LaravelJsLocalization\LocaleSetters\UserSessionLocaleSetter::class,

	/**
	 * The property of the authenticated user model that holds the locale
	 *
	 * If you have a property in your user model, that holds the locale of the user, you can set it here,
	 * and the locale will be set to the value of this property when the user is authenticated.
	 * You can leave it commented out if you don't have such a property on your user model.
	 */
	'user-locale-property' => 'language',
];

Related resources

• Vue3 NPM Package: laravel-inertia-vue-translator
• React NPM Package: laravel-inertia-react-translator