Laravel Vue i18n

https://github.com/xico2k/laravel-vue-i18n
Admin
Laravel Vue i18n is a Vue 3 plugin that connects Laravel localization files with Vue applications,...
Tokens:34,364
Snippets:405
Trust Score:9.6
License:MIT
Update:2 months ago
Show doc for...
Tokens:
Raw
### File Storage Example

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/_autodocs/pluralization.md

Example of using byte-based ranges for storage display.

```json
{
  "storage": "{1} :count byte|[2,1024] :count bytes|[1024,*] :count KB"
}
```

```typescript
transChoice('storage', 1)     // "1 byte"
transChoice('storage', 500)   // "500 bytes"
transChoice('storage', 1024)  // "1024 KB"
```

--------------------------------

### E-commerce Product Display Example

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/_autodocs/pluralization.md

Example of using ranges and specific counts for cart items.

```json
{
  "cart.items": "{0} Your cart is empty|{1} Your cart has one item|[2,*] Your cart has :count items"
}
```

```typescript
transChoice('cart.items', 0)   // "Your cart is empty"
transChoice('cart.items', 1)   // "Your cart has one item"
transChoice('cart.items', 3)   // "Your cart has 3 items"
transChoice('cart.items', 100) // "Your cart has 100 items"
```

--------------------------------

### Install the package

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/README.md

Use npm or yarn to add the package to your project dependencies.

```sh
npm i laravel-vue-i18n
```

```sh
yarn add laravel-vue-i18n
```

--------------------------------

### Time Display Example

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/_autodocs/pluralization.md

Example of using time ranges for relative time strings.

```json
{
  "time.ago": "{1} :count second ago|[2,60] :count seconds ago|[61,3600] :count minute ago|[3601,*] :count hour ago"
}
```

```typescript
transChoice('time.ago', 1)      // "1 second ago"
transChoice('time.ago', 30)     // "30 seconds ago"
transChoice('time.ago', 120)    // "2 minute ago" (120 seconds)
transChoice('time.ago', 7200)   // "2 hour ago" (7200 seconds)
```

--------------------------------

### Basic Plugin Setup

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/_autodocs/vue-integration.md

Initializes the i18nVue plugin with a basic language resolution function.

```typescript
import { createApp } from 'vue'
import { i18nVue } from 'laravel-vue-i18n'
import App from './App.vue'

createApp(App)
  .use(i18nVue, {
    resolve: lang => import(`./lang/${lang}.json`)
  })
  .mount('#app')
```

--------------------------------

### Configure I18n Instances

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/_autodocs/types.md

Examples of initializing the I18n class with minimal, full, and asynchronous loader configurations.

```typescript
import { I18n } from 'laravel-vue-i18n'

// Minimal configuration
new I18n({
  resolve: lang => import(`./lang/${lang}.json`)
})

// Full configuration
new I18n({
  lang: 'pt',
  fallbackLang: 'en',
  fallbackMissingTranslations: true,
  resolve: lang => import(`./lang/${lang}.json`),
  onLoad: (lang) => console.log(`Loaded ${lang}`)
})

// With async loader
new I18n({
  lang: 'en',
  resolve: async (lang) => {
    const response = await fetch(`/api/translations/${lang}`)
    return response.json()
  }
})
```

--------------------------------

### Configure Vite Plugin Paths

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/_autodocs/types.md

Examples of initializing the Vite i18n plugin with default, custom, and additional language paths.

```typescript
import i18n from 'laravel-vue-i18n/vite'

// Default path
i18n()

// Custom path
i18n('resources/lang')

// With additional paths
i18n({
  langPath: 'lang',
  additionalLangPaths: ['public/locales', 'vendor/package/translations']
})
```

--------------------------------

### Language Loading Configuration

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/_autodocs/README.md

Setup for language resolution during plugin initialization and manual loading at runtime.

```typescript
// At plugin setup
.use(i18nVue, {
  resolve: lang => import(`./lang/${lang}.json`)
})

// At runtime
await loadLanguageAsync('pt')
```

--------------------------------

### Use LanguageJsonFileInterface

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/_autodocs/types.md

Examples of importing language files and using them with the I18n resolver.

```typescript
// From ES module import
import enLang from './lang/en.json'
// { default: { "Welcome!": "Welcome!", ... } }

// From async dynamic import
const ptLang = await import('./lang/pt.json')
// { default: { "Welcome!": "Bem-vindo!", ... } }

// Direct object
const frLang: LanguageJsonFileInterface = {
  default: {
    'Welcome!': 'Bienvenue!',
    'Goodbye!': 'Au revoir!'
  }
}

// Using with I18n resolver
new I18n({
  resolve: (lang) => import(`./lang/${lang}.json`)
  // Returns LanguageJsonFileInterface
})
```

--------------------------------

### Use LanguageInterface

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/_autodocs/types.md

Examples of defining a language object and accessing loaded languages.

```typescript
// Typical structure
const portuguese: LanguageInterface = {
  lang: 'pt',
  messages: {
    'Welcome!': 'Bem-vindo!',
    'auth.login': 'Entrar',
    'auth.logout': 'Sair',
    'items.0': 'Item 1',
    'items.1': 'Item 2'
  }
}

// Accessed via I18n.loaded
import { I18n } from 'laravel-vue-i18n'
const loadedLanguages: LanguageInterface[] = I18n.loaded
```

--------------------------------

### Configure Webpack/Laravel Mix

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/_autodocs/configuration.md

Setup the plugin for Laravel Mix environments with custom path support.

