survos / lingua-bundle

2.24.22 2026-08-19 11:02 UTC

Requires

• php: ^8.5
• survos/babel-bundle: ^2.10
• survos/kit-bundle: ^2.6
• survos/lingua-contracts: ^2.5
• survos/lingua-core: ^2.5
• symfony/config: ^8.1
• symfony/console: ^8.1
• symfony/dependency-injection: ^8.1
• symfony/framework-bundle: ^8.1
• symfony/http-client: ^8.1
• symfony/http-kernel: ^8.1
• symfony/remote-event: ^8.1
• symfony/routing: ^8.1
• symfony/webhook: ^8.1

Requires (Dev)

• doctrine/orm: ^3.5
• symfony/messenger: ^8.1
• symfony/phpunit-bridge: ^8.1

Suggests

• symfony/messenger: Required to actually receive translation.completed — the webhook endpoint dispatches a ConsumeRemoteEventMessage.

MIT

• Tac Tacelosky

• symfony
• translation
• survos

Published on Packagist.org on 2026-08-19 11:02 UTC

README

A Symfony bundle for lingua functionality.

Features

• Twig extension with custom filters and functions
• Main service class for business logic
• Controller with example routes
• Console command for CLI operations
• Configurable via environment variables

Installation

Install the bundle using Composer:

composer require survos/lingua-bundle

If you're using Symfony Flex, the bundle will be automatically registered. Otherwise, add it to your config/bundles.php:

return [
    // ...
    Survos\LinguaBundle\SurvosLinguaBundle::class => ['all' => true],
];

Configuration

Configure the bundle in config/packages/lingua.yaml:

survos_lingua:
  api_key: '%env(SURVOS_LINGUA_API_KEY)%'

Or set environment variables:

SURVOS_LINGUA_API_KEY=your_value_here

Usage

This bundle provides various components depending on your configuration. Check the generated service classes and controllers for specific usage examples.

Being told when a string is translated

Translation on the lingua server is asynchronous, and the historical way to collect results was to poll with lingua:pull — a job that usually finds nothing, and that nobody schedules until a locale turns up empty in production.

Set a callback URL and lingua announces them instead:

LINGUA_CALLBACK_URL=https://your-app.example/webhook/lingua
LINGUA_WEBHOOK_SECRET=<same value the lingua server signs with>

lingua:push then sends each string's Str.code as a ref, the server records a subscription per (string × target locale), and POSTs a signed translation.completed carrying up to 500 finished translations inline. TranslationUpdateApplier writes them to StrTranslation and dispatches TranslationUpdatedEvent for app-specific work (reindexing, cache busting).

In the app:

# config/routes/webhook.yaml
webhook:
    resource: '@FrameworkBundle/Resources/config/routing/webhook.php'
    prefix: /webhook

# config/packages/webhook.yaml
framework:
    webhook:
        routing:
            lingua:
                service: Survos\LinguaBundle\Webhook\LinguaWebhookRequestParser
                secret: '%env(default::LINGUA_WEBHOOK_SECRET)%'

# config/packages/messenger.yaml — REQUIRED, or the endpoint's 202 is a lie
framework:
    messenger:
        routing:
            'Symfony\Component\RemoteEvent\Messenger\ConsumeRemoteEventMessage': lingua_callback

Leave LINGUA_CALLBACK_URL unset and nothing changes — no subscriptions are created and lingua:pull remains the way to collect results.

Full contract: kit-bundle/docs/webhooks.md.

Replaced LinguaWebhookController, which checked an X-Api-Key by hand and whose route was never registered. See survos-sites/mediary#8.

Testing

Run the test suite:

./vendor/bin/phpunit

License

This bundle is released under the MIT license. See the LICENSE file for details.