README

Artisan Translator streamlines the localization workflow in Laravel applications. It automates the extraction of strings from Blade templates, translates them using Google's Gemini AI, and helps keep your language files clean by removing unused keys.

Key Features

• 🔍 Automatic Extraction: Scans Blade templates (.blade.php) for raw text wrapped in common helpers (e.g. __('Hello')), replaces them with translation keys, and saves the source strings to language files.
• 🤖 AI Translation: Uses Google Gemini to translate your strings into multiple languages.
• 🚀 Batch Processing: Translates strings in batches to optimize API usage and reduce costs/time.
• 🧹 Smart Cleanup: Detects and removes translation keys that are no longer used in your codebase.
• 🛡️ Safe & Robust: Preserves HTML tags and Laravel placeholders (:name, {count}) during translation. Includes retry mechanisms for API stability.

Requirements

• PHP: 8.2 or higher
• Laravel: 11.0+ or 12.0+

Installation

Install the package via Composer:

composer require --dev artryazanov/artisan-translator

The package will automatically register its service provider.

Setup

1. Get a Gemini API Key: Obtain an API key from Google AI Studio.

2. Configure Environment: Add the key to your .env file:

   GEMINI_API_KEY=your-api-key-here
   GEMINI_MODEL=gemma-3-27b-it

3. (Optional) Publish Configuration: Customise default settings by publishing the config file:

   php artisan vendor:publish --provider="Artryazanov\ArtisanTranslator\ArtisanTranslatorServiceProvider" --tag="config"

Usage

1. Extract Strings

Scan your resources/views directory to find static strings, replace them with translation keys in the Blade files, and save the original strings to your source language files (default: en).

php artisan translate:extract

Options:

• --path=dir/name: Limit scanning to a specific subdirectory within resources/views.
• --dry-run: Preview changes without modifying any files.
• --force: Overwrite existing keys in translation files if they overlap.

📝 What strings are extracted?

The command scans for strings wrapped in __('...') or @lang('...'). It intelligently distinguishes between "plain text" that needs extraction and existing translation keys.

2. Translate with AI

Translate your extracted strings from the source language to one or more target languages using Gemini.

php artisan translate:ai --targets=fr --targets=de

Arguments & Options:

• source (optional): Specify source language (defaults to source_language in config, usually en).
• --targets: Required. The target language code(s) (e.g., fr, es, de). Can be repeated.
• --force: Overwrite existing translations in the target files.

Note: If you have mcamara/laravel-localization installed, the package can automatically detect supported locales if you omit --targets.

3. Cleanup Unused Translations

Keep your language files tidy by removing keys that are no longer referenced in your codebase.

php artisan translations:cleanup --dry-run

Options:

• --dry-run: List unused keys without deleting them (Recommended first step).
• --force: Skip the confirmation prompt and delete immediately.

Configuration

Main Config (config/artisan-translator.php)

Cleaner Config (config/translation-cleaner.php)

• scan_paths: Directories to scan for translation usage (defaults to app_path() and resource_path('views')).
• file_extensions: File types to scan (defaults to *.php, *.blade.php).
• translation_functions: Functions to look for (e.g., __, trans, @lang).

Supported AI Models

You can use any string supported by the Gemini API, or one of the built-in Enum values:

• gemini-3.0-pro
• gemini-3.0-flash
• gemini-2.5-pro
• gemini-2.5-flash
• gemini-2.5-flash-lite
• gemma-3-27b-it (Default)

Testing

Run the test suite to ensure everything is working correctly:

composer test

License

MIT. See LICENSE.