```javascript
// webpack.mix.js
const mix = require('laravel-mix')
require('laravel-vue-i18n/mix')

mix.i18n()
mix.i18n('resources/lang') // Custom path

// main.js
import { createApp } from 'vue'
import { i18nVue } from 'laravel-vue-i18n'

createApp()
  .use(i18nVue, {
    resolve: lang => import(`../../lang/${lang}.json`)
  })
  .mount('#app')
```

--------------------------------

### Access i18n instance in Setup function

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/_autodocs/vue-integration.md

Use the inject function to retrieve the i18n instance within a Vue setup function.

```typescript
import { inject } from 'vue'

export default {
  setup() {
    const i18n = inject('i18n')

    const currentLang = i18n.getActiveLanguage()
    const isLoaded = i18n.isLoaded('pt')

    return { currentLang, isLoaded }
  }
}
```

--------------------------------

### Translate with Composition API

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/_autodocs/vue-integration.md

Use trans and transChoice for static translation strings within the setup function.

```typescript
import { defineComponent, ref } from 'vue'
import { trans, transChoice, loadLanguageAsync } from 'laravel-vue-i18n'

export default defineComponent({
  setup() {
    const userName = ref('John')

    return {
      welcome: trans('Welcome!'),
      greeting: trans('Hello, :name!', { name: userName.value }),
      items: transChoice('One item|Many items', 5)
    }
  }
})
```

--------------------------------

### Implement reactive language switching with Composition API

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/_autodocs/vue-integration.md

Utilizes wTrans, loadLanguageAsync, and ref to handle language reactivity in script setup.

```vue
<template>
  <div>
    <h1>{{ welcome }}</h1>

    <select v-model="language" @change="changeLanguage">
      <option value="en">English</option>
      <option value="pt">Português</option>
      <option value="es">Español</option>
    </select>

    <button @click="toggleLanguage">
      Switch to {{ language === 'en' ? 'Portuguese' : 'English' }}
    </button>
  </div>
</template>

<script setup>
import { ref } from 'vue'
import { wTrans, loadLanguageAsync, getActiveLanguage } from 'laravel-vue-i18n'

const language = ref(getActiveLanguage())
const welcome = wTrans('Welcome!')

const changeLanguage = async () => {
  await loadLanguageAsync(language.value)
}

const toggleLanguage = async () => {
  const newLang = language.value === 'en' ? 'pt' : 'en'
  await loadLanguageAsync(newLang)
  language.value = newLang
}
</script>
```

--------------------------------

### Define PHP Translation File Content

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/_autodocs/configuration.md

Example of a PHP array returning translation keys and values.

```php
<?php

return [
    'login' => 'Login',
    'logout' => 'Logout',
    'register' => 'Register',
    'nested' => [
        'key' => 'Value'
    ]
];
```

--------------------------------

### Install Vue Plugin

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/_autodocs/API-REFERENCE.md

Registers the i18nVue plugin with the Vue application instance to provide global translation properties.

```typescript
import { createApp } from 'vue'
import { i18nVue } from 'laravel-vue-i18n'

createApp()
  .use(i18nVue, {
    lang: 'pt',
    resolve: lang => import(`../../lang/${lang}.json`)
  })
  .mount('#app')
```

--------------------------------

### Multi-language Pluralization Rules

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/_autodocs/pluralization.md

Examples of how different languages define plural forms.

```json
{
  "items": "{1} One item|[2,*] :count items"
}
```

```json
{
  "items": "{1} :count товар|[2,4] :count товара|[5,*] :count товаров"
}
```

```json
{
  "items": ":count أشياء|:count شيء|:count شيء|:count أشياء|:count أشياء|:count أشياء"
}
```

--------------------------------

### Vue Component Integration Testing

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/_autodocs/examples.md

Demonstrates testing a Vue component by installing the i18nVue plugin within the test environment.

```typescript
import { describe, it, expect } from 'vitest'
import { mount } from '@vue/test-utils'
import { i18nVue } from 'laravel-vue-i18n'
import MyComponent from './MyComponent.vue'

describe('MyComponent', () => {
  it('uses i18n translations', () => {
    const wrapper = mount(MyComponent, {
      global: {
        plugins: [
          [i18nVue, {
            resolve: () => ({
              default: {
                'Welcome!': 'Welcome!'
              }
            })
          }]
        ]
      }
    })

    expect(wrapper.text()).toContain('Welcome!')
  })
})
```

--------------------------------

### Install laravel-vue-i18n plugin

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/_autodocs/INDEX.md

Register the i18nVue plugin with the Vue application instance, providing a resolver function for language files.

```typescript
import { createApp } from 'vue'
import { i18nVue } from 'laravel-vue-i18n'

createApp(App)
  .use(i18nVue, {
    resolve: lang => import(`./lang/${lang}.json`)
  })
  .mount('#app')
```

--------------------------------

### Get Active Language

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/README.md

Retrieve the currently active language code.

```jsx
import { getActiveLanguage } from 'laravel-vue-i18n';

const lang = getActiveLanguage(); // en
```

--------------------------------

### Configure Build Tool Plugins

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/_autodocs/README.md

Import and register the i18n plugin for Vite or Mix build environments.

```javascript
import i18n from 'laravel-vue-i18n/vite'
```

```javascript
require('laravel-vue-i18n/mix')
then mix.i18n()
```

--------------------------------

### Configure Vue Plugin Instances

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/_autodocs/types.md

Demonstrates initializing the i18nVue plugin with shared and non-shared instance configurations.

