Weave Code
Laravel Gettext Laravel Package
zerospam/laravel-gettext
Gettext-based localization for Laravel: load PO/MO translation catalogs, translate strings with plural forms and contexts, switch locales at runtime, and use translations in Blade views. A practical alternative to Laravel’s default PHP/JSON language files.
Adds localization support to laravel applications using PoEdit and GNU-Gettext.
Frequently asked questions about Laravel Gettext
- How do I install and configure zerospam/laravel-gettext in a Laravel app?
- Install it with composer require zerospam/laravel-gettext, then publish the package config and point it at your locale directories where the compiled .mo catalogs live. You must also have PHP's ext-gettext enabled and the target system locales generated on the host, since gettext will not read a catalog for a locale the OS does not know. Add an explicit mapping table between Laravel locale codes like pt-BR and gettext codes like pt_BR.UTF-8 instead of doing string munging at runtime.
- Does laravel-gettext support Laravel 10, 11, or 12?
- Support depends entirely on the composer.json constraint of the latest release, and with roughly a hundred stars the package has a thin maintenance margin, so Laravel major-version support will likely lag behind core releases. Check the constraint and the date of the last release before committing to it. This is the single most common reason an evaluation of this package ends early.
- What is the difference between gettext and Laravel's default PHP and JSON language files?
- Laravel's native translator is key-based, while gettext is msgid-based, meaning the source string itself, usually English, is the lookup key. That buys translator-friendly ergonomics: per-locale plural rules, msgctxt disambiguation, fuzzy matching, translation memory, and compatibility with essentially every CAT tool and TMS on the market. The cost is that your code is coupled to copy, so editing an English string orphans every existing translation of it.
- How do I use gettext translations inside Blade views?
- The package exposes gettext, ngettext, and dgettext style lookups through a Laravel facade, so you can call them from Blade templates or from small helper functions you wrap around them. There is no drop-in replacement for the @lang directive, so most teams add a Blade helper or component that maps to the gettext call they want. Keep domain selection explicit so views do not need to know which catalog a string belongs to.
- Is laravel-gettext safe with Laravel Octane, Swoole, or RoadRunner?
- Not out of the box. setlocale, putenv, and textdomain are process-global, not per-request, which is fine under classic PHP-FPM where one process handles one request at a time but unsafe under long-lived workers. A worker that served a French request can leak that locale into a later German request. If Octane is on your roadmap, treat this as a design constraint requiring a per-request locale guard, or reject the package.
- Why are my translations still showing in English after installing laravel-gettext?
- Gettext fails silently: if the locale is missing from the host, the extension returns the msgid and your app renders English with no error and no log line. Run locale -a and confirm entries like fr_FR.UTF-8 actually exist, not just fr_FR. Then verify the .mo file is present and compiled, that the domain and directory paths match your config, and that your Laravel-to-gettext locale mapping is correct. A startup health check plus a monitoring assertion prevents this from failing open in production.
- How do I compile .po files to .mo for a Laravel deployment?
- Keep the .po sources in version control, edit them in PoEdit or any CAT tool, and run msgfmt as a build or CI step to produce the binary .mo files that gettext actually loads. Deploy the compiled .mo catalogs to your configured locale directories. When source strings change, use msgmerge plus a fuzzy review pass in PoEdit rather than hand-editing, otherwise you silently invalidate existing translations.
- Does laravel-gettext handle plural forms and string contexts?
- Yes. Plural handling goes through ngettext, which uses the plural rules declared in each catalog's .po header, so locales with complex plural families like Russian, Arabic, or Polish resolve correctly rather than falling back to a naive one-or-many rule. Contexts are handled with msgctxt, letting you disambiguate identical source strings that mean different things. This plural correctness is a genuine gettext strength and a good reason to quantify how many locales you actually need.
- How do I switch locale at runtime per user or per request?
- The package lets you set the active locale and text domain at runtime, which suits user-selectable languages and multi-tenant apps under PHP-FPM. Remember the change is process-global, so it only stays contained when each request gets its own process. Always route the switch through an explicit Laravel-to-gettext locale config table and set only LC_MESSAGES, since setlocale with LC_ALL also alters strcoll, strftime, and printf decimal separators.
- What are the alternatives to zerospam/laravel-gettext and is it still maintained?
- Alternatives include Laravel's built-in PHP and JSON translator, third-party file-based loaders, or a full translation management system. The package itself is a thin service provider over ext-gettext with a small user base, so expect maintenance to be slow and pin your composer constraint accordingly. Choose it when an external agency or TMS owns translations and .po is already your source of truth, not when developers translate strings ad hoc in a small app.
Weaver
How can I help you explore Laravel packages today?