PHPackages                             jayesh/laravel-gemini-translator - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Localization & i18n](/categories/localization)
4. /
5. jayesh/laravel-gemini-translator

ActiveLaravel-package[Localization & i18n](/categories/localization)

jayesh/laravel-gemini-translator
================================

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

5.0.1(2mo ago)702.2k—5.6%41MITPHPPHP ^8.3CI passing

Since Jun 14Pushed 2mo ago2 watchersCompare

[ Source](https://github.com/jayeshmepani/laravel-gemini-translator)[ Packagist](https://packagist.org/packages/jayesh/laravel-gemini-translator)[ Docs](https://github.com/jayeshmepani/laravel-gemini-translator)[ GitHub Sponsors](https://github.com/sponsors/jayeshmepani)[ RSS](/packages/jayesh-laravel-gemini-translator/feed)WikiDiscussions main Synced 3w ago

READMEChangelog (9)Dependencies (18)Versions (17)Used By (1)

Laravel Gemini AI Translation Extractor
=======================================

[](#laravel-gemini-ai-translation-extractor)

An interactive Artisan command that scans your Laravel project for translation keys, translates them using Google's Gemini AI, and generates the necessary language files with advanced safety and performance features.

[![Latest Version on Packagist](https://camo.githubusercontent.com/0fe58678ac473df08724d1056aafa152f7649d296bf5238eff2ce370f5eceaf4/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6a61796573682f6c61726176656c2d67656d696e692d7472616e736c61746f722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/jayesh/laravel-gemini-translator)[![Total Downloads](https://camo.githubusercontent.com/f7a06780853db78096fbc6fd83ddabe11dfa3387f850fc397c856997b7af80fc/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6a61796573682f6c61726176656c2d67656d696e692d7472616e736c61746f722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/jayesh/laravel-gemini-translator)[![License](https://camo.githubusercontent.com/b80fc24a3d8a23e8a39736ae392e2ea8565019e5a5aa8568df571d5f5eadf30e/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f6a61796573682f6c61726176656c2d67656d696e692d7472616e736c61746f722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/jayesh/laravel-gemini-translator)

🚀 Key Features
--------------

[](#-key-features)

- **AI-Powered Translation:** Uses Gemini AI for high-quality translations with context awareness
- **Interactive & Cross-Platform:** Works on all operating systems with robust fallback
- **Flexible Concurrency:** Fork driver for Linux/macOS, sync driver for Windows
- **Smart Key Detection:** Scans Blade, PHP, Vue, JS, and TypeScript files comprehensively
- **Framework Integration:** Automatic Laravel framework translation bootstrapping
- **Three Operational Modes:** Full sync, missing-only (`--skip-existing`), refresh-only (`--refresh`)
- **Production-Ready Safety:** Atomic file writes, path validation, and security checks
- **Module Support:** Full integration with `nwidart/laravel-modules` with consolidation options

📋 Requirements
--------------

[](#-requirements)

- PHP 8.3 or higher
- Laravel 11.0, 12.0, or 13.0
- Google Gemini API key
- `pcntl` extension (for fork driver on Linux/macOS)
- `tokenizer` PHP extension (for proper code parsing)

⚡ Quick Start
-------------

[](#-quick-start)

### 1. Installation

[](#1-installation)

```
composer require jayesh/laravel-gemini-translator
php artisan vendor:publish --provider="Jayesh\LaravelGeminiTranslator\TranslationServiceProvider"
```

### 2. Configuration

[](#2-configuration)

Add to your `.env`:

```
GEMINI_API_KEY="YOUR_GEMINI_API_KEY"
GEMINI_REQUEST_TIMEOUT=600
```

Get your API key from [Google AI Studio](https://makersuite.google.com/app/apikey).

**⚠️ IMPORTANT:** If you published the `config/gemini.php` file from the `google-gemini-php/laravel` package, make sure the `request_timeout` is cast to an integer:

```
// ✅ CORRECT
'request_timeout' => (int) env('GEMINI_REQUEST_TIMEOUT', 600),

// ❌ WRONG - Will cause "Configuration value must be an integer" error
'request_timeout' => env('GEMINI_REQUEST_TIMEOUT', 600),
```

### 3. Basic Usage

[](#3-basic-usage)

```
# Linux/macOS (fastest with configurable concurrency)
php artisan translations:extract-and-generate --driver=fork --concurrency=10

# Windows (stable)
php artisan translations:extract-and-generate --driver=sync

# Preview changes without writing files
php artisan translations:extract-and-generate --dry-run

# Refresh only existing translations (re-translate existing keys only)
php artisan translations:extract-and-generate --refresh

# Add only missing translations (recommended for updates)
php artisan translations:extract-and-generate --skip-existing
```

📖 Documentation
---------------

[](#-documentation)

For detailed documentation, step-by-step guides, and advanced usage examples, visit our comprehensive documentation:

**[📚 Full Documentation](https://jayeshmepani.github.io/laravel-gemini-translator/)**

🔧 Available Options
-------------------

[](#-available-options)

### Basic Options

[](#basic-options)

```
# Custom languages (English is always used as source)
php artisan translations:extract-and-generate --langs=en,es,fr,de

# Skip existing translations (translate only missing keys)
php artisan translations:extract-and-generate --skip-existing

# Refresh existing translations (re-translate existing keys only)
php artisan translations:extract-and-generate --refresh

# Preview without writing files
php artisan translations:extract-and-generate --dry-run

# Custom chunk size for API requests
php artisan translations:extract-and-generate --chunk-size=50

# Custom concurrency (when using fork driver)
php artisan translations:extract-and-generate --concurrency=20

# Exclude directories
php artisan translations:extract-and-generate --exclude=vendor,node_modules

# Custom target directory
php artisan translations:extract-and-generate --target-dir=custom-lang

# Provide project context for better translations
php artisan translations:extract-and-generate --context="E-commerce platform with payment features"
```

### Advanced Options

[](#advanced-options)

```
# Concurrency driver (default, fork, sync)
php artisan translations:extract-and-generate --driver=fork

# Retry settings
php artisan translations:extract-and-generate --max-retries=3 --retry-delay=5

# Custom extensions
php artisan translations:extract-and-generate --extensions=php,blade.php,vue,js,ts,json

# Consolidate module translations
php artisan translations:extract-and-generate --consolidate-modules

# Get help
php artisan help translations:extract-and-generate
```

### Mode Compatibility

[](#mode-compatibility)

- `--refresh` and `--skip-existing` are mutually exclusive (the command will fail if both are used)
- `--dry-run` works with all other options to preview changes
- `--concurrency` only affects fork driver

🏗️ File Structure & Support
-------------------------------

[](#️-file-structure--support)

### Directory Structure

[](#directory-structure)

```
lang/
├── en/
│   ├── auth.php
│   ├── pagination.php
│   ├── passwords.php
│   └── validation.php
├── es/
│   ├── auth.php
│   ├── pagination.php
│   ├── passwords.php
│   └── validation.php
├── en.json
├── es.json
└── fr.json

```

### Supported File Types

[](#supported-file-types)

- **Templates:** `.blade.php`
- **PHP Files:** `.php`
- **Frontend:** `.vue`, `.js`, `.jsx`, `.ts`, `.tsx`
- **Configuration:** `.json`

### Translation Functions

[](#translation-functions)

- **Laravel:** `__()`, `trans()`, `trans_choice()`, `@lang()`, `@choice()`
- **Facade:** `Lang::get()`, `Lang::choice()`, `Lang::has()`
- **Vue:** `$t()`, `i18n.t()`
- **Attributes:** `v-t`, `x-text`, `:v-t`, `:x-text`, `v-bind:v-t`, `v-bind:x-text`

Supports all quote types: single (`'`), double (`"`), and backtick (```).

🌐 Internationalization Features
-------------------------------

[](#-internationalization-features)

### Locale Support

[](#locale-support)

- Automatic locale canonicalization (converts `en-US` to `en_US`)
- Script-aware formatting (title case for English, sentence case for other Latin languages)
- Proper handling for RTL, CJK, Brahmic, and Cyrillic scripts
- Placeholder preservation across all language families

### Translation Quality

[](#translation-quality)

- Placeholder mismatch detection to prevent runtime errors
- Pluralization string handling to maintain Laravel pluralization format
- Smart machine key humanization for better offline placeholders
- Context-aware translation via project-specific context option

🚀 Performance & Safety
--------------------------

[](#-performance--safety)

### Concurrency Options

[](#concurrency-options)

- **Fork Driver:** Parallel processing (Linux/macOS) with configurable processes
- **Sync Driver:** Sequential processing (Windows/Linux) - more stable
- **Configurable Concurrency:** Control number of parallel processes

### Safety Features

[](#safety-features)

- **Atomic File Writes:** Temp files with atomic rename to prevent corruption
- **Path Validation:** Protection against directory traversal attacks
- **Memory Optimization:** Efficient chunk processing to minimize memory usage
- **Retry Logic:** Intelligent error handling with differentiated retry strategies

### Framework Integration

[](#framework-integration)

- Automatic Laravel framework translation bootstrapping
- Smart merging of vendor and app translations
- Only updates files when new keys are detected

🛡️ Security Features
--------------------

[](#️-security-features)

- **Path Validation:** All file paths validated against base directory
- **Atomic Operations:** Temp file strategy prevents partial writes
- **Input Sanitization:** User inputs and context properly sanitized
- **Directory Traversal Prevention:** Strict path checking before file operations

🐛 Troubleshooting
-----------------

[](#-troubleshooting)

### Rate Limits

[](#rate-limits)

- Free tier has 15 RPM / 1000 daily requests
- Use `--retry-delay` and `--max-retries` for better rate limit handling
- Upgrade to Gemini Pro for higher quotas

### Performance Tips

[](#performance-tips)

- Use `--driver=fork --concurrency=N` on Linux/macOS for best performance
- Adjust `--chunk-size` based on API limits (default: 25 keys per request)
- Increase `--concurrency` carefully to avoid hitting rate limits

### Common Issues

[](#common-issues)

#### Configuration Error: "must be an integer, string given"

[](#configuration-error-must-be-an-integer-string-given)

If you see this error:

```
Configuration value for key [gemini.request_timeout] must be an integer, string given.

```

**Fix:** Edit `config/gemini.php` and cast the timeout to integer:

```
'request_timeout' => (int) env('GEMINI_REQUEST_TIMEOUT', 600),
```

#### Other Issues

[](#other-issues)

- **Windows:** Use `--driver=sync` instead of fork for stability
- **Large Projects:** Use smaller `--chunk-size` to avoid API timeouts
- **Module Projects:** Ensure `nwidart/laravel-modules` is properly configured
- **Empty Keys:** Package automatically filters empty/whitespace-only keys (v4.0.1+)
- **Very Long Keys:** Automatic chunk size adjustment for keys >80 characters (v4.0.1+)

### Debugging

[](#debugging)

- Use `--dry-run` to preview changes without writing
- Check `translation_extraction_log.json` for detailed code extraction
- Check `failed_translation_keys.json` for failed translations

🏢 Enterprise Features
---------------------

[](#-enterprise-features)

### Module Support

[](#module-support)

- Full integration with `nwidart/laravel-modules`
- Ability to consolidate module translations to main app directory
- Independent module language file management
- Proper separation of application and module keys

### Production Ready

[](#production-ready)

- Atomic file operations prevent corruption
- Comprehensive error handling and logging
- Dry-run mode for safe testing
- Configurable concurrency for server environments

### Quality Assurance

[](#quality-assurance)

- Placeholder safety checking prevents runtime errors
- Multiple fallback chains for translation failures
- Cross-checking between languages
- Validation of translation quality

📜 License
---------

[](#-license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

---

⭐ **Star this repo** if you find it helpful! | 🐛 **Report issues** on GitHub | 📖 **Read full docs** at [Here](https://jayeshmepani.github.io/laravel-gemini-translator/)

###  Health Score

52

—

FairBetter than 96% of packages

Maintenance88

Actively maintained with recent releases

Popularity34

Limited adoption so far

Community13

Small or concentrated contributor base

Maturity60

Established project with proven stability

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~21 days

Recently: every ~39 days

Total

16

Last Release

60d ago

Major Versions

1.5 → 2.32025-06-24

2.7 → 3.02025-08-30

3.8 → 4.02025-11-23

4.0.3 → 5.0.02026-04-27

PHP version history (3 changes)1.0.0PHP ^8.1

3.8PHP ^8.2

5.0.0PHP ^8.3

### Community

Maintainers

![](https://www.gravatar.com/avatar/32cb5a476cac8bc43ffdf0769601a7425bc7ada6ec2291ee47c87441469035f0?d=identicon)[jayeshmepani](/maintainers/jayeshmepani)

---

Top Contributors

[![jayeshmepani](https://avatars.githubusercontent.com/u/112438589?v=4)](https://github.com/jayeshmepani "jayeshmepani (10 commits)")

---

Tags

ai-toolsai-translatorartisan-commandautomationcomposer-packagedeveloper-toolsgemini-aigoogle-geminii18nlanguage-fileslaravellaravel-ailaravel-localizationlaravel-packagelaravel-translatormultilingualphptranslationtranslation-extractortranslation-generatorphplaravellocalizationautomationi18ntranslationmultilinguallaravel-packagedeveloper-toolscomposer-packagelaravel-aiai-toolslanguage fileslaravel-translatorartisan-commandgoogle-geminilaravel localizationai-translatortranslation-generatortranslation-extractorgemini-ai

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan, Rector

Code StyleLaravel Pint

Type Coverage Yes

### Embed Badge

![Health badge](/badges/jayesh-laravel-gemini-translator/health.svg)

```
[![Health](https://phpackages.com/badges/jayesh-laravel-gemini-translator/health.svg)](https://phpackages.com/packages/jayesh-laravel-gemini-translator)
```

###  Alternatives

[vildanbina/laravel-auto-translation

A Laravel package for automating the translation of language files.

9624.2k3](/packages/vildanbina-laravel-auto-translation)[mominalzaraa/filament-localization

The first and only automatic Filament localization package with intelligent resource scanning, structured translation files, and comprehensive testing

101.6k](/packages/mominalzaraa-filament-localization)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)