Skip to content

Latest commit

 

History

History
162 lines (114 loc) · 4.48 KB

README.md

File metadata and controls

162 lines (114 loc) · 4.48 KB
Raw

Laravel Translator for Frontend

Laravel Translator is a package that allows you to use Laravel's localization features in your frontend code, with the same syntax you would use in your backend code and zero configuration.

This package was inspired by laravel-vue-i18n and lingua.

🧩 Features

  • Frontend framework-agnostic, works with any framework or even plain javascript (and even without Laravel)
  • Use the same translation files you use in your backend code (both php and json files are supported)
  • No extra configuration required: install, register and use
  • Zero SSR configuration required
  • No export step required, translations are parsed and bundled directly from your backend code by Vite
  • Support for hot reloading
  • Minimal and lightweight

🚀 Installation

ViteJS is required to use this package. Install the package via npm or yarn:

npm install -D laravel-translator

In your vite.config.js file, register the plugin:

import {defineConfig} from 'vite'
import laravelTranslator from 'laravel-translator/vite'

export default defineConfig({
    plugins: [
        // ...
        laravelTranslator()
    ]
})

Run npm run dev to start the development server, or npm run build to build your assets for production.

Remember to set the language in your html, for example in your app.blade.php file:

<html lang="{{ app()->getLocale() }}">

If you want to also pass the fallback locale to your frontend code, you can do so by adding the following line to your app.blade.php file:

<script>
    window.fallbackLocale = "{{ config('app.fallback_locale') }}"
</script>

🧑‍💻Usage

You can import the usual Laravel translation functions from the laravel-translator package:

import {__, trans, t, trans_choice} from 'laravel-translator'

__('user.welcome', {name: 'John'}) // Welcome, John!
trans('auth.failed') // These credentials do not match our records.
t('auth.failed') // ...

trans_choice('user.count', 1) // User
trans_choice('user.count', 2) // Users

Svelte

<script>
    import {__} from "laravel-translator"
</script>

<h1>{__('page.title')}</h1>

<p>{__('page.content')}</p>

Vue

Register the plugin:

...
.use(LaravelTranslatorVue, {
    locale: 'it'
    // fallbackLocale: 'en', optional
})
...

Use the functions function in your components:

<template>
    <div>
        <h1>{{ __('page.title') }}</h1>

        <p>{{ __('page.content') }}</p>
        <p>{{ t('page.content') }}</p>
        <p>{{ trans('page.content') }}</p>
        <p>{{ trans_choice('page.content') }}</p>
    </div>
</template>

Advanced usage

It's possible to set the locale and the fallback locale manually, by using the setLocale function:

import {setLocale} from "laravel-translator"

setLocale('it') // Set the locale to 'it'
setLocale('it', 'en') // Set the locale to 'it' and the fallback locale to 'en'

You can add additional path where to look for translation files on the Vite plugin options:

import {defineConfig} from 'vite'
import laravelTranslator from 'laravel-translator/vite'

export default defineConfig({
    plugins: [
        // ...
        laravelTranslator({
            langPath: 'resources/js/translations', // By default, the package looks for translations in the 'lang' folder
            additionalLangPaths: ['vendor/my-package/lang'] // You can add additional paths where to look for translations
        })
    ]
})

⚙️ How it works

This package uses Vite Virtual Modules feature to parse your translations files and make them available in your frontend code, without the need to export them to a separate file.

In development mode, the translations are parsed and bundled on the fly, and hot reloaded when the files change.

In production mode, the translations are parsed and bundled automatically when you run npm run build.

⚖️ License

The MIT License (MIT). Please see License File for more information.

🏅 Credits