PHPackages                             tooinfinity/lingua - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Localization & i18n](/categories/localization)
4. /
5. tooinfinity/lingua

ActiveLibrary[Localization & i18n](/categories/localization)

tooinfinity/lingua
==================

Zero-config localization for Laravel 12 with Inertia.js and React

v0.2.0(5mo ago)02MITPHPPHP ^8.4CI passing

Since Jan 17Pushed 1mo agoCompare

[ Source](https://github.com/tooinfinity/lingua)[ Packagist](https://packagist.org/packages/tooinfinity/lingua)[ GitHub Sponsors](https://github.com/tooinfinity)[ RSS](/packages/tooinfinity-lingua/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (2)Dependencies (9)Versions (7)Used By (0)

Lingua
======

[](#lingua)

[![Tests](https://github.com/tooinfinity/lingua/actions/workflows/tests.yml/badge.svg)](https://github.com/tooinfinity/lingua/actions/workflows/tests.yml)[![Formats](https://github.com/tooinfinity/lingua/actions/workflows/formats.yml/badge.svg)](https://github.com/tooinfinity/lingua/actions/workflows/formats.yml)[![PHP Version](https://camo.githubusercontent.com/5d674320982435ba09ebeabc34277cce26ae91fff1efcbcb7049276ec37e93a7/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f746f6f696e66696e6974792f6c696e677561)](https://packagist.org/packages/tooinfinity/lingua)[![Laravel Version](https://camo.githubusercontent.com/a6874a9d36788f06a2b9c7b9a5559e19cf4dd5d445b327ba6e2038bf704f57c7/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c61726176656c2d31312e7825323025374325323031322e782d7265642e737667)](https://laravel.com)[![Latest Stable Version](https://camo.githubusercontent.com/365bb5fe911c38d4ad258f20dd569f2bc240ce201fe7eb7b0fb2738d90908e87/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f746f6f696e66696e6974792f6c696e677561)](https://packagist.org/packages/tooinfinity/lingua)[![License](https://camo.githubusercontent.com/6030a2f7b9d05443ca39a6f2a8b9b06878eac4884909ec584ed200c2dbcfddc7/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f746f6f696e66696e6974792f6c696e677561)](LICENSE.md)

> ⚠️ **Under Development**: This package is currently under active development and is not ready for production use.

Share Laravel translations with your Inertia.js + React frontend.

Quick Start
-----------

[](#quick-start)

### 1. Install

[](#1-install)

```
composer require tooinfinity/lingua
php artisan lingua:install
```

This installs the Laravel package, publishes the config, and installs the React package (`@tooinfinity/lingua-react`).

### 2. Configure Locales

[](#2-configure-locales)

Edit `config/lingua.php`:

```
'locales' => ['en', 'fr', 'es'],
```

### 3. Middleware

[](#3-middleware)

**The middleware is auto-registered to the `web` group by default.** No action needed for most apps.

To disable auto-registration and add manually:

```
// config/lingua.php
'middleware' => [
    'auto_register' => false,
],

// bootstrap/app.php
->withMiddleware(function (Middleware $middleware) {
    $middleware->web(append: [
        \TooInfinity\Lingua\Http\Middleware\LinguaMiddleware::class,
    ]);
})
```

### 4. Create Translations

[](#4-create-translations)

```
lang/
├── en/
│   └── messages.php
└── fr/
    └── messages.php

```

```
// lang/en/messages.php
return [
    'welcome' => 'Welcome!',
    'greeting' => 'Hello, :name!',
];

// lang/fr/messages.php
return [
    'welcome' => 'Bienvenue!',
    'greeting' => 'Bonjour, :name!',
];
```

### 5. Use in React

[](#5-use-in-react)

```
import { useTranslations } from '@tooinfinity/lingua-react';

function Welcome() {
    const { __, locale, locales } = useTranslations();

    return (

            {__('messages.welcome')}
            {__('messages.greeting', { name: 'John' })}
            Current: {locale}

    );
}
```

Locale Switching
----------------

[](#locale-switching)

```
import { router } from '@inertiajs/react';
import { useTranslations } from '@tooinfinity/lingua-react';

function LocaleSwitcher() {
    const { locale, locales } = useTranslations();

    const switchLocale = (newLocale: string) => {
        router.post('/locale', { locale: newLocale });
    };

    return (

            {locales.map((loc) => (
                 switchLocale(loc)}
                    disabled={loc === locale}
                >
                    {loc.toUpperCase()}

            ))}

    );
}
```

Translation Groups (Optional)
-----------------------------

[](#translation-groups-optional)

Load only the translations needed for a specific request by passing group names to the middleware. When no groups are provided, Lingua shares all translations.

```
Route::middleware(['web', 'lingua:common,validation'])->get('/dashboard', function () {
    // ...
});
```

You can also load specific groups manually via `Lingua::translationsFor(['common', 'validation'])`.

API Reference
-------------

[](#api-reference)

### `useTranslations()` Hook

[](#usetranslations-hook)

```
const { __, locale, locales, direction, isRtl } = useTranslations();

__('messages.welcome')                    // "Welcome!"
__('messages.greeting', { name: 'John' }) // "Hello, John!"
```

PropertyTypeDescription`__``function`Translation function`locale``string`Current locale`locales``string[]`Supported locales`direction``'ltr' | 'rtl'`Text direction`isRtl``boolean`Is RTL locale### Facade

[](#facade)

```
use TooInfinity\Lingua\Facades\Lingua;

Lingua::getLocale();           // Get current locale
Lingua::setLocale('fr');       // Set locale (optionally persists cookie)
Lingua::supportedLocales();    // Get supported locales
Lingua::translations();        // Get all translations (missing keys fall back to default locale)
```

### Fallback Locale Behavior

[](#fallback-locale-behavior)

When a translation key is missing in the current locale, Lingua automatically fills it from the default locale. This applies to:

- PHP translation groups loaded via `Lingua::translationGroup()` and `Lingua::translations()`
- JSON translations loaded via `Lingua::translations()` when `translation_driver` is `json`

If the current locale already matches the default locale, no fallback merge occurs.

```
// config/lingua.php
'default' => 'en',
```

```
// lang/en/auth.php
return [
    'login' => 'Login',
    'logout' => 'Logout',
];

// lang/fr/auth.php
return [
    'login' => 'Connexion',
];

Lingua::setLocale('fr');

// 'logout' comes from the default locale
Lingua::translationGroup('auth');
// ['login' => 'Connexion', 'logout' => 'Logout']
```

### Routes

[](#routes)

MethodURIDescriptionPOST`/locale`Switch locale> **Note:** The route prefix can be configured via `config('lingua.routes.prefix')`.

Translation File Formats
------------------------

[](#translation-file-formats)

Lingua supports both PHP and JSON translation files. Configure the driver in `config/lingua.php`:

```
'translation_driver' => 'php', // or 'json'
```

### PHP Translations (Default)

[](#php-translations-default)

PHP translations are organized in groups (files) under `lang/{locale}/`:

```
lang/
├── en/
│   ├── messages.php
│   └── validation.php
└── fr/
    ├── messages.php
    └── validation.php

```

```
// lang/en/messages.php
return [
    'welcome' => 'Welcome!',
    'greeting' => 'Hello, :name!',
];
```

**Shared to React as:**

```
{
  "messages": {
    "welcome": "Welcome!",
    "greeting": "Hello, :name!"
  },
  "validation": { ... }
}
```

Access in React: `__('messages.welcome')`

### JSON Translations

[](#json-translations)

JSON translations use a flat key-value structure in `lang/{locale}.json`:

```
lang/
├── en.json
└── fr.json

```

```
// lang/en.json
{
  "Welcome!": "Welcome!",
  "Hello, :name!": "Hello, :name!",
  "auth.login": "Login",
  "auth.logout": "Logout"
}
```

**Shared to React as-is (flat structure):**

```
{
  "Welcome!": "Welcome!",
  "Hello, :name!": "Hello, :name!",
  "auth.login": "Login",
  "auth.logout": "Logout"
}
```

Access in React: `__('Welcome!')` or `__('auth.login')`

> **Tip:** JSON translations are ideal for simple apps or when using Laravel's `__()` helper with literal string keys.

Advanced
--------

[](#advanced)

### Custom Controller

[](#custom-controller)

```
// config/lingua.php
'controller' => \App\Http\Controllers\LocaleController::class,
```

```
namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Illuminate\Validation\Rule;
use TooInfinity\Lingua\Lingua;

class LocaleController
{
    public function __invoke(Request $request, Lingua $lingua)
    {
        $validated = $request->validate([
            'locale' => ['required', 'string', Rule::in($lingua->supportedLocales())],
        ]);

        $lingua->setLocale($validated['locale']);

        return redirect()->route('dashboard');
    }
}
```

License
-------

[](#license)

MIT License. See [LICENSE.md](LICENSE.md).

###  Health Score

37

—

LowBetter than 81% of packages

Maintenance83

Actively maintained with recent releases

Popularity2

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity47

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 95.7% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~4 days

Total

2

Last Release

162d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/51855906?v=4)[TouwfiQ Meghlaoui](/maintainers/tooinfinity)[@tooinfinity](https://github.com/tooinfinity)

---

Top Contributors

[![tooinfinity](https://avatars.githubusercontent.com/u/51855906?v=4)](https://github.com/tooinfinity "tooinfinity (44 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (2 commits)")

---

Tags

laravellocalizationi18ninertiareactrtl

###  Code Quality

TestsPest

Static AnalysisPHPStan, Rector

Code StyleLaravel Pint

Type Coverage Yes

### Embed Badge

![Health badge](/badges/tooinfinity-lingua/health.svg)

```
[![Health](https://phpackages.com/badges/tooinfinity-lingua/health.svg)](https://phpackages.com/packages/tooinfinity-lingua)
```

###  Alternatives

[outhebox/laravel-translations

Manage your Laravel translations with a beautiful UI. Add, edit, delete, import, and export translations with ease.

813100.4k](/packages/outhebox-laravel-translations)[typicms/base

A modular multilingual CMS built with Laravel, enabling developers to manage structured content like pages, news, events, and more.

1.6k20.4k](/packages/typicms-base)[vemcogroup/laravel-translation

Translation package for Laravel to scan for localisations and up/download to poeditor

136327.1k3](/packages/vemcogroup-laravel-translation)[erag/laravel-lang-sync-inertia

A powerful Laravel package for syncing and managing language translations across backend and Inertia.js (Vue/React/Svelte) frontends, offering effortless localization, auto-sync features, and smooth multi-language support for modern Laravel applications.

4925.3k](/packages/erag-laravel-lang-sync-inertia)[pmochine/laravel-tongue

🎉 Finally a subdomain localization that works how you want it to work. 🌐

4158.4k](/packages/pmochine-laravel-tongue)[jayesh/laravel-gemini-translator

An interactive command to extract and generate Laravel translations using Gemini AI.

702.3k1](/packages/jayesh-laravel-gemini-translator)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)