## Getting Started

1. **Installation**
   Add to your Laravel project via Composer (preferably in `require-dev`):
   ```bash
   composer require --dev om/potrans

Or globally for CLI access:

composer global require om/potrans

First Command Verify installation with:
```
./vendor/bin/potrans --help
```
Key commands:
- potrans google (Google Translate API)
- potrans deepl (DeepL API)
Initial Translation Translate a .po file to Spanish using Google Translate:
```
./vendor/bin/potrans google ./resources/lang/en/messages.po ./resources/lang/es --lang=es --apikey=$GOOGLE_TRANSLATE_API_KEY
```
Note: Laravel’s .env won’t auto-load; pass keys via CLI or set them in the current directory’s .env.

Implementation Patterns

1. Laravel Integration Workflow

Step 1: Generate POT file from Laravel source:

xgettext -o ./resources/lang/messages.pot --from-code=UTF-8 ./app --keyword=_ --keyword=__ --keyword=trans_choice

Step 2: Translate via potrans in composer.json scripts:

"scripts": {
  "translate:es": "potrans google ./resources/lang/messages.pot ./resources/lang/es --lang=es --apikey=$GOOGLE_TRANSLATE_API_KEY --ignore='^#, fuzzy$'",
  "translate:all": "potrans google ./resources/lang/messages.pot ./resources/lang --lang=de,fr,es --apikey=$GOOGLE_TRANSLATE_API_KEY"
}

Run with:

composer translate:es

2. CI/CD Pipeline

Use in GitHub Actions to auto-update translations on main branch:

- name: Translate new strings
  run: |
    composer translate:all
    git add ./resources/lang/
    git diff --quiet || git commit -m "chore: update translations"
    git push

3. DeepL-Specific Patterns

Batch Processing: Translate multiple files at once:

./vendor/bin/potrans deepl ./resources/lang/en/*.po ./resources/lang/de --lang=de --apikey=$DEEPL_API_KEY --format=po

Ignore Rules: Preserve manual edits with:

--ignore="^#, fuzzy$|^#, translator-comments$"

4. Custom Translator Extension

Create a custom translator (e.g., app/Translators/CustomTranslator.php):

<?php
namespace App\Translators;

use Potrans\Translator\TranslatorInterface;

class CustomTranslator implements TranslatorInterface {
    public function translate(string $text, string $sourceLang, string $targetLang): string {
        // Add custom logic (e.g., fallback to Google if DeepL fails)
        return str_replace('foo', 'bar', $text); // Example
    }
}

Use it via CLI:

./vendor/bin/potrans deepl ./locale/messages.po ./locale --translator=app/Translators/CustomTranslator --lang=fr

5. Laravel Cache Sync

Sync potrans cache with Laravel’s cache:

// In a service provider
use Illuminate\Support\Facades\Cache;
use Illuminate\Support\Facades\File;

Cache::remember('potrans_cache', 3600, function () {
    $cacheDir = base_path('.potrans/cache');
    return File::exists($cacheDir) ? File::get($cacheDir) : null;
});

Gotchas and Tips

1. API Key Management

Laravel .env Limitation: potrans ignores Laravel’s .env. Create a .env in your project root or pass keys via CLI:
```
--apikey=$(cat .env | grep GOOGLE_TRANSLATE_API_KEY | cut -d'=' -f2)
```
DeepL Quotas: DeepL’s free tier has strict limits. Monitor usage via --debug to avoid hitting caps.

2. Language Code Quirks

Mismatched Codes: Google uses zh-CN; DeepL uses ZH. potrans auto-converts, but verify with:
```
./vendor/bin/potrans deepl --debug ./locale/messages.po ./locale --lang=zh-CN
```
Fallback Languages: DeepL may return EN for unsupported languages. Use --ignore to skip or handle in a custom translator.

3. Cache Pitfalls

Cache Location: Defaults to ~/.potrans/cache/. In Docker/Laravel Forge, this may fail. Override with:
```
--cache-dir=./storage/potrans_cache
```
Stale Cache: Use --force to bypass cache for updated strings. Avoid --all (deprecated in v1.0+).

4. PO/MO File Handling

MO File Overwrites: By default, potrans regenerates .mo files. To avoid:
```
--only  # Generate only .po files
```

Encoding Issues: Ensure .po files are UTF-8. Use:

iconv -f ISO-8859-1 -t UTF-8 input.po -o output.po

5. Debugging

API Errors: Add --debug to see raw responses:
```
./vendor/bin/potrans deepl --debug ./locale/messages.po ./locale --lang=fr
```
Common errors:
- DeepL 403: Invalid API key. Verify with curl -X POST "https://api-free.deepl.com/v2/translate" -H "Authorization: DeepL-Auth-Key $DEEPL_API_KEY".
- Google 403: Quota exceeded. Check Google Cloud Console.

6. Laravel-Specific Tips

Filesystem Conflicts: potrans uses symfony/finder. If Laravel’s Illuminate/Filesystem interferes, alias the namespace in composer.json:
```
"autoload": {
  "psr-4": {
    "Symfony\\Component\\Finder\\": "vendor/symfony/finder/"
  }
}
```

Artisan Integration: Wrap potrans in an Artisan command for Laravel-native usage:

namespace App\Console\Commands;

use Illuminate\Console\Command;
use Symfony\Component\Process\Process;
use Symfony\Component\Process\Exception\ProcessFailedException;

class TranslateCommand extends Command {
    protected $signature = 'translate:lang {lang}';
    protected $description = 'Translate Laravel lang files';

    public function handle() {
        $process = new Process(['vendor/bin/potrans', 'google', './resources/lang/en/messages.pot', './resources/lang', '--lang=' . $this->argument('lang'), '--apikey=' . env('GOOGLE_TRANSLATE_API_KEY')]);
        $process->run();
        if (!$process->isSuccessful()) {
            throw new ProcessFailedException($process);
        }
    }
}