Phrase Tag Bundle Laravel Package

Getting Started

This package is a Symfony bundle for extracting Phrase translation tags from templates and syncing keys/translations with Phrase. In a Laravel codebase it is not a native Laravel package, so start by confirming whether you need the full bundle or only its extraction/sync concepts.

Minimal steps:

1. Check PHP compatibility first. Release 4.0.0 is a BC break and deprecates PHP 8.3 support. Verify your composer.json platform requirement and CI matrix before upgrading. If you are on PHP 8.3, stay on 3.2.0 until you can move PHP versions.
2. Install via Composer and register the bundle in a Symfony kernel if you are using it standalone. For Laravel, prefer invoking it through a small Symfony console bootstrap or replicate the extraction command in an artisan command.
3. Publish/define configuration for your Phrase project: project ID, API token, tag prefix/format, and template paths.
4. Run the extraction command against one template directory first. Inspect the generated tag list before pushing anything to Phrase.
5. First use case: extract translation keys from Blade/Twig templates, review the diff, then push new keys to Phrase and pull translations back into your language files.

Where to look first:

• The bundle’s console commands: extraction, push, and pull.
• The configuration reference for tag discovery patterns and Phrase credentials.
• The changelog/upgrade notes for the 4.0.0 BC break and PHP support change.

Implementation Patterns

Typical day-to-day workflow:

• Extract locally before committing. Run tag extraction over resources/views and compare the output. Treat the extracted tag list as a reviewable artifact rather than pushing automatically from every developer machine.
• CI extraction check. In CI, run extraction in dry-run/check mode to fail builds when templates contain untranslated or malformed Phrase tags.
• Push on merge, pull on schedule. Push new keys after merging to your main branch; pull translations on a schedule or before release builds. This avoids noisy Phrase updates from feature branches.
• Separate environments/projects. Point local and CI at a sandbox Phrase project; production releases use the production project. Keep credentials in environment variables, not committed config.
• Laravel integration wrapper. If you cannot run the Symfony bundle directly, create an Artisan command that boots the bundle’s extractor or reuses its tag parser, then maps the output into Laravel’s lang/ files.
• Key naming convention. Keep Phrase tags stable and human-readable. Avoid deriving tags from rendered content or dynamic Blade variables that change frequently.
• Translation file sync. Use pull output as the source for Laravel language files. Normalize locale folder names and file formats before committing pulled translations.

Integration tips:

• Run extraction against explicit paths, not the whole repository, to avoid scanning vendor or compiled assets.
• Store Phrase API tokens in config/services.php or environment variables and never in the bundle config file.
• Add generated/pulled translation files to version control only if your deployment relies on committed translations; otherwise generate them at deploy time.
• Pair the package with a Laravel translation loader if pulled files need to be consumed by __()/trans().

Gotchas and Tips

• 4.0.0 is a BC break. Review the upgrade path before bumping. The release deprecates PHP 8.3 support, so PHP version constraints are the first thing to check. Pin 3.2.0 if you cannot change PHP versions yet.
• Not a native Laravel package. Expect Symfony bundle conventions: kernel registration, bundle config, and Symfony console commands. Do not assume Laravel auto-discovery or Laravel-style config publishing.
• Credential leakage. Phrase API tokens are powerful. Keep them out of committed config and restrict CI logs so extracted/pushed payloads do not expose tokens.
• Over-extraction. Broad template globs can pull in example files, cached views, or vendor templates. Scope extraction paths tightly.
• Tag drift. Renaming a template key can orphan Phrase translations. Treat tag keys as public identifiers and migrate them deliberately in Phrase.
• Dry runs are essential. Always inspect extraction output before pushing. A bad push can create hundreds of junk keys in Phrase.
• Config caching. In Symfony-style setups, changes to bundle config may require cache clearing. In Laravel wrappers, clear config/route caches after changing paths or credentials.
• Extension points. If the bundle’s extractor does not understand Blade syntax, extend or wrap the tag parser rather than post-processing rendered HTML. Parsing templates directly is more reliable.
• Debugging failed syncs. Check the extracted tag list first, then API credentials/project ID, then Phrase API rate limits. Most failures are configuration or malformed tags, not the API itself.