zenphp/zorah

Add your Laravel language translations to your asset pipeline for use in Javascript packages like Vue or React.

v1.0.2 2024-09-27 01:15 UTC

Requires

• php: ^8.3
• illuminate/console: ^11.24
• illuminate/filesystem: ^11.24
• illuminate/support: ^11.24

Requires (Dev)

• mockery/mockery: ^1.6
• pestphp/pest: ^3.2
• pestphp/pest-plugin-laravel: ^3.0
• pestphp/pest-plugin-type-coverage: ^3.0
• zenphp/fixr: ^1.0.2

MIT

• SMV

README

About Zorah

With Zorah you can add your Laravel language translations to your asset pipeline for use in Javascript packages like Vue or React.

Zorah provides two Javascript __() or __trans() translation helper functions that work like Laravel's, making it easy to use your Laravel translations in Javascript.

The package works similar to Ziggy for routing, but without the Blade directive.

Zorah supports all versions of Laravel from 11.x onwards, and all modern browsers.

• About Zorah
• Installation
• Setup - Javascript Frameworks - Vue - Svelte
• Usage - The trans() helper

Installation

Install Zorah into your Laravel app via composer:

composer require zenphp/zorah --dev

Setup

Javascript Frameworks

Zorah provides an Artisan command to output its config and routes to a file: php artisan zorah:generate. By default this command stores your translations at resources/js/zorah.js.

The file generated by php artisan zorah:generate will look something like this:

Alternatively, you can compile the translations to resources/js in your dev and build steps in package.json:

"build:assets": "php artisan zorah:generate",

// zorah.js

const Zorah = {
  translations: {"en": {"php": {}, "json": {}}};
};
if (typeof window !== 'undefined' && typeof window.Zorah !== 'undefined') {
  Object.assign(Zorah.translations, window.Zorah.translations);
}

export { Zorah }

Create an alias to make importing Zorah's core source files easier:

// vite.config.js
export default defineConfig({
  resolve: {
    alias: {
      // for other frameworks
      'zorah-js': resolve(__dirname, 'vendor/zenphp/zorah/dist/client.js'),
      // for vue
      'zorah-js': resolve(__dirname, 'vendor/zenphp/zorah/dist/index.js'),
      zorah: resolve(__dirname, 'vendor/zenphp/zorah/dist/vue.js'),
    },
  },
});

// webpack.mix.js

// Mix v6
const path = require('path');

mix.alias({
  // for other frameworks
  'zorah-js': path.resolve(__dirname, 'vendor/zenphp/zorah/dist/client.js'),
  // for Vue
  'zorah-js': path.resolve(__dirname, 'vendor/zenphp/zorah/dist/index.js'),
  zorah: path.resolve(__dirname, 'vendor/zenphp/zorah/dist/vue.js'),
});

// Mix v5
const path = require('path');

mix.webpackConfig({
  resolve: {
    alias: {
      // for other frameworks
      'zorah-js': path.resolve(__dirname, 'vendor/zenphp/zorah/dist/client.js'),
      // for Vue
      'zorah-js': path.resolve(__dirname, 'vendor/zenphp/zorah/dist/index.js'),
      zorah: path.resolve(__dirname, 'vendor/zenphp/zorah/dist/vue.js'),
    },
  },
});

Add the following to your app.blade.php so that translation functions will use the current locale.

<script>
  window.locale = '{{ app()->getLocale() }}';
</script>

Finally, import and use Zorah like any other JavaScript library.

import { ZorahVue } from 'zorah'
import { Zorah } from '../zorah.js'


// ...

__(key: string, replacers: array, config: Zorah)

// or

trans(key: string, replacers: array, config: Zorah)

Vue

Zorah includes a vue plugin to make it easy to use trans() or __() helpers throughout your app:

import { ZorahVue } from 'zorah';
import { Zorah } from '../zorah.js';

Then use it in your app (register Zorah plugin):

...
.use(ZorahVue, Zorah)

Svelte

There is no built in integration for svelte, however to avoid passing in the Zorah configuration object you can create translation helper file.

// i18n.svelte

<script context="module">
  import { trans as t } from 'zorah-js/'
  import { Zorah } from '../zorah.js'

  // window.locale = document.documentElement.lang; // optional if not set in app.blade.php

  export function __(key, replace, config=Zorah){
    return t(key, replace, config);
  }
  export function trans(key, replace, config=Zorah){
    return t(key, replace, config);
  }

</script>


// Dashboard.svelte
<script>
import {__} from "@/i18n.svelte";
</script>

<div>{__("key")}</div>

Usage

The trans() helper

Both trans() or __() helper function works like Laravel's - You can pass the key of one of your translations, and a key-pair object for replacing the placeholders as the second argument.

Basic usage

// lang/en/messages.php
return [
  'welcome' => 'Welcome to our application!',
]

// Dashbaord.js
__('messages.welcome'); // Welcome to our application!

With parameters

// lang/en/messages.php
return [
  'welcome' => 'Welcome, :name',
]

// Dashbaord.js
__('messages.welcome', { name: 'Zorah' }); // Welcome, Zorah

With multiple parameters

// lang/en/messages.php
return [
  'welcome' => 'Welcome, :name! There are :count apples.',
]

// Dashbaord.js
__('messages.welcome', { name: 'Zorah', count: 8 }); // Welcome, Zorah! There are 8 apples.