README

A Laravel package that automatically discovers and manages translation strings in your application. Scan your codebase for translation function calls, generate language files, and optionally sync with lynguist.com for collaborative translation management.

Works in tandem with NPM's package @vixen-tech/lynguist.

Features

Automatic Translation Discovery - Scans PHP, Blade, JavaScript, Vue, and TypeScript files for translation function calls
Multi-Language Support - Generates and manages JSON language files for multiple languages
Smart Merging - Preserves existing translations when scanning for new strings
TypeScript Integration - Auto-generates TypeScript declaration files for type-safe frontend translations
Cloud Sync - Upload and sync translations with lynguist.com
Customizable - Configure which directories to scan, file extensions to include, and translation functions to detect

Requirements

PHP 8.3+
Laravel 12.x

Installation

Install the package via Composer:

composer require vixen/laravel-lynguist

The package auto-registers via Laravel's service provider discovery.

Publish the configuration file:

php artisan vendor:publish --provider="Vixen\Lynguist\LynguistServiceProvider"

Configuration

After publishing, configure the package in config/lynguist.php:

return [
    // Default/reference language
    'default_language' => 'en',

    // Languages to generate files for
    'languages' => ['en'],

    // Translation functions to search for
    'search_for' => ['__', 'lang', 'trans', 'trans_choice', 'transChoice', 'choice'],

    // Output directory for language JSON files
    'output_path' => lang_path(),

    // TypeScript declarations file path (set to false to disable)
    'types_path' => resource_path('js/types/translations.d.ts'),

    // Directories to scan for translations
    'scannable_paths' => [
        app_path(),
        resource_path('views'),
        resource_path('js'),
    ],

    // File extensions to scan (null for all files)
    'allowed_extensions' => ['php', 'js', 'jsx', 'ts', 'tsx', 'vue'],

    // Lynguist.com integration
    'connect' => [
        'api_token' => env('LYNGUIST_API_TOKEN'),
        'timeout' => env('LYNGUIST_TIMEOUT', 120),
    ],
];

You can include in the config file only altered options, since they are merged with defaults.

Usage

Scanning for Translations

Run the scan command to discover all translation strings in your codebase:

php artisan lynguist:scan

This will:

Scan configured directories for translation function calls
Create/update JSON language files in your lang/ directory
Generate TypeScript declarations (if configured)

To also upload translations to lynguist.com (this requires an API key):

php artisan lynguist:scan --upload

Supported Translation Functions

The package detects the following translation functions by default:

PHP/Blade:

__('welcome-message')
trans('greeting')
trans_choice('items', $count)
lang('settings.timezone')

Blade Directives:

@lang('page-title')
@choice('notifications', $count)

JavaScript/Vue:

__('frontend-string')
trans('greeting', { name: 'Jane' })
transChoice('pluralized-key', count)

Language File Output

The scan creates JSON files for each configured language (e.g., lang/en.json):

{
    "greeting": null,
    "items": null,
    "welcome-message": null
}

Keys with null values are untranslated. Add your translations:

{
    "welcome-message": "Welcome to our application!",
    "greeting": "Hello",
    "items": "{0} No items|{1} One item|[2,*] :count items"
}

Existing translations are preserved when re-scanning and then sorted alphabetically.

Programmatic Usage

You can also use the package programmatically via the facade:

use Vixen\Lynguist\Facades\Lynguist;

// Scan directories for translation terms
$terms = Lynguist::scan([
    app_path(),
    resource_path('views'),
]);

// Store terms to language files
Lynguist::store($terms);

// Get translations for a language
$translations = Lynguist::translations('en');

// Merge new terms with existing translations
$merged = Lynguist::merge($terms, 'en');

// Generate TypeScript declarations
Lynguist::generateTypeScriptFile($terms);

TypeScript Integration

When types_path is configured, the package generates TypeScript declarations for type-safe frontend translations:

// resources/js/types/translations.d.ts (configurable)
interface LynguistTranslations {
    'greeting': string
    'items': string
    'welcome-message': string
}

This enables autocomplete and type checking for translation keys in your frontend code.

Cloud Sync with Lynguist.com

To sync translations with lynguist.com:

Add your credentials to .env:

LYNGUIST_API_TOKEN=your_api_token
LYNGUIST_TIMEOUT=120

Upload existing translations:
```
php artisan lynguist:upload
```
Or include the --upload flag when scanning:
```
php artisan lynguist:scan --upload
```
Download translations from Lynguist.com:
```
php artisan lynguist:download
```

Create your callback endpoint:

use Illuminate\Http\Request;
use Vixen\Lynguist\Lynguist;

class SyncController extends Controller
{
    public function sync(Request $request, Lynguist $lynguist)
    {
        $lynguist->sync($request->input('translations')); 

        return response([
            'message' => 'Updated!',
        ]);
    }
}

Custom Translation Functions

To detect custom translation functions, add them to the search_for config:

'search_for' => [
    '__',
    'trans',
    'myCustomHelper',
    'Label', // Supports class/attribute names too
],

License

This package is open-sourced software licensed under the MIT license.

vixen / laravel-lynguist

Maintainers

Package info

Statistics

Security