```typescript
import { createApp } from 'vue'
import { i18nVue } from 'laravel-vue-i18n'

// Shared instance (default, all Vue apps use the same instance)
createApp()
  .use(i18nVue, {
    lang: 'pt',
    resolve: lang => import(`./lang/${lang}.json`)
  })
  .mount('#app-1')

// Non-shared instances (each app has its own instance)
createApp()
  .use(i18nVue, {
    lang: 'es',
    shared: false,
    resolve: lang => import(`./lang/${lang}.json`)
  })
  .mount('#app-2')

createApp()
  .use(i18nVue, {
    lang: 'pt',
    shared: false,
    resolve: lang => import(`./lang/${lang}.json`)
  })
  .mount('#app-3')
```

--------------------------------

### Get Active Language

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/_autodocs/API-REFERENCE.md

Retrieves the currently active language code as a string.

```typescript
import { getActiveLanguage } from 'laravel-vue-i18n'

const lang = getActiveLanguage() // "pt"
```

--------------------------------

### OptionsInterface

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/_autodocs/types.md

Configuration options for creating an I18n instance or the plugin.

```APIDOC
## OptionsInterface

### Description
Configuration options for creating an I18n instance or the plugin.

### Parameters
- **lang** (string) - Optional - The current language code (e.g., 'en', 'pt_BR'). Automatically detected from <html lang=""> if not set.
- **fallbackLang** (string) - Optional - Language to fall back to if the requested language cannot be loaded. Default: 'en'.
- **fallbackMissingTranslations** (boolean) - Optional - If true, falls back to fallbackLang for missing translation keys instead of showing the key itself. Default: false.
- **resolve** (function) - Optional - Callback function that returns a Promise or direct object with translation data. Called with language code as parameter.
- **onLoad** (function) - Optional - Callback executed when a language is successfully loaded. Receives the language code.
```

--------------------------------

### loadLanguageAsync(lang: string, dashLangTry?: boolean, ignoreAbort?: boolean): Promise<string | void>

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/_autodocs/API-REFERENCE.md

Load a language file and switch to it on this instance.

```APIDOC
## loadLanguageAsync(lang: string, dashLangTry?: boolean, ignoreAbort?: boolean): Promise<string | void>

### Parameters
- **lang** (string) - Required - Language code to load.
- **dashLangTry** (boolean) - Optional - Internal fallback flag.
- **ignoreAbort** (boolean) - Optional - Ignore pending abort requests.
```

--------------------------------

### Asterisk Start Range Pluralization

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/_autodocs/pluralization.md

Matches counts from 0 up to a specific number.

```text
"[*,10] Low|[11,*] High"
```

```typescript
transChoice(msg, 0)   // "Low"
transChoice(msg, 5)   // "Low"
transChoice(msg, 10)  // "Low"
transChoice(msg, 11)  // "High"
```

--------------------------------

### Full Plugin Configuration

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/_autodocs/vue-integration.md

Configures the plugin with initial language, fallback settings, and an onLoad callback.

```typescript
import { createApp } from 'vue'
import { i18nVue } from 'laravel-vue-i18n'
import App from './App.vue'

const app = createApp(App)

app.use(i18nVue, {
  lang: 'pt',                              // Initial language
  fallbackLang: 'en',                      // Fallback if not found
  fallbackMissingTranslations: true,       // Fall back for missing keys
  resolve: lang => import(`./lang/${lang}.json`),
  onLoad: (lang) => {
    console.log(`Language ${lang} loaded`)
  }
})

app.mount('#app')
```

--------------------------------

### Configure with Vite

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/README.md

Initialize the plugin in your Vue application using Vite's import.meta.glob for dynamic translation file resolution.

```js
import { createApp } from 'vue'
import { i18nVue } from 'laravel-vue-i18n'

createApp()
    .use(i18nVue, {
        resolve: async lang => {
            const langs = import.meta.glob('../../lang/*.json');
            return await langs[`../../lang/${lang}.json`]();
        }
    })
    .mount('#app');
```

```js
.use(i18nVue, {
    lang: 'pt',
    resolve: lang => {
        const langs = import.meta.glob('../../lang/*.json', { eager: true });
        return langs[`../../lang/${lang}.json`].default;
    },
})
```

--------------------------------

### getCurrentLanguage(): ComputedRef<string>

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/_autodocs/API-REFERENCE.md

Get a reactive computed reference to the currently active language on this instance.

```APIDOC
## getCurrentLanguage(): ComputedRef<string>

### Description
Returns a reactive reference to the current language code.
```

--------------------------------

### Using $t in Templates

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/_autodocs/vue-integration.md

Demonstrates translation usage with simple keys, replacements, and case transformations in Vue templates.

```vue
<template>
  <!-- Simple translation -->
  <h1>{{ $t('Welcome!') }}</h1>

  <!-- With replacements -->
  <p>{{ $t('Hello, :name!', { name: 'John' }) }}</p>

  <!-- Case transformations -->
  <p>{{ $t('User :USERNAME joined', { username: 'alice' }) }}</p>
</template>
```

--------------------------------

### i18nVue: Plugin

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/_autodocs/API-REFERENCE.md

The Vue plugin to install on your application. Registers $t and $tChoice global properties for translation.

```APIDOC
## i18nVue: Plugin

### Description
The Vue plugin to install on your application. Registers `$t` and `$tChoice` global properties for translation.

### Installation
```typescript
import { createApp } from 'vue'
import { i18nVue } from 'laravel-vue-i18n'

createApp()
  .use(i18nVue, {
    lang: 'pt',
    resolve: lang => import(`../../lang/${lang}.json`)
  })
  .mount('#app')
