jayesh/laravel-gemini-translator

An interactive command to extract and generate Laravel translations using Gemini AI.

Maintainers

Details

github.com/jayeshmepani/laravel-gemini-translator

Source

Issues

Installs: 9

Dependents: 0

Suggesters: 0

Security: 0

Stars: 1

Watchers: 0

Forks: 0

Open Issues: 0

Type:laravel-package

2.0.1 2025-06-14 14:40 UTC

Requires

MIT 1b52e38f65852af0a5d6c708b2ca8319795c20a0

  • Jayesh Patel <jayeshmepani777.woop@gmail.com>

This package is auto-updated.

Last update: 2025-06-14 15:56:37 UTC

README

An interactive Artisan command (translations:extract-and-generate) to scan your Laravel project for translation keys, translate them using Google's Gemini AI, and generate the necessary language files.

This tool is designed to dramatically speed up the localization process for both PHP (/lang/en/messages.php) and JSON (/lang/en.json) translation files.

Latest Version on Packagist Total Downloads License

Features

  • Interactive Prompts: Interactively select which translation files (messages.php, validation.php, etc.) and JSON key prefixes to process.
  • Powerful Key Extraction: Scans Blade, PHP, Vue, JS, and TypeScript files for translation keys using precise regular expressions.
  • Intelligent Exclusions: Automatically ignores route() and config() helpers to prevent false positives.
  • AI-Powered Translation: Uses the Gemini AI API to provide high-quality translations for multiple languages at once.
  • Concurrency Support: Uses spatie/fork for parallel processing, making API calls significantly faster.
  • Graceful Stop: Stop the translation process at any time by pressing a key (defaults to 'q').
  • Detailed Logging: Creates a translation_extraction_log.json file detailing every key and where it was found, plus a failed_translation_keys.json for any errors.

Requirements

  • PHP 8.1 or higher
  • Laravel 10.0 or higher
  • Google Gemini API key
  • pcntl PHP extension is required for the high-performance fork driver.

Installation

You can install the package via Composer:

composer require jayesh/laravel-gemini-translator

After installation, you need to publish the configuration file:

php artisan gemini:install

Configuration

Next, add your Google Gemini API key and a request timeout to your .env file. You can get an API key from Google AI Studio.

GEMINI_API_KEY=YOUR_GEMINI_API_KEY
GEMINI_REQUEST_TIMEOUT=600

Gemini API Model & Limits

This package uses the Gemini 2.0 Flash-Lite model, which provides excellent translation quality with the following free tier limitations:

  • Rate Limit: 30 requests per minute (RPM)
  • Daily Limit: 1,500 requests per day

Important Considerations:

  • Large projects may exceed these limits. Consider using the --chunk-size option to control the number of keys sent per request.
  • The --driver=fork option processes multiple requests concurrently, which can help you reach rate limits faster but complete translations more efficiently.
  • If you hit rate limits, the command will automatically retry with exponential backoff (configurable with --max-retries and --retry-delay options).

Usage

Once installed and configured, you can run the main command from your terminal:

php artisan translations:extract-and-generate --driver=fork

To get detailed information about all available options and their descriptions, use:

php artisan help translations:extract-and-generate

The command will guide you through the following steps:

  1. Scanning: It will scan your project for all translation keys.
  2. File Selection: It will ask you which translation files (e.g., messages.php, auth.php, Root JSON file) you want to process.
  3. Translation: It will send the keys to the Gemini API and show a progress bar.
  4. File Generation: It will write the translated keys to the correct language files in your lang directory, overwriting existing files.

Command Options

You can customize the command's behavior with the following options:

Basic Options

  • --source=.: The root directory of the application to scan for keys (default: current directory).
  • --target-dir=lang: Root directory for final Laravel translation files (default: lang).
  • --langs=en,ru,uz: Comma-separated language codes to translate to (default: en,ru,uz).

Scanning Options

  • --exclude=vendor,node_modules,...: Comma-separated directories to exclude from scanning.
  • --extensions=php,blade.php,vue,js,jsx,ts,tsx: File extensions to search for translation keys.
  • --custom-patterns=path/to/patterns.txt: Path to a file with custom regex patterns.
  • --no-advanced: Disable advanced, context-based pattern detection.

Performance & Behavior Options

  • --chunk-size=100: Number of keys to send to Gemini in a single request (default: 100).
  • --driver=default: Concurrency driver. Options: fork (fastest, requires pcntl), sync (sequential, most stable), async (currently falls back to sync), default (currently falls back to sync).
  • --skip-existing: Skip keys that already have translations in all target languages.

Reliability Options

  • --max-retries=5: Maximum number of retries for failed API calls (default: 5).
  • --retry-delay=3: Base delay in seconds between retries with exponential backoff (default: 3).
  • --stop-key=q: The key to press to gracefully stop the translation process (default: q).

Output Control Options

  • -h, --help: Display help for the given command. When no command is given display help for the list command.
  • --silent: Do not output any message.
  • -q, --quiet: Only errors are displayed. All other output is suppressed.
  • -V, --version: Display this application version.
  • --ansi|--no-ansi: Force (or disable --no-ansi) ANSI output.
  • --no-interaction: Do not ask any interactive question.
  • --env[=ENV]: The environment the command should run under.
  • -v|vv|vvv, --verbose: Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug.

