jrmajor/laravel-fluent

Fluent translations for Laravel

v1.1.1 2024-11-22 20:25 UTC

Requires

• php: 8.2 - 8.4
• jrmajor/fluent: ^1.0
• laravel/framework: ^11.0

Requires (Dev)

• jrmajor/cs: ^0.6.1
• orchestra/testbench: ^9.1
• phpstan/phpstan: ^2.0
• phpunit/phpunit: ^11.4

MIT

• Jeremiasz Major

• i18n
• translation
• locale
• language
• l10n
• translator
• localization
• internationalization
• plural
• mozilla
• gender
• ftl

README

Unleash the expressive power of the natural language in your Laravel application with Project Fluent, a localization system designed by Mozilla.

Read the Fluent Syntax Guide or try it out in the Fluent Playground to learn more about the syntax.

shared-photos =
    { $userName } { $photoCount ->
        [one] added a new photo
       *[other] added { $photoCount } new photos
    } to { $userGender ->
        [male] his stream
        [female] her stream
       *[other] their stream
    }.

__('stream.shared-photos', [
    'userName' => 'jrmajor',
    'photoCount' => 2,
    'userGender' => 'male',
]); // jrmajor added 2 new photos to his stream.

This package is a Laravel wrapper around jrmajor/fluent-php.

You may install it via Composer: composer require jrmajor/laravel-fluent. The package will automatically register itself.

Usage

This package replaces default Laravel translator with Major\Fluent\Laravel\FluentTranslator.

app('translator') instanceof Major\Fluent\Laravel\FluentTranslator; // true

Fluent translations are stored in .ftl files. Place them among your .php translation files in your Laravel app:

/resources
  /lang
    /en
      menu.ftl
      validation.php
    /pl
      menu.ftl
      validation.php

If there is no Fluent message for a given key, translator will fall back to a .php file, which allows you to introduce Fluent translation format progressively.

Laravel validator uses custom logic for replacing the :attribute variable and requires deeply nested keys, which are not supported in Fluent, so you should leave validation.php file in the default Laravel format.

The trans_choice() helper always falls back to the default translator, as the Fluent format eliminates the need for this function.

You may use the FluentTranslator::addFunction() method to register Fluent functions.

Configuration

Optionally, you can publish the configuration file with this command:

php artisan vendor:publish --tag fluent-config

This will publish the following file in config/fluent.php:

return [

    /*
     * In strict mode, exceptions will be thrown for syntax errors
     * in .ftl files, unknown variables in messages etc.
     * It's recommended to enable this setting in development
     * to make it easy to spot mistakes.
     */
    'strict' => env('APP_ENV', 'production') !== 'production',

    /*
     * Determines if it should use Unicode isolation marks (FSI, PDI)
     * for bidirectional interpolations. You may want to enable this
     * behaviour if your application uses right-to-left script.
     */
    'use_isolating' => false,

];

Testing

vendor/bin/phpunit           # Tests
vendor/bin/phpstan analyze   # Static analysis
vendor/bin/php-cs-fixer fix  # Formatting