Glottos Laravel Package

Getting Started

1. Install the package

   composer require pragmarx/glottos
   

   Check the required PHP/Laravel versions in composer.json before pulling it in — the package targets PHP 5.3+ and an older Laravel era, so verify compatibility against your app first.

2. Register the service provider and facade in config/app.php:

   'providers' => [
       PragmaRX\Glottos\ServiceProvider::class,
   ],
   'aliases' => [
       'Glottos' => PragmaRX\Glottos\Facade::class,
   ],
   

3. Publish config and migrations

   php artisan vendor:publish --provider="PragmaRX\Glottos\ServiceProvider"
   php artisan migrate
   

   The published config/glottos.php is the first file to open — it defines the translation services (Google, Bing, Yandex, etc.), their API keys, the storage driver, and the locale defaults.

4. Configure a translation service by adding the API key(s) in config/glottos.php (or your .env if the config reads from there). Without a key, external calls will fail.

5. First use case — translate a missing string and cache it:

   use Glottos;
   
   $translated = Glottos::translate('Welcome back', 'en', 'fr');
   

   The value is returned and (depending on config) persisted to the glottos_* tables so subsequent lookups don't hit the external API.

6. First place to look after install: the published migrations (create_glottos_* tables) to understand the schema, then the package README's "Usage" section for the exact method signatures.

Implementation Patterns

Translate-once, store-and-reuse. Glottos is a database-backed translation store as much as an API wrapper. Wrap lookups so the DB is checked before hitting an external service:

function t(string $text, string $from, string $to): string
{
    return Cache::rememberForever("glottos:{$from}:{$to}:".md5($text), function () use ($text, $from, $to) {
        return Glottos::translate($text, $from, $to);
    });
}

Import → translate → export workflow. The most common day-to-day pattern is:

1. Import existing resources/lang/* files into Glottos (so the DB becomes the source of truth).
2. Translate the untranslated entries via the configured service, or edit them in the web UI.
3. Export back out to language files for the runtime loader.

Keep the exported files under version control so you can diff and review machine-translated strings before merging.

Use it as an authoring tool, not a runtime dependency. Calling an external API on every request is slow and rate-limited. Run translation as a build/deploy step (artisan command or queue job), commit the resulting lang files, and let Laravel's normal __()/trans() loader serve them. This decouples production traffic from Glottos entirely.

Service fallback chain. Configure more than one provider and catch failures at the call site — if Google is rate-limited, fall back to Bing/Yandex, and log the miss rather than throwing into the request:

try {
    $value = Glottos::translate($text, 'en', 'de');
} catch (\Exception $e) {
    Log::warning('glottos translate failed', ['text' => $text, 'e' => $e->getMessage()]);
    $value = $text; // graceful degradation
}

Batch/queue translation. For large catalogs, dispatch translation jobs per-string or per-file so you don't block a request and can retry transient API errors with backoff.

Locale mapping. Keep your config/app.php locales and the package's glottos_languages rows in sync — mismatched codes (e.g. pt_BR vs pt-br) are the most common cause of "translation exists but isn't found."

Web UI for content editors. If you enable the package's management routes, put them behind admin middleware and keep them out of the public surface. It's an authoring interface, not a user-facing feature.

Gotchas and Tips

• API keys are mandatory for external translation. If the config has empty keys, translate() will throw or return the source string — silently. Log and assert on missing keys at boot.
• Rate limits and quotas. Google/Bing/Yandex all throttle and bill per character. Batch, cache aggressively, and add a small delay between bulk calls. Never translate in a request/response loop.
• Re-running imports duplicates rows unless the package's importer upserts. Test import idempotency in staging; consider truncating translation tables before a full re-import.
• Export overwrites language files. Always commit before exporting and review the diff. Machine strings often break placeholders like :name and {count} — add a validation pass after export.
• Clear caches after import/export/config edits: php artisan config:clear, cache:clear, and view:clear. Stale config is a frequent "why isn't my key picked up" cause.
• Legacy footprint. The package is old (PHP 5.3+, early Laravel) with few dependents. Pin a version, test on your Laravel version, and be prepared to vendor/fork it. Don't couple your translation layer so tightly that swapping to a maintained tool (e.g. a lang-file manager plus a translate service) becomes a rewrite.
• Migration collisions. The published migrations create glottos_-prefixed tables; if you already manage translations in the DB elsewhere, check for naming overlap before running migrate.
• Database vs. file source of truth. Decide up front whether the DB or the resources/lang files are authoritative. Mixing both leads to drift; a common compromise is DB-authored, files exported, files deployed.
• Extension points. The translation service is resolved through the package's config/manager — you can bind a custom service implementation in the container if you need a provider the package doesn't ship (e.g. DeepL). Look at how the config registers services, then mirror that binding.
• Test with a fake service. For your own test suite, bind a stub translator in the container so unit tests don't hit real APIs. This also lets you assert what would be translated in bulk jobs.