Getting Started

Minimal Setup

Installation

composer require becklyn/translations

Add to config/bundles.php (if using Symfony):

return [
    // ...
    Becklyn\TranslationsBundle\BecklynTranslationsBundle::class => ['all' => true],
];

Basic Configuration Add to config/packages/becklyn_translations.yaml:
```
becklyn_translations:
    cache_version: 1
```

First Use Case

Define extraction rules in config/packages/becklyn_translations.yaml:

becklyn_translations:
    extract:
        frontend:
            messages:
                - app.*
                - auth.*

Run the extraction command:

php bin/console becklyn:translations:extract

Include the generated JS in your frontend:

<script src="{{ asset('_v/translations/frontend.js') }}"></script>

Initialize translations in JS:

window.translations = window.translations || {};
window.translations.init('frontend', translations);

Implementation Patterns

Workflows

Translation Extraction
- Use the CLI command to extract translations from PHP files:
```
php bin/console becklyn:translations:extract
```
- Schedule this command in a post-update-cmd in composer.json for CI/CD pipelines:
```
"scripts": {
    "post-update-cmd": [
        "@php bin/console becklyn:translations:extract"
    ]
}
```

Namespacing Translations

Organize translations by context (e.g., frontend, admin):

becklyn_translations:
    extract:
        frontend:
            messages: [app.*, auth.*]
        admin:
            messages: [admin.*, settings.*]

Load translations dynamically in JS:

// Load frontend translations
translations.init('frontend', translationsFrontend);

// Load admin translations (if needed)
translations.init('admin', translationsAdmin);

Integration with Frontend Frameworks

Vue.js: Bind translations to a Vuex store or composable:

import { useTranslations } from '@/composables/translations';

const { t } = useTranslations('frontend');

React: Use a context provider:

const TranslationContext = createContext();
// Wrap app with <TranslationContext.Provider value={translations}>

Dynamic Translation Updates
- Invalidate cache when translations change:
```
php bin/console becklyn:translations:invalidate-cache
```
- Or bump cache_version in config and redeploy.

Integration Tips

Laravel-Specific Setup

Publish config for customization:

php artisan vendor:publish --provider="Becklyn\TranslationsBundle\BecklynTranslationsBundle" --tag="config"

Override default routes in routes/web.php:

Route::get('_v/translations/{namespace}.js', \Becklyn\TranslationsBundle\Controller\TranslationController::class)
    ->where('namespace', 'frontend|admin');

Custom Extraction Logic

Extend the extractor service by binding your own implementation:

$this->app->bind(
    \Becklyn\TranslationsBundle\Extractor\ExtractorInterface::class,
    \App\Services\CustomExtractor::class
);

Localization with JavaScript

Use libraries like i18next alongside the bundle:

i18next.init({
    resources: {
        en: { translation: translations }
    }
});

Testing

Mock translations in PHPUnit:

$this->app->instance(
    \Becklyn\TranslationsBundle\Loader\TranslationLoaderInterface::class,
    new \App\Tests\MockTranslationLoader()
);

Gotchas and Tips

Pitfalls

Cache Invalidation
- Forgetting to bump cache_version after manual translation edits will serve stale JS.
- Fix: Automate cache invalidation in deployment scripts or use a post-save hook in your CMS.
Wildcard Overuse
- Overly broad patterns (e.g., *.*) may extract unused translations, bloating JS bundles.
- Fix: Scope patterns tightly (e.g., auth.* instead of *.*).
Namespace Collisions
- Reusing namespaces (e.g., frontend for both PHP and JS) can cause confusion.
- Fix: Use descriptive names (e.g., frontend-php, frontend-js).
Route Conflicts
- Default routes (/_v/translations/) may clash with existing routes.
- Fix: Customize the route prefix in config/packages/becklyn_translations.yaml:
```
_import.becklyn_translations:
    resource: '@BecklynTranslationsBundle/Resources/config/routes.yaml'
    prefix: /assets/translations/
```

Debugging

Missing Translations
- Check if the extraction command ran successfully:
```
php bin/console becklyn:translations:extract --verbose
```
- Verify the config matches your translation keys (e.g., app.welcome vs. app.*).
JS Not Loading
- Ensure the route is accessible:
```
curl http://localhost/_v/translations/frontend.js
```
- Check browser dev tools for 404 errors or failed requests.
Cache Issues
- Clear Laravel cache:
```
php artisan cache:clear
php artisan config:clear
```
- Manually delete cached files in var/cache/dev/ (or bootstrap/cache/ in Laravel).

Tips

Versioning
- Use semantic versioning for cache_version (e.g., 1.0.0 for major updates, 1.0.1 for minor fixes).

Environment-Specific Configs

Override extraction rules per environment:

# config/packages/becklyn_translations_{env}.yaml
becklyn_translations:
    extract:
        frontend:
            messages: [app.%, auth.*]  # % = current env

Performance

Exclude unused languages from extraction:

becklyn_translations:
    extract:
        frontend:
            locales: [en, fr]  # Only extract for these locales

Extending Functionality

Add custom filters to the extractor:

// app/Extractor/CustomFilter.php
public function filter(array $messages): array {
    return array_filter($messages, fn($key) => str_contains($key, 'custom.'));
}

Bind the filter in AppServiceProvider:

$this->app->make(\Becklyn\TranslationsBundle\Extractor\Extractor::class)
    ->addFilter(new \App\Extractor\CustomFilter());

Local Development
- Disable caching in config/packages/becklyn_translations.yaml:
```
becklyn_translations:
    cache_version: dev  # Forces cache busting
```

Translations Laravel Package