Example Usage

# Basic usage with custom languages
php artisan translations:extract-and-generate --langs=en,es,fr,de

# High-performance processing with fork driver and smaller chunks
php artisan translations:extract-and-generate --driver=fork --chunk-size=50

# Exclude additional directories and only scan Blade files
php artisan translations:extract-and-generate --exclude=vendor,tests,docs --extensions=blade.php

# Skip existing translations and use a different target directory
php artisan translations:extract-and-generate --skip-existing --target-dir=resources/lang

# Get help with all available options
php artisan help translations:extract-and-generate

For a full list of options, run:

php artisan help translations:extract-and-generate

Example Output

┌ Which translation files would you like to process? ───────────────────────────┐
│ ● messages.php                                                                │
│ ○ auth.php                                                                    │
│ ○ validation.php                                                              │
│ ● Root JSON file                                                              │
└───────────────────────────────────────────────────────────────────────────────┘

Press the 'q' key at any time to gracefully stop the process.
📊 Total keys to translate: 156
📦 Total chunks to process: 2
🚀 156/156 [============================] 100% -- ✅ Chunk 2/2 - SUCCESS (56 keys) ⏱️  18s

💾 Phase 3: Writing Language Files
 ✅ Wrote: lang/es.json (78 keys)
 ✅ Wrote: lang/es/messages.php (78 keys)
 ✅ Wrote: lang/fr.json (78 keys)
 ✅ Wrote: lang/fr/messages.php (78 keys)
...

File Structure

The command intelligently separates keys. Keys with a group prefix (e.g., messages.welcome) are placed in the corresponding PHP file (messages.php). Keys without a group (e.g., 'Welcome') are placed in the root JSON file for that language (es.json).

lang/
├── en/
│   ├── messages.php
│   ├── auth.php
│   └── validation.php
├── es/
│   ├── messages.php
│   ├── auth.php
│   └── validation.php
├── fr/
│   ├── messages.php
│   ├── auth.php
│   └── validation.php
├── en.json
├── es.json
└── fr.json

Supported File Types

The package scans the following file types for translation keys by default:

  • Blade templates (.blade.php)
  • PHP files (.php)
  • Vue components (.vue)
  • JavaScript (.js, .jsx)
  • TypeScript (.ts, .tsx)

Translation Key Patterns

The package uses sophisticated pattern matching to detect translation keys.

Standard Laravel Functions

  • __('key')
  • trans('key')
  • trans_choice('key', $count)
  • @lang('key')
  • @choice('key', $count)
  • Lang::get('key')
  • Lang::choice('key', $count)
  • Lang::has('key')

Vue.js/JavaScript Functions

  • $t('key')
  • i18n.t('key')

HTML Attributes

  • v-t="'key'"
  • x-text="'key'"

Advanced Context Detection

When advanced pattern detection is enabled (default), the package also detects quoted strings that look like translation keys, such as "messages.welcome_user" or "auth.failed".

Intelligent Exclusions

The package automatically ignores strings inside route() and config() function calls to prevent false positives.

Custom Patterns

You can define your own regular expression patterns by creating a text file and passing its path to the --custom-patterns option. The format for each line should be: REGEX_PATTERN|DESCRIPTION|CAPTURE_GROUP_NUMBER.

Example my-patterns.txt file:

t\(['"]([^'"]+)['"]\)|Custom t() function|1
translate\(['"]([^'"]+)['"]\)|Custom translate() function|1

Getting Help

For detailed information about all available command options and their usage, run:

php artisan help translations:extract-and-generate

This will display comprehensive help information including:

  • Command description
  • Usage syntax
  • All available options with descriptions
  • Default values for each option
  • Verbosity levels and output control options

Troubleshooting

Common Issues

API Key Issues:

  • Ensure your GEMINI_API_KEY is set correctly in your .env file.
  • Verify your API key is active and has sufficient quota.

Rate Limiting Issues:

  • The free tier of Gemini 2.0 Flash-Lite has limits of 30 RPM and 1,500 requests per day.
  • If you encounter rate limiting errors, try reducing the --chunk-size to send fewer keys per request.
  • Increase --retry-delay to add more time between retries.
  • For large projects, consider processing translations in multiple sessions to stay within daily limits.

Performance Issues:

  • Use the --driver=fork option for the fastest processing. This requires the pcntl PHP extension to be installed and enabled.
  • If fork is unavailable, the command will run sequentially (sync), which is slower but more compatible.
  • Increase GEMINI_REQUEST_TIMEOUT in your .env file if you are translating very large chunks of text.

Memory Issues:

  • For very large projects, consider processing files in smaller batches by selecting them one by one in the interactive prompt.
  • Reduce the --chunk-size to send fewer keys per API request.

Command Help:

  • If you're unsure about any option or need to see all available parameters, use the help command: 
    php artisan help translations:extract-and-generate

Security Vulnerabilities

If you discover a security vulnerability within this package, please send an e-mail to the maintainer. All security vulnerabilities will be promptly addressed.

Acknowledgments

This package would not be possible without the excellent work of the following open-source projects:

License

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