PHPackages                             cleargoal/laravel-deepl - 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. cleargoal/laravel-deepl

ActiveLibrary[Localization & i18n](/categories/localization)

cleargoal/laravel-deepl
=======================

Laravel package for DeepL translation with multi-key management, quota tracking, and automatic key rotation

v1.0.0(1mo ago)00MITPHPPHP ^8.1|^8.2|^8.3

Since Mar 24Pushed 1mo agoCompare

[ Source](https://github.com/cleargoal/laravel-deepl)[ Packagist](https://packagist.org/packages/cleargoal/laravel-deepl)[ RSS](/packages/cleargoal-laravel-deepl/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (1)Dependencies (8)Versions (2)Used By (0)

Laravel DeepL Translation
=========================

[](#laravel-deepl-translation)

[![Latest Version on Packagist](https://camo.githubusercontent.com/7ed76379a2cb9caa1be9e706ccf9e6b9300edd7d05de68dcaaf6839d20038357/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f636c656172676f616c2f6c61726176656c2d646565706c2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/cleargoal/laravel-deepl)[![Total Downloads](https://camo.githubusercontent.com/543081c7324d264aef22b61e1ed29143750211a0273467da19fa18e031a6f0bf/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f636c656172676f616c2f6c61726176656c2d646565706c2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/cleargoal/laravel-deepl)

A Laravel package for DeepL translation with advanced features:

- **Multi-Key Management**: Automatic rotation between multiple DeepL API keys from different accounts to increase total quota
- **Quota Tracking**: Per-key character usage tracking with automatic key selection
- **Smart Caching**: 5-minute cache TTL for API keys to reduce database queries
- **Language Detection**: Automatic source language detection
- **Event-Driven**: Laravel events for quota exhaustion notifications
- **Graceful Degradation**: Handles database unavailability during installation
- **Filament Integration**: Optional beautiful admin UI (auto-enabled when Filament is installed)
- **Artisan Commands**: Full CLI management without requiring UI

Requirements
------------

[](#requirements)

- PHP 8.1 or higher
- Laravel 10.x, 11.x, or 12.x
- PostgreSQL, MySQL, or SQLite database

Installation
------------

[](#installation)

Install the package via Composer:

```
composer require cleargoal/laravel-deepl
```

### Publish Configuration

[](#publish-configuration)

Publish the configuration file:

```
php artisan vendor:publish --tag=deepl-config
```

This creates `config/deepl.php` where you can customize package behavior.

### Publish and Run Migration

[](#publish-and-run-migration)

Publish the migration:

```
php artisan vendor:publish --tag=deepl-migrations
```

Run the migration to create the `platform_settings` table:

```
php artisan migrate
```

Configuration
-------------

[](#configuration)

### Add Your First API Key

[](#add-your-first-api-key)

Add your DeepL API key using the artisan command:

```
php artisan deepl:add-key "your-deepl-api-key-here" 1 --label="Production Key"
```

Parameters:

- `api-key`: Your DeepL API key
- `renewal-day`: Day of month when quota renews (1-31)
- `--label`: Optional friendly name for the key

That's it! The key is now stored in the database and ready to use.

### Optional: Customize Storage

[](#optional-customize-storage)

If you want to use a different table or key name, add to your `.env`:

```
DEEPL_SETTINGS_TABLE=platform_settings  # default
DEEPL_SETTINGS_KEY=deepl_api_keys       # default
```

Usage
-----

[](#usage)

### Basic Translation

[](#basic-translation)

Translate text from one language to another:

```
use Cleargoal\LaravelDeepL\Facades\DeepL;

// Translate English to German
$translated = DeepL::translate('Hello, world!', 'en', 'de');
// Result: "Hallo, Welt!"

// Translate Ukrainian to French
$translated = DeepL::translate('Доброго ранку', 'uk', 'fr');
// Result: "Bon matin"
```

### Translate to All Languages

[](#translate-to-all-languages)

Translate text to all supported languages at once:

```
use Cleargoal\LaravelDeepL\Facades\DeepL;

$translations = DeepL::translateToAll('Welcome to our platform', 'en');

// Result:
// [
//     'en' => 'Welcome to our platform',
//     'uk' => 'Ласкаво просимо на нашу платформу',
//     'de' => 'Willkommen auf unserer Plattform',
//     'fr' => 'Bienvenue sur notre plateforme',
//     'es' => 'Bienvenido a nuestra plataforma'
// ]
```

### Language Detection

[](#language-detection)

Automatically detect the language of text:

```
use Cleargoal\LaravelDeepL\Facades\DeepL;

$detectedLang = DeepL::detectLanguage('Bonjour le monde');
// Result: 'fr'

$detectedLang = DeepL::detectLanguage('Hola mundo');
// Result: 'es'
```

### Using Dependency Injection

[](#using-dependency-injection)

You can also inject the service directly:

```
use Cleargoal\LaravelDeepL\Services\DeepLTranslationService;

class TranslationController extends Controller
{
    public function __construct(
        private DeepLTranslationService $deepl
    ) {}

    public function translate(Request $request)
    {
        $translated = $this->deepl->translate(
            $request->input('text'),
            $request->input('source'),
            $request->input('target')
        );

        return response()->json(['translation' => $translated]);
    }
}
```

Managing API Keys
-----------------

[](#managing-api-keys)

The package provides artisan commands for easy key management.

**Important**: To increase your total quota, each API key must be from a **different DeepL account**. Multiple keys from the same account share the same quota and won't increase your limit. Create separate DeepL Free accounts (different emails) to get 500,000 characters per account per month.

### Add a New Key

[](#add-a-new-key)

```
php artisan deepl:add-key "your-api-key" 15 --label="Production Key #2"
```

### List All Keys

[](#list-all-keys)

```
php artisan deepl:list-keys
```

This displays a table with all keys, showing:

- Index number
- Label
- Masked API key
- Status (Active/Inactive)
- Remaining quota
- Usage percentage
- Renewal day

Tip: Use `--show-keys` to display full API keys (be careful in shared environments).

### Check Quota

[](#check-quota)

Check all keys:

```
php artisan deepl:check-quota
```

Check a specific key:

```
php artisan deepl:check-quota --key=0
```

### Remove a Key

[](#remove-a-key)

```
php artisan deepl:remove-key 0
```

The command will ask for confirmation. Use `--force` to skip confirmation.

### Advanced: Programmatic API

[](#advanced-programmatic-api)

If you're building an admin panel or need programmatic access, you can use the `DeepLApiKeyManager` service directly:

```
use Cleargoal\LaravelDeepL\Services\DeepLApiKeyManager;

$keyManager = app(DeepLApiKeyManager::class);

// Add key
$keyManager->addKey('your-api-key', 15, 'Production Key');

// Get all keys
$keys = $keyManager->getAllKeys();

// Check quota for specific key
$quota = $keyManager->checkQuota(0);

// Update key
$keyManager->updateKey(0, [
    'label' => 'Updated Label',
    'is_active' => false,
    'renewal_day' => 1
]);

// Delete key
$keyManager->deleteKey(0);
```

Filament Admin Panel Integration
--------------------------------

[](#filament-admin-panel-integration)

If you're using [Filament](https://filamentphp.com/) in your Laravel application, the package automatically provides a beautiful admin interface for managing DeepL API keys.

### Installation

[](#installation-1)

The Filament integration is automatically enabled when Filament is detected in your application. No additional configuration required!

If you don't have Filament yet:

```
composer require filament/filament:"^3.0"
php artisan filament:install --panels
```

### Features

[](#features)

Once Filament is installed, you'll find a new "DeepL API Keys" page in your admin panel under the "Settings" navigation group. The interface provides:

**Key Management**:

- ➕ **Add API Keys** - Modal form with API key, label, and renewal day (use keys from different DeepL accounts to increase quota)
- 📋 **List Keys** - Table view with quota usage, status, and last check time
- ✏️ **Edit Keys** - Update label, renewal day, and active status
- 🗑️ **Delete Keys** - Remove keys with confirmation

**Quota Monitoring**:

- 🔄 **Refresh Quotas** - Bulk update all keys from DeepL API
- 📊 **Usage Indicators** - Color-coded quota usage (green/yellow/red)
- ⏰ **Next Renewal** - Shows when each key's quota will reset
- ⚠️ **Stale Data Warnings** - Alerts when local quota might be outdated

**Security**:

- 🔒 **Masked API Keys** - Keys are partially hidden by default
- 📋 **Copy to Clipboard** - Quick copy with visual confirmation
- 🔐 **Reveal Full Keys** - Optional full key display

### Customization

[](#customization)

**Navigation Group**: The page appears under "Settings" by default. To change this, publish the views:

```
php artisan vendor:publish --tag=deepl-views
```

Then edit `resources/views/vendor/laravel-deepl/filament/pages/manage-deepl-keys.blade.php`.

You can also extend the `ManageDeepLKeys` class in your own Filament panel:

```
use Cleargoal\LaravelDeepL\Filament\Pages\ManageDeepLKeys as BaseManageDeepLKeys;

class ManageDeepLKeys extends BaseManageDeepLKeys
{
    protected static ?string $navigationGroup = 'Administration';

    protected static ?int $navigationSort = 10;

    // Add custom logic here
}
```

**Access Control**: Use Filament's built-in policy system to restrict access:

```
// In your FilamentPanelProvider or config
->authGuard('web')
->authMiddleware([
    Authenticate::class,
])
```

### Screenshots

[](#screenshots)

The Filament interface provides:

- **Table view** with all your DeepL API keys
- **Add Key** button in the header
- **Quota usage** with color-coded indicators
- **Quick actions** (Check Quota, Edit, Delete) for each key
- **Refresh All Quotas** button to sync with DeepL API

### No Filament? No Problem!

[](#no-filament-no-problem)

If you don't use Filament, the artisan commands provide full functionality via CLI. The Filament integration is completely optional and adds zero overhead if not installed.

Handling Quota Exhaustion
-------------------------

[](#handling-quota-exhaustion)

When all API keys are exhausted, the package fires a Laravel event that you can listen to:

### Option 1: Event Listener

[](#option-1-event-listener)

Create an event listener:

```
// app/Listeners/NotifyAdminsQuotaExhausted.php