Skip to main content
This guide will walk you through translating your first language file using AI Translations for Laravel.

​
Before you begin

Make sure you have:
  • Installed the package via Composer
  • Published the configuration file
  • Added your LLM provider API key to .env
If you haven’t completed these steps, see the installation guide.

​
Step 1: Prepare your source language file

First, create a language file in your base language (typically en). For this example, we’ll create a simple authentication messages file:
lang/en/auth.php
<?php

return [
    'failed' => 'These credentials do not match our records.',
    'password' => 'The provided password is incorrect.',
    'throttle' => 'Too many login attempts. Please try again in :seconds seconds.',
];

​
Step 2: Configure your environment

Add your LLM provider credentials to your .env file: 
ANTHROPIC_API_KEY=sk-ant-api03-...
Set your provider in config/ai-translations.php:
config/ai-translations.php
return [
    "provider" => "anthropic", // Change to your provider
    // ... rest of config
];

​
Step 3: Run your first translation

Now you’re ready to translate your language files. Run the translate command: 
php artisan translate
You’ll see output similar to this: 
AI Translator
Source: en
Languages: de, es, fr
Domains: auth

Translating from en to de: auth
3 missing keys found: failed, password, throttle

  ┌ Translating in 1 chunks... (attempt #1 of 3) ──────────────┐
  │ ████████████████████████████████████████████████████  100% │
  └──────────────────────────────────────────────────────────────┘

Generated translations for auth from en to de:
failed: "Diese Zugangsdaten stimmen nicht mit unseren Unterlagen überein."
password: "Das angegebene Passwort ist falsch."
throttle: "Zu viele Anmeldeversuche. Bitte versuchen Sie es in :seconds Sekunden erneut."

Writing translations for auth from en to de
The package will:
  1. Detect all languages in your lang directory
  2. Find missing translations for each language
  3. Use AI to generate contextually appropriate translations
  4. Write the translations to your language files

​
Step 4: Check the generated translations

The package creates new language files for each target language:
lang/de/auth.php
<?php

return [
    'failed' => 'Diese Zugangsdaten stimmen nicht mit unseren Unterlagen überein.',
    'password' => 'Das angegebene Passwort ist falsch.',
    'throttle' => 'Zu viele Anmeldeversuche. Bitte versuchen Sie es in :seconds Sekunden erneut.',
];
Notice how the AI preserves the :seconds placeholder in the translation. The LLM is context-aware and understands Laravel’s translation placeholders.

​
Step 5: Validate your translations

Verify that all translations are complete using the validation command: 
php artisan translate:validate
You’ll see a summary table: 
Checking translations...
Source: en
Languages: de, es, fr
Domains: auth

  ┌────────────┬───────────────┐
  │ Domain     │ Missing Keys  │
  ├────────────┼───────────────┤
  │ de/auth    │ ✔             │
  │ es/auth    │ ✔             │
  │ fr/auth    │ ✔             │
  └────────────┴───────────────┘
A green checkmark (✔) means no missing translations. Red numbers indicate how many keys are missing.

​
Common translation scenarios

​
Translate a specific file

If you only want to translate a specific language file: 
php artisan translate --name=auth

​
Translate to a specific language

To translate only to German: 
php artisan translate --language=de

​
Translate from a different base language

If your source language is German instead of English: 
php artisan translate --base-language=de

​
Use faster (but less accurate) translations

For quicker translations using a faster model: 
php artisan translate --fast

​
Interactive mode

For more control, use interactive mode to review and re-translate files: 
php artisan translate --interactive
In interactive mode, you’ll be prompted to confirm translations for each file, allowing you to regenerate if needed.

​
Updating existing translations

When you add new keys to your base language file, simply run the translate command again:
lang/en/auth.php
<?php

return [
    'failed' => 'These credentials do not match our records.',
    'password' => 'The provided password is incorrect.',
    'throttle' => 'Too many login attempts. Please try again in :seconds seconds.',
    'locked' => 'Your account has been locked.', // New key
];

php artisan translate
The package will detect the missing locked key and translate only that key: 
Translating from en to de: auth
1 missing keys found: locked

Generated translations for auth from en to de:
locked: "Ihr Konto wurde gesperrt."
The package only translates missing keys by default. Existing translations are preserved to maintain consistency and avoid unnecessary API calls.

​
Next steps

Now that you’ve successfully translated your first language file, explore the full capabilities:

Translate command

Learn about all translate command options and features

Validate command

Master translation validation and quality checks

Configuration

Customize your translation workflow and provider settings

Advanced options

Explore advanced command options and workflows

Build docs developers (and LLMs) love

Get started for freeTalk to us