```

### Global Properties
- **$t** - Alias for `trans()`
- **$tChoice** - Alias for `transChoice()`
```

--------------------------------

### prepareExtendedParsedLangFiles(langPaths: string[]): ParsedLangFileInterface[]

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/_autodocs/loader.md

Parses multiple directories and returns combined results.

```APIDOC
## prepareExtendedParsedLangFiles(langPaths: string[]): ParsedLangFileInterface[]

### Description
Parses multiple directories and returns combined results.

### Parameters
- **langPaths** (string[]) - Required - Array of directory paths to parse

### Returns
- **ParsedLangFileInterface[]** - Combined results from all paths
```

--------------------------------

### Configure Multiple Apps on One Page

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/_autodocs/configuration.md

Initialize multiple Vue apps with independent language settings by setting shared to false.

```typescript
// App 1 - Portuguese
createApp()
  .use(i18nVue, {
    lang: 'pt',
    shared: false,
    resolve: ...
  })
  .mount('#app-1')

// App 2 - Spanish
createApp()
  .use(i18nVue, {
    lang: 'es',
    shared: false,
    resolve: ...
  })
  .mount('#app-2')

// Note: Only one app's language will be reflected in the HTML lang attribute
```

--------------------------------

### Configure Vite with PHP files

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/_autodocs/INDEX.md

Configures the i18n plugin with custom language paths for PHP file support.

```typescript
// vite.config.js
import i18n from 'laravel-vue-i18n/vite'

export default {
  plugins: [
    vue(),
    i18n({
      langPath: 'lang',
      additionalLangPaths: ['vendor/package/lang']
    })
  ]
}

// main.js
.use(i18nVue, {
  resolve: lang => import(`./lang/${lang}.json`)
})
```

--------------------------------

### Configure SSR Language Loading

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/_autodocs/INDEX.md

Use eager loading with import.meta.glob for server-side rendering environments.

```typescript
resolve: lang => {
  const langs = import.meta.glob('../../lang/*.json', { eager: true })
  return langs[`../../lang/${lang}.json`].default
}
```

--------------------------------

### Use translation functions in TypeScript components

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/_autodocs/vue-integration.md

Import trans and transChoice functions to handle translations within a defineComponent setup.

```typescript
import { defineComponent } from 'vue'
import { trans, transChoice } from 'laravel-vue-i18n'

interface Props {
  itemCount: number
}

export default defineComponent<Props>({
  props: {
    itemCount: {
      type: Number,
      required: true
    }
  },
  setup(props) {
    return {
      welcome: trans('Welcome!'),
      items: transChoice('One item|Many items', props.itemCount)
    }
  }
})
```

--------------------------------

### load(): void

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/_autodocs/API-REFERENCE.md

Reload the current language from the resolver function.

```APIDOC
## load(): void
```

--------------------------------

### Time Expression Pluralization

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/_autodocs/examples.md

Use wTransChoice within a Vue composition API setup to handle complex time-based pluralization.

```json
{
  "{1} :count second ago|[2,60] :count seconds ago|[61,3600] :count minute ago|[3601,*] :count hour ago": "{1} :count second ago|[2,60] :count seconds ago|[61,3600] :count minute ago|[3601,*] :count hour ago"
}
```

```vue
<template>
  <div>
    <p>Last updated: {{ timeAgo }}</p>
  </div>
</template>

<script>
import { wTransChoice } from 'laravel-vue-i18n'
import { computed, ref } from 'vue'

export default {
  setup() {
    const secondsAgo = ref(120)
    const msg = '{1} :count second ago|[2,60] :count seconds ago|[61,3600] :count minute ago|[3601,*] :count hour ago'

    const timeAgo = computed(() => {
      return wTransChoice(msg, secondsAgo.value).value
    })

    return { timeAgo }
  }
}
</script>
```

--------------------------------

### Configure SSR with Vite

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/_autodocs/examples.md

Uses eager loading for language files to support Server-Side Rendering environments.

```typescript
// main.js (SSR-specific)
import { createApp } from 'vue'
import { i18nVue } from 'laravel-vue-i18n'
import App from './App.vue'

export function createAppInstance(initialLang = 'en') {
  return createApp(App)
    .use(i18nVue, {
      lang: initialLang,
      resolve: (lang) => {
        // Use eager: true for SSR
        const langs = import.meta.glob('../../lang/*.json', { eager: true })
        return langs[`../../lang/${lang}.json`].default
      }
    })
}
```

--------------------------------

### Configure Vite with PHP language files

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/_autodocs/examples.md

Configures the Vite plugin to watch specific language paths and resolves files via dynamic imports.

```typescript
// vite.config.js
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import i18n from 'laravel-vue-i18n/vite'

export default defineConfig({
  plugins: [
    vue(),
    i18n({
      langPath: 'lang',
      additionalLangPaths: ['vendor/laravel-admin/lang']
    })
  ]
})

// main.js
import { createApp } from 'vue'
import { i18nVue } from 'laravel-vue-i18n'
import App from './App.vue'

createApp(App)
  .use(i18nVue, {
    lang: 'en',
    resolve: (lang) => import(`./lang/${lang}.json`)
  })
  .mount('#app')
```

--------------------------------

### Project Dependency Graph

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/_autodocs/module-graph.md

Visual representation of the internal module structure and external dependencies.

