Skip to main content
The AI Translations package can automatically detect available languages from your Laravel application or you can manually specify which languages to support. By default, the package automatically detects languages from your lang directory:
config/ai-translations.php
'languages' => null,
When set to null, the package scans your Laravel application’s lang_path() directory and identifies all available language directories.

​
How auto-detection works

The package looks for language subdirectories in your lang folder: 
lang/
├── en/
│   ├── auth.php
│   └── validation.php
├── de/
│   ├── auth.php
│   └── validation.php
├── fr/
│   ├── auth.php
│   └── validation.php
└── es/
    ├── auth.php
    └── validation.php
In this example, the package would automatically detect: en, de, fr, and es.
Auto-detection is the recommended approach as it keeps your configuration in sync with your actual language files.

​
Manual configuration

You can explicitly specify which languages your application supports:
config/ai-translations.php
'languages' => [
    'en',
    'de',
    'es',
    'fr',
    'it',
    'nl',
    'ua',
    'ar',
    'jp',
    'cn',
],

​
When to use manual configuration

Manual configuration is useful when:
  • You want to translate to languages that don’t exist yet in your lang directory
  • You want to exclude certain language directories from translation
  • You need strict control over which languages are processed
  • You’re planning to add new languages and want them configured ahead of time

​
Language codes

Use standard ISO 639-1 language codes (2-letter codes) or locale codes: 
'languages' => [
    'en', // English
    'de', // German
    'es', // Spanish
    'fr', // French
    'it', // Italian
    'pt', // Portuguese
    'nl', // Dutch
    'pl', // Polish
    'ru', // Russian
    'ja', // Japanese
    'zh', // Chinese
    'ko', // Korean
    'ar', // Arabic
],
Ensure the language codes you use match the directory names in your lang folder, otherwise translations won’t be saved correctly.

​
Base language

The base language (also called source language) is the language you’re translating from. By default, this is your application’s locale:
config/app.php
'locale' => 'en',
You can override the base language when running translation commands: 
php artisan translate --base-language=de
This is useful when:
  • Your primary language isn’t English
  • You want to translate from a different source language
  • You’re maintaining translations in multiple directions
The base language should always be complete and accurate, as all other translations are generated from it.

​
Working with language files

​
Creating a new language

To add a new language to your application:
  1. Manual configuration: Add the language code to the languages array
  2. Auto-detection: Create a new directory in your lang folder
mkdir lang/de
Then run the translate command:
php artisan translate --language=de
The package will create translation files automatically.

​
Translating specific languages

You can limit translations to specific languages: 
# Translate only to German
php artisan translate --language=de

# Skip certain languages
php artisan translate --skip-languages=de,fr

​
Validating languages

Check for missing translations in specific languages: 
# Validate all languages
php artisan translate:validate

# Validate specific language
php artisan translate:validate --language=de

# Validate with different base language
php artisan translate:validate --base-language=en

​
Best practices

​
Keep your base language complete

Always ensure your base language (typically en) is complete and up-to-date: 
php artisan translate:validate --language=en
All other translations are generated from this source, so it must be accurate.

​
Use auto-detection when possible

Auto-detection keeps your configuration simple and automatically adapts to your project structure: 
'languages' => null, // Recommended
Organize your language files by domain: 
lang/en/
├── auth.php
├── validation.php
├── messages.php
├── emails.php
└── admin.php
This makes it easier to translate specific sections: 
php artisan translate --name=auth

​
Validate before deploying

Always run validation before deploying to ensure all translations are complete: 
php artisan translate:validate

​
Examples

​
Multi-language application

config/ai-translations.php
return [
    'languages' => null, // Auto-detect from lang directory
    'provider' => 'anthropic',
    'anthropic' => [
        'model' => 'claude-sonnet-4-5',
        'fast_model' => 'claude-haiku-4-5',
        'api_key' => env('ANTHROPIC_API_KEY'),
    ],
];

# Translate all detected languages
php artisan translate

# Translate only specific language
php artisan translate --language=de

# Validate all languages
php artisan translate:validate

​
European languages only

config/ai-translations.php
'languages' => [
    'en', // English
    'de', // German
    'fr', // French
    'es', // Spanish
    'it', // Italian
    'pt', // Portuguese
    'nl', // Dutch
    'pl', // Polish
],

​
Adding Asian languages

config/ai-translations.php
'languages' => [
    'en',    // English
    'ja',    // Japanese
    'ko',    // Korean
    'zh_CN', // Simplified Chinese
    'zh_TW', // Traditional Chinese
    'th',    // Thai
    'vi',    // Vietnamese
],
LLM models generally handle Asian languages well, but always review translations for cultural appropriateness and context.

​
Next steps

Start translating

Learn how to translate your language files

Validate translations

Check for missing translations

Build docs developers (and LLMs) love

Get started for freeTalk to us