Download the PHP package volcy/translator-flight without Composer

volcy/translator-flight

FlightPHP bridge for volcy/translator-core: compile-time template translation with zero runtime overhead.

Architecture

This library uses a compile-time translation architecture for maximum performance:

• Compile-Time Injection: Translations are embedded directly into compiled templates, eliminating runtime processing
• Locale-Specific Caching: Each locale maintains its own compiled template cache for instant rendering
• Instant Language Switching: Delivers fully translated HTML from the first byte
• Lightweight Middleware: Only handles locale resolution; all translation work happens during compilation
• Dynamic Content Support: Handles JavaScript framework content via custom data attributes

Requirements

• PHP 8.0+
• volcy/translator-core ^1.0
• flightphp/core ^3.0
• eftec/bladeone ^4.0

Installation

Install via Composer:

If you want to use the included CLI commands, also install flightphp/runway (recommended in require-dev):

Quick start

1. Install Dependencies

2. Configure Translation Settings

Add translator configuration to your Flight app config:

3. Register Translator Service

Create a service registration file:

4. Configure BladeOne View Service

Update your view service configuration to use TrackedBladeOne:

5. Attach Locale Middleware

Add the locale middleware to your routes:

6. Add Translatable Attributes to Templates

Use data-i18n attributes in your Blade templates:

The LocaleMiddleware is lightweight and only resolves the current locale. The actual translation happens during template compilation by TrackedBladeOne, which injects translations directly into the compiled PHP files for each locale.

CLI Workflow

1. Scan Views

Extract translatable strings from your Blade templates:

This creates a source locale index in your configured index_path.

2. Build Translations

Generate translations for target locales:

This creates French translations from your English source.

3. Compile Views (Precompilation)

Compile views for all locales to avoid runtime compilation:

This compiles your Blade templates with translations embedded for each locale.

Note: If you don't use the compile command, views will be compiled on first request for each locale.

4. Apply Translations

Translations are automatically applied via the locale middleware during web requests. The middleware sets the locale, and the appropriate compiled template is served.

Usage Examples

Static Content Translation

Attribute Translation

Dynamic Content (Alpine.js)

Locale Switching

Access different locales via URL parameter or session:

CLI Commands

The library provides three Runway commands:

translator:scan

Scans Blade views and creates the source locale index.

Options:

• --path: Path to views directory (default: from config)
• --exclude: Comma-separated folders to exclude

translator:build

Builds target locale indexes from the source locale.

Options:

• <locale>: Target locale (required)
• --source: Source locale (default: from config)

translator:compile

Pre-compiles views for a specific locale with translations embedded.

Arguments:

• <locale>: Target locale to compile (required)

Configuration

Additional configuration options for translation drivers:

API overview

• TranslatorBootstrap::register(Engine $app, array $config): TranslatorBootstrap — registers services and returns an instance.
• TranslatorBootstrap::blade(string $viewsPath, string $compilePath): TrackedBladeOne — convenience factory that wires the rendered-views registry and translation catalog.
• TranslatorBootstrap::middleware(): LocaleMiddleware — Flight middleware to attach to groups that should be translated.
• TrackedBladeOne::lockLocale(string $locale): void — locks the locale for CLI compilation, bypassing runtime locale resolution.

Dynamic Content Support

The library supports translation of dynamic JavaScript framework content through custom data-i18n-* attributes:

Alpine.js Example

Other Frameworks

This pattern works with any JavaScript framework that can access DOM attributes:

The scanner automatically extracts values from data-i18n-* attributes, and the compile-time injection replaces them with translated values, enabling performance translation for dynamic content.

ID Strategies

This package supports all ID strategies from translator-core:

• hash (default): Content-based SHA1 hashes
• tag_path: HTML tag path + attribute aware IDs
• explicit: Manual control via data-i18n attributes with hash fallback

For detailed information about ID strategies, see the translator-core documentation.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For issues and questions, please use the GitHub issue tracker.

For security issues, please see SECURITY.md.