Extractor Laravel Package

Getting Started

sooyoos/extractor is a small utility package for scanning Laravel source code and pulling out translation keys so you can generate/update language files. It's a low-traffic package (0 stars, no dependents), so treat the source as the source of truth and expect to read it before trusting it in production.

1. Install it

   composer require sooyoos/extractor --dev
   

   It's a build-time tool, not a runtime dependency — keep it in require-dev.

2. Register the provider (if needed). Laravel 5.5+ auto-discovery should pick it up. If not, add it to config/app.php under providers. Run php artisan list and look for an extract/translation:* style command — the exact name is worth checking with php artisan | grep -i trans before you start wiring scripts around it.

3. Publish config (if the package ships one).

   php artisan vendor:publish --provider="Sooyoos\Extractor\..."
   

   Confirm whether a config file appears in config/. If not, options are likely flags on the command.

4. Where to look first. Read the command class and the extractor/regex layer — that tells you exactly which patterns (__(), trans(), @lang, trans_choice, etc.) are recognised. This is the single most important thing to understand because everything downstream depends on it.

5. First use case. On a project with strings like __('auth.failed') scattered through controllers and Blade views, run the extractor pointed at app/ and resources/views/, have it write to resources/lang/en/, then diff the output against your existing files. If the diff is clean, you know the package's parser matches your codebase.

Implementation Patterns

Scan-then-diff workflow. The safest pattern is to extract into a scratch directory and diff against your real lang files rather than letting the tool overwrite them:

php artisan extract --path=app --path=resources/views --output=storage/app/extracted
git diff --no-index resources/lang/en storage/app/extracted/en || true

Review the diff, then copy in the new keys.

Wire it into CI as a lint step. Run extraction and fail the build if new keys appear that aren't present in the default locale. This catches "developer added __('foo.bar') but forgot the translation" before merge.

Post-view-authoring pass. The natural moment to run it is after you finish a feature branch that added UI text. Loop over app/ and resources/views/ in one invocation so keys referenced from controllers (flash messages, validation) and Blade templates land in the same file.

Locale-aware generation. If the tool supports a --locale flag or reads config/app.php for the default locale, generate the canonical en file first, then scaffold fr, de, etc. by copying structure with empty values. This gives translators a complete skeleton.

Namespaced translations. If your app relies on package translations (__('vendor::message.key')), scope the extractor to app code only and merge package lang files separately — mixing them will produce keys that look valid but don't resolve.

Config-driven allowlists. If a config file exists, use its include/exclude arrays to skip vendor code, tests, and stubs. Put the config under version control alongside the app so all developers extract identically.

Gotchas and Tips

Dynamic keys are invisible to it. __($key), __("messages.{$type}"), and trans(sprintf('errors.%s', $code)) cannot be statically extracted. Expect these to be missed; maintain them manually or keep them in a separate "dynamic" lang file that the extractor never touches, or it will delete them on regeneration.

Destructive overwrites. Many extractors write the full file, replacing existing content. If it does, any manually-added keys (dynamic ones, keys for values that come from DB) vanish. Always keep a backup or run in diff mode first. Test on a throwaway branch.

Regex false positives. Strings inside comments, docblocks, and unused code will be picked up. So will __('...') inside tests. Tighten include paths rather than trying to fix the output.

Pluralisation and choice semantics. trans_choice('apples', $count) uses the same key as __('apples') but the translation file should contain apples with |-separated plurals or {0} ... {1} ... syntax. If the extractor writes a plain string, plural rendering breaks. Verify how it handles trans_choice and @choice.

Nested key flattening. __('auth.failed') should land as 'failed' => ... under 'auth' => [...] in auth.php, not as a literal 'auth.failed' key in messages.php. If nested output isn't supported, you get a flat file that still technically works via dot access only for top-level keys — a subtle, painful bug. Confirm by inspecting the generated structure.

Blade directives. If @lang('foo') or {{ __('foo') }} isn't in the pattern list, add it — inspect the extractor class for the regex/pattern constant and extend or wrap it if the package allows.

Key case, quoting, and whitespace. Patterns usually match only single-quoted keys. Double quotes, heredocs, and multi-line concatenations are commonly missed. Grep your own code with __\(|trans\( and compare to the extracted set to spot gaps.

Debugging missing keys. Comment out everything but a single Blade file and run. If the key is still missing, it's a pattern problem, not a config problem. Work from one file outward.

Extension points. If the package exposes an interface for extractors/patterns (check src/), implement it for your custom helper functions (t(), lang(), project-specific translate()). This is often the difference between a useful tool and a forgotten one.

Abandoned-package risk. Zero stars and zero dependents means likely no maintenance, no issue activity, and no guarantees against Laravel version bumps. Pin a version in composer.json, avoid coupling CI critically to it on day one, and keep an eye on whether illuminate/support constraints in its composer.json keep pace with your framework. If they drift, be prepared to fork or swap to laravel-lang/barryvdh/laravel-translation-manager style alternatives.

Version mismatch in generated format. Older Laravel versions use resources/lang/, newer use lang/. Confirm where the tool writes; if it hardcodes the old path on a modern app, translations won't load at all.