From 2f29ddcd4e1e729593a107dd2cf9859a761e8008 Mon Sep 17 00:00:00 2001 From: Sergio Brighenti Date: Fri, 15 Dec 2023 11:00:32 +0100 Subject: [PATCH] Add README.md --- README.md | 153 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 153 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..4d70158 --- /dev/null +++ b/README.md @@ -0,0 +1,153 @@ + + +> 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](https://github.com/xiCO2k/laravel-vue-i18n) +and [lingua](https://github.com/cyberwolf-studio/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 +- 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: + +```bash +npm install -D laravel-translator +``` + +In your `vite.config.js` file, register the plugin: + +```js +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 + + +``` + +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: + +```html + + +``` + +## 🧑‍💻Usage + +You can import the usual Laravel translation functions from the `laravel-translator` package: + +```js +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 + +```html + + + +

{__('page.title')}

+ +

{__('page.content')}

+``` + +#### Vue + +```html + + + + +``` + +### Advanced usage + +It's possible to set the locale and the fallback locale manually, by using the `setLocale` function: + +```js +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: + +```js +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](https://vitejs.dev/) 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](LICENSE.md) for more information. + +## 🏅 Credits + +- [Sergio Brighenti](https://github.com/sergix44/) +- [All Contributors](https://github.com/sergix44/laravel-translator-js/contributors) \ No newline at end of file