## Getting Started

### Minimal Steps
1. **Installation**:
   ```bash
   composer require nativecodein/laravel-translation-scanner

No additional configuration is required—auto-discovery handles the service provider.

First Scan: Run the scanner to extract all translation strings from your project:
```
php artisan translations:scan
```
This will:
- Scan .php, .blade.php, .js, .ts, .jsx, and .tsx files.
- Append missing translation keys to resources/lang/en.json with the key as the default value.
- Skip excluded folders (vendor/, node_modules/, etc.).

First Use Case: After scanning, use the extracted translations in your code:

// Blade
{{ __('Dashboard') }}

// PHP
return trans('Welcome Back');

// Inertia React (TSX)
t("Login");

Implementation Patterns

Core Workflow

Scanning:
- Integrate translations:scan into your CI/CD pipeline (e.g., GitHub Actions) to ensure translations are always up-to-date.
- Run manually during feature development to catch new translation strings early.
- Example workflow:
```
git add .
composer require nativecodein/laravel-translation-scanner
php artisan translations:scan
git commit -m "feat: add translations for new dashboard"
```

Translation Generation:

Use translations:translate to generate translations for target locales (e.g., Spanish, Arabic):
```
php artisan translations:translate es ta ar
```

Schedule this command in a cron job or Laravel scheduler for periodic updates:

// app/Console/Kernel.php
protected function schedule(Schedule $schedule)
{
    $schedule->command('translations:translate es ta ar')->weekly();
}

Inertia.js Integration:
- For React/TypeScript projects, ensure your t() calls are consistent:
```
// Good: Direct string
t("Settings")

// Good: Template literal
t(`Welcome, ${user.name}`)

// Good: Variable (scanner resolves it)
const key = "Dashboard";
t(key)
```
- Avoid dynamic keys (e.g., t(user.customKey)) unless you handle them via custom logic.

Blade/PHP Patterns:

Prefer __() for static strings and trans() for dynamic keys with replacements:

// Static
__('Homepage')

// Dynamic (with replacements)
trans('Welcome back, :name!', ['name' => $user->name])

Use pluralization in Blade:

{{ __('Post :count', ['count' => $posts->count()]) }}

Testing:

Add a test script to verify translations are scanned correctly:
```
php artisan translations:scan --dry-run
```

Use PHPUnit to assert translations exist:

public function test_translations_are_scanned()
{
    $this->artisan('translations:scan')
         ->expectsOutputToContain('Added: Dashboard');
    $this->assertFileExists(database_path('lang/en.json'));
}

Gotchas and Tips

Pitfalls

Dynamic Keys:
- The scanner cannot resolve dynamic keys like t(user.key). Workaround:
  - Use a custom resolver (extend the package or pre-process keys).
  - Example: Replace t(user.key) with t(user.key || 'fallback') in your JS/TS.
False Positives:
- The scanner may pick up non-translation strings (e.g., t as a variable name). Exclude files/folders via:
```
php artisan translations:scan --exclude=path/to/file.js
```
- Or rename conflicting variables (e.g., const t = 'temp' → const temp = 'temp').
Locale-Specific Issues:
- Right-to-left (RTL) languages (e.g., Arabic) may need manual adjustments for punctuation/placement.
- Special characters in keys (e.g., key.with.dots) may cause parsing issues in some translation APIs. Sanitize keys:
```
// In a custom provider
$key = preg_replace('/[^a-zA-Z0-9._-]/', '_', $key);
```
API Rate Limits:
- Free translation APIs (e.g., LibreTranslate) may throttle requests. Mitigate by:
  - Using the built-in usleep(300000) delay (configurable in the package).
  - Caching translated files to avoid re-translating unchanged keys:
```
php artisan translations:translate es --cache
```
Inertia.js Edge Cases:
- JSX expressions like t({ key: variable }) are not supported. Use:
```
t(variable) // Supported
```
- Async t() calls (e.g., in useEffect) may not be scanned. Ensure strings are defined as constants first.
Merge Conflicts:
- The scanner appends to en.json but may conflict with manual edits. Use:
```
php artisan translations:scan --force  # Overwrites en.json (use with caution)
```
- Git strategy: Commit en.json separately from code changes to avoid merge hell.

Debugging

Dry Run:
- Test scanning without modifying files:
```
php artisan translations:scan --dry-run
```
- Outputs what would be added without saving.
Verbose Mode:
- Show detailed scanning logs:
```
php artisan translations:scan -v
```

Custom Paths:

Scan specific directories:

php artisan translations:scan --path=app/Http/Controllers --path=resources/js

Provider Debugging:

If translations fail, check which provider is used:

php artisan translations:translate es --provider=google

Add debug flag to see API responses:

php artisan translations:translate es --debug

Extension Points

Custom Providers:

Add a new translation provider by publishing the config:

php artisan vendor:publish --provider="NativeCodeIn\TranslationScanner\TranslationScannerServiceProvider" --tag="config"

Extend NativeCodeIn\TranslationScanner\Contracts\TranslationProvider:

class DeepLProvider implements TranslationProvider {
    public function translate(string $text, string $locale): string {
        // Custom DeepL API logic
    }
}

'providers' => [
    'deepl' => \App\Providers\DeepLProvider::class,
],

Pre/Post-Scan Hooks:

Listen to the translations.scanned event to process results:

// app/Providers/EventServiceProvider.php
protected $listen = [
    'NativeCodeIn\TranslationScanner\Events\TranslationsScanned' => [
        \App\Listeners\ProcessTranslations::class,
    ],
];

Example listener:

public function handle(TranslationsScanned $event) {
    foreach ($event->newKeys as $key) {
        Log::info("New translation key: $key");
    }
}

Excluding Keys:
- Skip specific keys (e.g., internal strings) by adding a .translationignore file:
```
# .translationignore
/^internal\./
/^temp\./
```
- Or use the --ignore flag:
```
php artisan translations:scan --ignore="internal.*"
```

Post-Processing:

Use the translations:scan output to generate TypeScript types for your translations:

php artisan translations:scan | grep 'Added:' | awk '{print "const " $2 " = \"" $2 "\";"}' > resources/js/translations.d.ts

Performance Tips

Incremental Scanning:
- For large projects, scan specific paths first:
```
php artisan translations:scan --path=resources/views
```
- Use --changed to scan only modified files (requires Git):
```
php artisan translations:scan --changed
```
Parallel Processing:
- The scanner processes files sequentially. For faster scans, consider:
  - Running in parallel (e.g., via Laravel queues):
```
// app/Console/Commands/ScanTranslations.php
public function handle() {
    $files =
```

Laravel Translation Scanner Laravel Package