Download the PHP package survos/translator-bundle without Composer

Survos Translator Bundle

A Symfony 7.3 / PHP 8.4 bundle that unifies multiple translation engines (DeepL, LibreTranslate, …), adds smart caching, and optional async processing via Messenger. Designed to replace the legacy libre-bundle in the Survos translation server.

Target repo to integrate with next: https://github.com/survos-sites/translation-server

Features

• ✅ Drop‑in service: Survos\TranslatorBundle\Service\Translator
• 🔌 Pluggable engines: DeepL, LibreTranslate (more welcome)
• 🧠 Cache‑first: Symfony Cache (PSR‑6/16) with per‑engine TTL & busting
• 🚀 Async mode: Messenger message + worker for heavy workloads
• 📝 Rich metadata: hash, engine, source/target, confidence, token counts
• 🧪 Handy CLI for quick checks & warmups

Installation

If you use Symfony Flex, the bundle is auto‑enabled. Otherwise, add to config/bundles.php:

Environment & API Keys

Set the following in your .env.local (or server secrets). Only configure the engines you’ll use.

Pro tip: keep engine‑specific keys/names distinct per environment to avoid accidental cross‑use.

Bundle Configuration

Create config/packages/survos_translator.yaml:

Optional: Dedicated Cache Pool

The bundle will auto‑wire a pool named survos_translator.cache if present, otherwise falls back to cache.app.

Quick Start (Sync)

Minimal Service Call (no controller)

Async Translation (Messenger)

Enable a transport (choose one) in config/packages/messenger.yaml:

Dispatch work:

Run a worker:

The worker uses the same caching rules; repeated requests are cheap.

CLI Utilities (Symfony 7.3 style)

The bundle ships a small demo command to smoke‑test config and warm cache.

Sample implementation pattern (your app command):

Notes for this user/project: parameters follow your preferred Symfony 7.3 attribute style (invokable, SymfonyStyle, attributes in __invoke).

Engine Behavior

• DeepL

  • Auto‑selects Free/Pro endpoint by key suffix (-free = Free); can override via DEEPL_BASE_URI.
  • Supports options: formality, glossary_id, preserve_formatting, etc.

• LibreTranslate

  • Works with any compatible instance; set LIBRETRANSLATE_BASE_URI.
  • Some deployments require LIBRETRANSLATE_API_KEY; others don’t.

Both engines normalize language codes and report back detectedSource when source is omitted.

Caching Strategy

• Key = hash(text, source, target, engine, domain, options subset)
• Default TTL via TRANSLATOR_CACHE_TTL or cache pool lifetime
• Bust per domain/engine using provided cache‑clearer:

Error Handling

• Network/HTTP errors raise TranslationTransportException
• Invalid configuration raises TranslationConfigException
• Engines return TranslationResult with meta["cached"] = true|false

Catch & fallback example:

Replacing the Legacy libre-bundle

1. Remove old services/config tied to libre-bundle.
2. Install this bundle and add envs: LIBRETRANSLATE_BASE_URI, optional LIBRETRANSLATE_API_KEY.
3. Search/Replace old client/service with Survos\TranslatorBundle\Service\Translator.
4. Switch endpoints: old /translate controllers can now delegate to the new service.
5. Enable async in the translation server by routing TranslateText via Messenger.
6. Keep your existing cache: point the pool name to survos_translator.cache.

Minimal controller in translation‑server style:

Testing Locally

Extending with New Engines

1. Implement EngineInterface (e.g., AcmeEngine).
2. Tag the service with survos.translator.engine and give it a name.
3. Now you can call with options: ['engine' => 'acme'].

Skeleton:

Roadmap

• Google/Bing providers
• Glossaries & per‑project domains
• Token accounting & quotas per engine
• Batch API for paragraphs (keeps caching per unit)

License

MIT © Survos