```text
index.ts (MAIN)
├── interfaces/options.ts
├── interfaces/plugin-options.ts
├── interfaces/language.ts
├── interfaces/language-json-file.ts
├── interfaces/replacements.ts
├── pluralization.ts
│   └── utils/get-plural-index.ts
├── utils/avoid-exceptions.ts
└── utils/has-php-translations.ts

vite.ts (VITE PLUGIN)
├── interfaces/parsed-lang-file.ts
├── interfaces/plugin-options.ts
├── loader.ts
│   └── interfaces/parsed-lang-file.ts
└── utils/has-php-translations.ts

mix.ts (MIX PLUGIN)
├── loader.ts
│   └── interfaces/parsed-lang-file.ts
└── utils/has-php-translations.ts

loader.ts (UTILITIES)
├── interfaces/parsed-lang-file.ts
└── php-parser (external dependency)
```

--------------------------------

### Defining the i18nVue Plugin

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/_autodocs/types.md

Type definition for the Vue 3 plugin export. Implement the install method to register the plugin with the application instance.

```typescript
import { Plugin } from 'vue'

const i18nVue: Plugin = {
  install(app, options) { ... }
}
```

--------------------------------

### Translate Messages Reactively with wTrans()

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/README.md

Use wTrans() within Vue setup functions to return reactive translation objects that update automatically when language settings change.

```jsx
// lang/pt.json
{
    "Welcome!": "Bem-vindo!",
    "Welcome, :name!": "Bem-vindo, :name!"
}

import { wTrans } from 'laravel-vue-i18n';

setup() {
    return {
        welcomeLabel: wTrans('Welcome!'),
        welcomeFrancisco: wTrans('Welcome, :name!', { name: 'Francisco' })
    }
}

<template>
    <div>{{ welcomeLabel }}</div> // <div>Bem-vindo!</div>
    <div>{{ welcomeFrancisco }}</div> // <div>Bem-vindo, Francisco!</div>
</template>
```

--------------------------------

### Perform Parameter Replacement

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/_autodocs/INDEX.md

Demonstrates how to use different casing patterns for parameter replacement in translation strings.

```typescript
trans('Hello :name', { name: 'John' })      // Hello John (lowercase)
trans('Hello :NAME', { name: 'john' })      // Hello JOHN (uppercase)
trans('Hello :Name', { name: 'john' })      // Hello John (capitalized)
```

--------------------------------

### Configure with Webpack / Laravel Mix

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/README.md

Initialize the plugin in your Vue application using Webpack's dynamic import or require for translation file resolution.

```js
import { createApp } from 'vue'
import { i18nVue } from 'laravel-vue-i18n'

createApp()
    .use(i18nVue, {
        resolve: lang => import(`../../lang/${lang}.json`),
    })
    .mount('#app');
```

```js
.use(i18nVue, {
    lang: 'pt',
    resolve: lang => require(`../../lang/${lang}.json`),
})
```

--------------------------------

### Instantiate I18n Class

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/_autodocs/API-REFERENCE.md

Create a new I18n instance with specific language configuration and translation resolution logic.

```typescript
new I18n(options?: OptionsInterface)
```

```typescript
import { I18n } from 'laravel-vue-i18n'

const i18nEn = new I18n({
  lang: 'en',
  fallbackLang: 'en',
  resolve: lang => import(`./lang/${lang}.json`)
})

const i18nPt = new I18n({
  lang: 'pt',
  resolve: lang => import(`./lang/${lang}.json`)
})

console.log(i18nEn.trans('Welcome!')) // "Welcome!"
console.log(i18nPt.trans('Welcome!')) // "Bem-vindo!"
```

--------------------------------

### Implement language switching with persistence

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/_autodocs/examples.md

Uses Vue 3 Composition API to load saved language preferences or detect browser language on mount.

```vue
<script setup>
import { ref, onMounted } from 'vue'
import { loadLanguageAsync, getActiveLanguage } from 'laravel-vue-i18n'

const currentLanguage = ref(getActiveLanguage())

const changeLanguage = async (lang) => {
  await loadLanguageAsync(lang)
  currentLanguage.value = lang
  localStorage.setItem('language', lang)
}

const detectBrowserLanguage = () => {
  const browserLang = navigator.language.replace('-', '_')
  return ['en', 'pt', 'es', 'fr'].includes(browserLang) ? browserLang : 'en'
}

onMounted(async () => {
  const savedLang = localStorage.getItem('language')
  const langToLoad = savedLang || detectBrowserLanguage()
  await loadLanguageAsync(langToLoad)
  currentLanguage.value = langToLoad
})
</script>

<template>
  <select :value="currentLanguage" @change="changeLanguage($event.target.value)">
    <option value="en">English</option>
    <option value="pt">Português</option>
    <option value="es">Español</option>
  </select>
</template>
```

--------------------------------

### Define plugin options

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/_autodocs/INDEX.md

Configure the plugin behavior using the OptionsInterface, including fallback languages and custom load callbacks.

```typescript
interface OptionsInterface {
  lang?: string                    // Current language
  fallbackLang?: string           // Default: 'en'
  fallbackMissingTranslations?: boolean  // Default: false
  resolve?(lang: string): Promise // Resolver function (required)
  onLoad?: (lang: string) => void // Load callback
}
```

--------------------------------

### Configure Vite with JSON language files

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/_autodocs/examples.md

Uses Vite plugin and dynamic glob imports to resolve JSON language files.

```typescript
// vite.config.js
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import i18n from 'laravel-vue-i18n/vite'

export default defineConfig({
  plugins: [
    vue(),
    i18n()
  ]
})

// main.js
import { createApp } from 'vue'
import { i18nVue } from 'laravel-vue-i18n'
import App from './App.vue'

createApp(App)
  .use(i18nVue, {
    resolve: async (lang) => {
      const langs = import.meta.glob('../../lang/*.json')
      return await langs[`../../lang/${lang}.json`]()
    }
  })
  .mount('#app')
```

