Libre Translate Bundle Laravel Package

Getting Started

This is a Symfony bundle, not a Laravel package. In a Laravel codebase, do not expect package discovery, a facade, or publishable Laravel config. Treat it as either:

1. A Symfony-only integration, if you also maintain a Symfony service, or
2. A reference implementation for calling a LibreTranslate instance from Laravel.

First steps:

composer require survos/libre-translate-bundle

Then inspect, in this order:

1. README.md for required config and service IDs.
2. src/ for the client/service class and public methods.
3. DependencyInjection/ and config/ for bundle configuration keys and env vars.
4. composer.json for Symfony/LibreTranslate HTTP dependencies and PHP version constraints.

For Symfony, register the bundle in config/bundles.php if it is not auto-registered, then configure the LibreTranslate base URL and optional API key:

# config/packages/libre_translate.yaml
libre_translate:
    base_uri: '%env(LIBRETRANSLATE_URL)%'
    api_key: '%env(LIBRETRANSLATE_API_KEY)%'

First use case: translate a single short string and verify language detection.

// Symfony: inject the bundle's client/service.
$translated = $translator->translate('Hello world', 'en', 'es');

In Laravel, the practical first move is to wrap the same HTTP contract behind your own interface:

interface Translator
{
    public function translate(string $text, string $source, string $target): string;
}

Implement it with Laravel's Http client against your LibreTranslate instance. Use the bundle's source only to confirm endpoint shapes and payload conventions.

Implementation Patterns

Wrap the bundle behind your own service. With zero stars and no dependents, do not let bundle-specific classes leak across your application. Define a small Translator interface and bind it in Laravel's AppServiceProvider or Symfony's services.yaml. This makes it easy to replace the bundle, mock translations in tests, or switch to a hosted translation provider later.

Use a cache-aside translation layer. Translation calls are network-bound and rate-limited. Cache by a key that includes the instance URL, source language, target language, text hash, and format:

$key = 'lt:' . sha1($baseUri . '|' . $source . '|' . $target . '|' . $text);

Return cached values first; only call LibreTranslate on a miss. In Laravel, use the cache repository; in Symfony, inject a cache pool.

Queue bulk translations. Do not translate large catalogs inside a web request. In Laravel, dispatch jobs per batch or per document. In Symfony, use Messenger. Chunk by sentence or short paragraph, not by arbitrary character count, so translations keep context.

Store translations, not just API responses. For CMS content, products, or UI strings, persist a translations table keyed by source hash, locale, and source locale. This gives you review workflows, stale-translation detection, and the ability to re-run only changed content.

Protect placeholders and markup before sending. LibreTranslate may translate or reorder tokens like :name, {{ count }}, %s, and HTML attributes. Either use the API's HTML format if supported by your instance, or replace placeholders with opaque tokens before translation and restore them afterward.

Detect and validate languages. Call the languages endpoint at boot or during a health check. Normalize locale variants such as pt-BR to supported codes such as pt, and reject unsupported targets before queueing work.

Test with fakes and fixtures. Never hit a live LibreTranslate instance in CI. In Laravel use Http::fake(); in Symfony use the mock HTTP client. Keep fixture translations for snapshot tests, but assert request payloads and cache behavior rather than exact machine-translation output.

Gotchas and Tips

• Symfony bundle, Laravel mismatch. There is no Laravel auto-discovery or facade. In Laravel, install it only if you are deliberately using Symfony components, or port the HTTP call into a Laravel service. Do not assume config/libre_translate.php can be published like a Laravel package config.
• Base URL quirks. Trailing slashes, path prefixes, and reverse-proxy URLs often cause 404s. Configure the full base URI, for example https://translate.example.com, and verify the /translate and /languages endpoints directly with curl.
• API keys are instance-dependent. Public instances may require keys, may disable keys, or may rate-limit aggressively. Self-hosted LibreTranslate often needs no key but may need language models installed.
• Language code mismatch. LibreTranslate language codes are not always ISO locale codes. Check the instance's /languages response rather than hard-coding zh-CN, pt-BR, or similar variants.
• Empty or non-linguistic input. Skip empty strings, whitespace, numbers, punctuation-only strings, and already-correct locales. Sending them wastes quota and can produce odd output.
• HTML can break. If you send HTML, validate and sanitize the result before rendering. Never inject machine-translated HTML into a trusted page without sanitization.
• Cache invalidation is subtle. Include source text, source language, target language, format, and instance URL in the cache key. Otherwise changing models or instances can serve stale translations silently.
• Timeouts and retries. Set explicit connect/read timeouts. Retries are generally safe for translation because the operation is idempotent, but respect rate limits and use backoff.
• Low maturity risk. Zero stars and zero dependents mean no community pressure on backward compatibility. Pin an exact version, read the source, and be prepared to fork or replace. Keep the bundle behind your own interface.
• Debugging. In Symfony, use debug:container to find the actual service ID and the profiler to inspect HTTP calls. In Laravel, log request payloads, status codes, and latency; use Http::fake() for deterministic tests.
• Extension points. Prefer decoration over modification: decorate the translator service, inject a custom HTTP client, or add a caching decorator. If the bundle does not expose the client cleanly, do not fight it — implement the small LibreTranslate HTTP call yourself.