Crowdin Bundle Laravel Package

Getting Started

The mismatch stands, with one important amendment. jjanvier/crowdin-bundle is still a Symfony2 bundle — no service provider, no config/crowdin.php, no auto-discovery — and still targets the PHP 5.4–5.6 / Symfony 2.x era. But release 0.2.0 changes the shape of the package in a way that matters to a Laravel developer: it now requires php-crowdin-lib as a dependency. The HTTP/Crowdin logic has been extracted into a standalone library, and the bundle is now a thin Symfony wrapper around it.

That split is the headline. You no longer have to choose between "install a 2014 Symfony bundle" and "hand-roll HTTP calls." The realistic path is now: composer require the underlying php-crowdin-lib on its own, skip the bundle entirely, and wrap the library in two Artisan commands.

If you actually have a Symfony 2.x host for the bundle:

1. composer require jjanvier/crowdin-bundle:^0.2 — note this now pulls php-crowdin-lib transitively, so dependency resolution has one more pin to satisfy (see Gotchas).
2. Register the bundle in app/AppKernel.php under registerBundles().
3. Put Crowdin project credentials in app/config/parameters.yml and wire the bundle's config key — check DependencyInjection/Configuration.php for the exact root key and node names, don't guess.
4. Run bin/console list and look for the command namespace. That output tells you more than the README does.

Where to look first, in order (revised): composer.json of the bundle and of php-crowdin-lib (the real capability lives there now), then Command/ (the product surface), then DependencyInjection/Configuration.php, then the README.

First use case: a "download translations" command run against a staging build, populating Resources/translations/ from Crowdin instead of hand-editing.

Laravel-first use case: composer require php-crowdin-lib, expose it as a singleton in a small service provider, and write crowdin:pull / crowdin:push Artisan commands on top. That is the correct call in 2024+ and now involves less code than it did before 0.2.0.

Implementation Patterns

The canonical loop (unchanged — the bundle's whole reason for existing):

1. Developer edits source strings (messages.en.yml, XLIFF, whatever your format is) and merges to main.
2. CI runs an upload command pushing only the source file(s) to Crowdin.
3. Translators work in Crowdin.
4. CI or a scheduled job runs a download command pulling completed translations into the repo or a build artifact.
5. Deploy consumes the downloaded translations.

Keep upload and download as separate, independently-runnable steps. Never couple them into one "sync" command — you want to pull without ever risking a push.

Ordering matters in CI. Put the download after your build step, or exclude translation directories from cache keys, otherwise you get stale-language builds that are painful to diagnose. If you commit translations, run the download in a dedicated job that opens a PR — translator output stays reviewable and your deploy pipeline stays read-only.

Credentials via environment, always. Any bundle from this era expects parameters in YAML; pass them from env vars so the same config works across staging/production Crowdin projects.

Laravel parity implementation — now library-backed, not hand-rolled. Before 0.2.0 you had to write the HTTP layer yourself. Now you bind the library and delegate:

// app/Providers/CrowdinServiceProvider.php
public function register(): void
{
    $this->app->singleton(CrowdinClient::class, fn () => new CrowdinClient(
        config('services.crowdin.token'),
        config('services.crowdin.project'),
    ));
}

// app/Console/Commands/CrowdinPull.php
public function handle(CrowdinClient $crowdin): int
{
    $buildId = $crowdin->buildTranslations();   // exact method names: read php-crowdin-lib
    $zip     = $crowdin->downloadBuild($buildId);

    // unzip into lang/, one directory per locale, replacing not merging
    cache()->forever('crowdin:last-pulled-build', $buildId);

    return self::SUCCESS;
}

Two things to keep from the pre-0.2.0 advice: record the build ID you pulled (it's the only proof of which translations shipped in a release), and wrap slow downloads in a queued job.

Treat the library, not the bundle, as your integration surface. Your service provider + commands are ~100 lines and give you the same ergonomics with PHP 8 support and a maintained dependency chain — provided php-crowdin-lib itself resolves on your PHP version. Verify that before committing to the approach (see Gotchas).

Integration tip: make the commands idempotent and safe to re-run. Both CI retries and manual operator reruns will happen, and a download that appends instead of replacing will silently corrupt locale files.

Gotchas and Tips

• 0.2.0 adds a dependency, not a fix. The symfony/framework-bundle constraints are unchanged; a 2014 bundle that now also pins php-crowdin-lib has one more way to fail composer update on PHP 8. Don't expect the release to have modernized the Symfony side.
• php-crowdin-lib is now the thing to vet. Check its composer.json (PHP constraint, Guzzle major version), its last release date, and — critically — which Crowdin API version it targets. If it's still pre-v2, you inherit the deprecated-endpoint problem without the bundle's code to blame. The release notes here say nothing about API modernization; assume nothing.
• Upload semantics are still destructive-by-default territory. Assume an upload can overwrite translated strings unless you've confirmed the library's update-vs-replace behaviour in source. Never point an unverified upload command at a production Crowdin project — use a throwaway project for the first run.
• Placeholders get mangled silently. Symfony-era code often did naive string handling, and moving the HTTP layer into a library doesn't change how translation strings are parsed. Round-trip %name%, :attribute, {count}, and ICU plural blocks before rolling out. Still the #1 source of production sprintf explosions.
• Debugging is better than it was, worse than you'd like. With a real library underneath you can now instantiate the client directly in php artisan tinker and inspect responses — use that before reaching for -v/-vv. Note the commands may still swallow API errors and return a bare non-zero exit; capture the response body on failure. If a command "succeeds" but nothing changes, suspect file-mapping config (source filename, translation file pattern) before auth.
• Extension points improved, but only at the seam. The client is now a separate object, so you can inject a stub in tests and swap implementations. The command classes are still thin and mostly-hardcoded — realistic options remain: subclass the command and override execute, or (better) write your own command and use the library directly. Read the service definitions before planning to decorate anything.
• Rate limits and reruns. Crowdin throttles. Add retry/backoff around the library call if you run per-PR uploads across many branches, and make sure CI doesn't fan out one upload per commit.
• Verdict for a Laravel team (updated): composer require php-crowdin-lib, bind it in a service provider, write two Artisan commands. If the library's PHP/API constraints are acceptable you get a maintained, PHP 8-ready integration with far less code than before 0.2.0. If they aren't, the fallback is unchanged: fifteen minutes in Command/, then two commands against Crowdin API v2 directly. Either way, the Symfony bundle remains a design reference, not a dependency.