--------------------------------

### loadLanguageAsync(lang: string, dashLangTry?: boolean): Promise<string | void>

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/_autodocs/API-REFERENCE.md

Loads a language file and switches the active language to it. Returns a promise that resolves when the language is loaded.

```APIDOC
## loadLanguageAsync(lang: string, dashLangTry?: boolean)

### Description
Loads a language file and switches the active language to it. Returns a promise that resolves when the language is loaded.

### Parameters
- **lang** (string) - Required - Language code to load (e.g., 'pt', 'en_US')
- **dashLangTry** (boolean) - Optional - Internal flag for fallback attempt with dash/underscore conversion

### Returns
- **Promise<string | void>** - Resolves with the language code on success
```

--------------------------------

### Configure Mix with PHP files

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/_autodocs/INDEX.md

Integrates the i18n plugin into the Laravel Mix build pipeline.

```javascript
// webpack.mix.js
require('laravel-vue-i18n/mix')
mix.i18n()

// main.js
.use(i18nVue, {
  resolve: lang => import(`../../lang/${lang}.json`)
})
```

--------------------------------

### Organize Translations with Dot Notation

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/_autodocs/vue-integration.md

Structure translation files using dot notation for better key management and retrieval.

```json
{
  "auth.login": "Login",
  "auth.logout": "Logout",
  "auth.register": "Register",
  "messages.welcome": "Welcome",
  "messages.goodbye": "Goodbye"
}
```

```typescript
trans('auth.login')      // "Login"
trans('messages.welcome') // "Welcome"
```

--------------------------------

### Implement a simple language dropdown

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/_autodocs/examples.md

Uses a select element to trigger language changes and save preferences to localStorage.

```vue
<template>
  <div class="language-switcher">
    <select v-model="currentLanguage" @change="changeLanguage">
      <option value="en">English</option>
      <option value="pt">Português</option>
      <option value="es">Español</option>
      <option value="fr">Français</option>
    </select>
  </div>
</template>

<script>
import { loadLanguageAsync, getActiveLanguage } from 'laravel-vue-i18n'

export default {
  data() {
    return {
      currentLanguage: getActiveLanguage()
    }
  },
  methods: {
    async changeLanguage() {
      await loadLanguageAsync(this.currentLanguage)
      this.saveLanguagePreference()
    },
    saveLanguagePreference() {
      localStorage.setItem('preferredLanguage', this.currentLanguage)
    }
  }
}
</script>

<style scoped>
.language-switcher {
  margin: 1rem 0;
}

select {
  padding: 0.5rem;
  border-radius: 4px;
  border: 1px solid #ccc;
}
</style>
```

--------------------------------

### Project Directory Structure

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/_autodocs/module-graph.md

Visual representation of the source code organization and module hierarchy.

```text
laravel-vue-i18n/
├── src/
│   ├── index.ts                 # Main entry point (8 exports)
│   ├── vite.ts                  # Vite plugin
│   ├── mix.ts                   # Laravel Mix plugin
│   ├── loader.ts                # PHP file parsing & JSON generation
│   ├── pluralization.ts         # Pluralization logic
│   ├── interfaces/
│   │   ├── options.ts           # OptionsInterface
│   │   ├── plugin-options.ts    # PluginOptionsInterface, VitePluginOptionsInterface
│   │   ├── language.ts          # LanguageInterface
│   │   ├── language-json-file.ts # LanguageJsonFileInterface
│   │   ├── replacements.ts      # ReplacementsInterface
│   │   └── parsed-lang-file.ts  # ParsedLangFileInterface
│   └── utils/
│       ├── avoid-exceptions.ts  # Error handling utilities
│       ├── get-plural-index.ts  # Language plural rules (200+ locales)
│       └── has-php-translations.ts # PHP translation detection
├── test/
├── dist/                        # Compiled output (CJS, ESM)
├── package.json
└── tsconfig.json
```

--------------------------------

### Configure the i18n Plugin

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/README.md

Initialize the plugin within the Vue application instance, providing a resolve function to locate language files.

```js
createApp().use(i18nVue, {
    lang: 'pt',
    resolve: lang => import(`../../lang/${lang}.json`),
})
```

--------------------------------

### reset(): void

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/_autodocs/API-REFERENCE.md

Clears all loaded language data and resets the plugin to its initial state.

```APIDOC
## reset()

### Description
Clears all loaded language data and resets the plugin to its initial state. Does not create a shared instance if one doesn't exist.
```

--------------------------------

### Using $tChoice in Templates

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/_autodocs/vue-integration.md

Demonstrates pluralized translation usage with simple strings, replacements, and dynamic variables in Vue templates.

```vue
<template>
  <!-- Simple plural -->
  <p>{{ $tChoice('One apple|Many apples', 5) }}</p>

  <!-- With replacement -->
  <p>{{ $tChoice('{1} :count minute ago|[2,*] :count minutes ago', 10) }}</p>

  <!-- With additional replacements -->
  <p>{{ $tChoice('{1} :count item for :user|[2,*] :count items for :user', count, { user: name }) }}</p>
</template>
```

--------------------------------

### Create multiple I18n instances

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/README.md

Instantiate multiple I18n objects with different languages while sharing loaded translation files.

```js
import { I18n } from 'laravel-vue-i18n'

const resolver = lang => import(`./fixtures/lang/${lang}.json`)

const i18nEn = new I18n({
    lang: 'en',
    resolve: resolver
})
const i18nPt = new I18n({
    lang: 'pt',
    resolve: resolver
})

i18nEn.trans('Welcome!') // will output "Welcome!"
i18nPt.trans('Welcome!') // will output "Bem-vindo!"
```

--------------------------------

### Merge vendor translations

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/_autodocs/loader.md

Demonstrates how vendor package translations are merged into the main translation object using namespace syntax.

```text
vendor/package/lang/
└── en/
    └── messages.php → { 'package.hello': 'Hello' }

Gets merged as: { 'package::hello': 'Hello' }
```

--------------------------------

### setOptions(options?: OptionsInterface, forceLoad?: boolean): I18n

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/_autodocs/API-REFERENCE.md

Update the options on this instance and optionally force a reload.

```APIDOC
## setOptions(options?: OptionsInterface, forceLoad?: boolean): I18n

### Parameters
- **options** (OptionsInterface) - Optional - New options to merge.
- **forceLoad** (boolean) - Optional - Force language reload.
```

--------------------------------

### Implement safe language switching

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/_autodocs/vue-integration.md

Wrap language loading in try-catch blocks to handle potential network or file resolution errors.

```typescript
async changeLanguage(lang) {
  try {
    await loadLanguageAsync(lang)
    this.currentLanguage = lang
  } catch (error) {
    console.error(`Failed to load language: ${lang}`)
    // Show error to user or use fallback
  }
}
```

--------------------------------

### Implement a flag-based language switcher

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/_autodocs/examples.md

Displays language options as clickable buttons with flag emojis and visual active states.

```vue
<template>
  <div class="language-flags">
    <button
      v-for="lang in languages"
      :key="lang.code"
      :class="{ active: currentLanguage === lang.code }"
      @click="changeLanguage(lang.code)"
      :title="lang.name"
    >
      <span>{{ lang.flag }}</span>
    </button>
  </div>
</template>

<script>
import { loadLanguageAsync, getActiveLanguage } from 'laravel-vue-i18n'

export default {
  data() {
    return {
      currentLanguage: getActiveLanguage(),
      languages: [
        { code: 'en', name: 'English', flag: '🇬🇧' },
        { code: 'pt', name: 'Português', flag: '🇵🇹' },
        { code: 'es', name: 'Español', flag: '🇪🇸' },
        { code: 'fr', name: 'Français', flag: '🇫🇷' }
      ]
    }
  },
  methods: {
    async changeLanguage(lang) {
      await loadLanguageAsync(lang)
      this.currentLanguage = lang
    }
  }
}
</script>

<style scoped>
.language-flags {
  display: flex;
  gap: 0.5rem;
}

button {
  background: none;
  border: 2px solid transparent;
  font-size: 1.5rem;
  cursor: pointer;
  padding: 0.5rem;
  border-radius: 4px;
  transition: all 0.3s ease;
}

button:hover {
  background-color: rgba(0, 0, 0, 0.05);
}

button.active {
  border-color: #007bff;
  background-color: rgba(0, 123, 255, 0.1);
}
</style>
```

--------------------------------

### Configure Vite Plugin

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/_autodocs/API-REFERENCE.md

Integrate the i18n plugin into the Vite configuration file to process translation files during build.

```typescript
// vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import i18n from 'laravel-vue-i18n/vite'

export default defineConfig({
  plugins: [
    vue(),
    
    // Simple usage with default path
    i18n(),
    
    // Custom path
    i18n('resources/lang'),
    
    // With additional paths and options
    i18n({
      langPath: 'lang',
      additionalLangPaths: ['public/locales', 'vendor/package/lang']
    })
  ]
})
```

--------------------------------

### Enable Debugging in Development

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/_autodocs/vue-integration.md

Log language loading events specifically during development environments.

```typescript
.use(i18nVue, {
  resolve: lang => import(`./lang/${lang}.json`),
  onLoad: (lang) => {
    if (import.meta.env.DEV) {
      console.log(`[i18n] Loaded language: ${lang}`)
      console.log(`[i18n] Loaded keys:`, Object.keys(I18n.loaded.find(l => l.lang === lang).messages))
    }
  }
})
```

--------------------------------

### Enable Fallback for Missing Keys

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/_autodocs/configuration.md

Configure the plugin to automatically use the fallback language when a translation key is missing in the primary language file.

```javascript
createApp()
  .use(i18nVue, {
    lang: 'pt',
    fallbackLang: 'en',
    fallbackMissingTranslations: true, // Show English if Portuguese key is missing
    resolve: lang => import(`./lang/${lang}.json`)
  })
  .mount('#app')
```

--------------------------------

### Implement Pluralization

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/_autodocs/INDEX.md

Shows basic and range-based pluralization syntax for translation keys.

```typescript
// Simple: singular | plural
transChoice('One apple|Many apples', 1)

// With conditions: {n} = exact, [n,m] = range
transChoice('{0} None|{1} One|[2,*] Many', 5)
```

--------------------------------

### Vite Plugin Integration

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/_autodocs/loader.md

Configuration and lifecycle overview for the Vite plugin, including file preparation, hot update handling, and cleanup.

```typescript
import i18n from 'laravel-vue-i18n/vite'

// During buildStart:
// 1. Calls prepareExtendedParsedLangFiles([frameworkLangPath, langPath, ...additionalPaths])
// 2. Calls generateFiles(langPath, parsed)
// 3. Creates php_en.json, php_pt.json, etc.

// During handleHotUpdate (watching .php files):
// 1. Regenerates files on any .php change

// During buildEnd:
// 1. Calls reset() to clean up generated files
```

--------------------------------

### Configure Vite plugin options

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/_autodocs/configuration.md

Define the language directory and additional paths for translation file processing within the Vite configuration.

```typescript
import i18n from 'laravel-vue-i18n/vite'

export default defineConfig({
  plugins: [
    // Default configuration
    i18n(),
    
    // Custom language path
    i18n('resources/lang'),
    
    // With additional paths
    i18n({
      langPath: 'lang',
      additionalLangPaths: ['public/locales', 'vendor/my-package/lang']
    })
  ]
})
```

--------------------------------

### Configure shared instance usage

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/README.md

Default behavior where multiple Vue app instances share the same I18n configuration and active language.

```js
import { i18nVue } from 'laravel-vue-i18n'

const appA = createApp()
    .use(i18nVue, { lang: 'pt' })
    .mount('#app-1');

const appB = createApp()
    .use(i18nVue)
    .mount('#app-2');

// elsewhere
import { trans } from 'laravel-vue-i18n'

trans('Welcome!') // will output "Bem-vindo!"
```

--------------------------------

### trans(key: string, replacements?: ReplacementsInterface): string

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/_autodocs/API-REFERENCE.md

Translate a message key on this specific instance.

```APIDOC
## trans(key: string, replacements?: ReplacementsInterface): string

### Description
Translate a message key on this specific instance.

### Parameters
- **key** (string) - Required - The translation key to look up.
- **replacements** (ReplacementsInterface) - Optional - Key-value pairs for string interpolation.
```

--------------------------------

### Configure Fallback Language

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/_autodocs/INDEX.md

Set up fallback language and missing translation behavior within the i18nVue plugin configuration.

```typescript
.use(i18nVue, {
  lang: 'pt',
  fallbackLang: 'en',
  fallbackMissingTranslations: true
})
```

--------------------------------

### loadLanguageAsync(lang)

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/_autodocs/INDEX.md

Asynchronously loads a new language file.

```APIDOC
## loadLanguageAsync(lang)

### Description
Asynchronously switches the application language by loading the corresponding translation file.

### Parameters
- **lang** (string) - Required - The language code to load.
```

--------------------------------

### Dynamic Language Selection from API

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/_autodocs/examples.md

Manages user language preferences by syncing with a backend API and falling back to the current active instance language.

```typescript
// Store language preferences in backend
import { I18n } from 'laravel-vue-i18n'
import { loadLanguageAsync } from 'laravel-vue-i18n'

class LanguageManager {
  constructor() {
    this.supportedLanguages = ['en', 'pt', 'es', 'fr']
  }

  async loadUserPreference() {
    try {
      const response = await fetch('/api/user/preferences')
      const data = await response.json()
      const lang = data.language

      if (this.supportedLanguages.includes(lang)) {
        await loadLanguageAsync(lang)
        return lang
      }
    } catch (error) {
      console.error('Failed to load user language preference', error)
    }
    return I18n.getSharedInstance().getActiveLanguage()
  }

  async saveUserPreference(lang) {
    await fetch('/api/user/preferences', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ language: lang })
    })
    await loadLanguageAsync(lang)
  }
}

export default new LanguageManager()
```

--------------------------------

### Use Replacements in trans()

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/_autodocs/types.md

Demonstrates simple, multiple, case-transformed, and numeric replacements using the trans function.

```typescript
import { trans } from 'laravel-vue-i18n'

// Simple replacement
trans('Hello :name!', { name: 'John' })
// "Hello John!"

// Multiple replacements
trans('Hello :name, you are :age years old', {
  name: 'John',
  age: '25'
})
// "Hello John, you are 25 years old"

// Case transformations
trans('The user :USERNAME joined', { username: 'john' })
// "The user JOHN joined"

trans('Welcome :Name!', { name: 'alice' })
// "Welcome Alice!"

// Numeric replacements (converted to strings)
trans('You have :count notifications', { count: 5 })
// "You have 5 notifications"
```

--------------------------------

### isLoaded(lang?: string)

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/README.md

Checks if a specific language or the current language is loaded.

```APIDOC
## isLoaded(lang?: string)

### Description
Checks if the specified language is loaded. If no parameter is provided, it checks the currently active language.
```

--------------------------------

### Lazy load language files

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/_autodocs/vue-integration.md

Load language files asynchronously before mounting components to improve initial load times.

```typescript
import { defineAsyncComponent } from 'vue'
import { loadLanguageAsync } from 'laravel-vue-i18n'

const HeavyComponent = defineAsyncComponent(async () => {
  // Load language before loading component
  await loadLanguageAsync('pt')
  return import('./HeavyComponent.vue')
})
```

--------------------------------

### Basic Pluralization String

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/_autodocs/pluralization.md

A simple string format for pluralization without explicit conditions.

```text
"One item|Many items"
```

--------------------------------

### reset(folderPath: string): void

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/_autodocs/loader.md

Cleans up generated PHP JSON files.

```APIDOC
## reset(folderPath: string): void

### Description
Cleans up generated PHP JSON files.

### Parameters
- **folderPath** (string) - Required - Directory containing generated files

### Returns
- **void**
```

--------------------------------

### Load Languages Asynchronously

Source: https://github.com/xico2k/laravel-vue-i18n/blob/main/_autodocs/vue-integration.md

Pre-load alternative languages to reduce latency when switching locales.

```typescript
import { loadLanguageAsync } from 'laravel-vue-i18n'

// Pre-load alternate languages
loadLanguageAsync('en')
loadLanguageAsync('es')
```
Tokens:
Raw