README

This package lets you share your local translations via API, so that any app can use them. To do so, it converts your PHP lang files to JSON.

Requirements

1. You must provide your lang files within folders, such as lang/en or lang/de.
2. The lang files must be in PHP format, such as lang/en/validation.php.
3. Must secure the API routes and its patterns on your own.

Installation

This package requires Laravel 9.33+. You can install the package via composer:

composer require empuxa/laravel-locale-via-api

Afterward, you might want to copy the vendor files:

php artisan vendor:publish --provider="Empuxa\LocaleViaApi\LocaleViaApiServiceProvider"

Remember to also update the config file config/locale-via-api.php to your needs!

Usage

This package provides two controllers to access your translations via API. You must add them to your routes/api.php file manually.

Empuxa\LocaleViaApi\Http\Controllers\ListLocalesController

With this controller, you can list any locale that is available in your app. For security reasons, it only returns the array from your config and doesn't read the actual files.

Route::get('/locales', ListLocalesController::class);

By adding ?flatten=true to the URL, you can get a flat array of all available locales. You can also change the default behavior in the config file.

Non-flattened response

{
    "data": {
        "api": {
            "error": {
                "401": "Unauthenticated.",
                "403": "Forbidden.",
                "404": "Not Found.",
                "422": "Unprocessable Entity."
            }
        }
    }
}

Flattened response

{
    "data": {
        "api.error.401": "Unauthenticated.",
        "api.error.403": "Forbidden.",
        "api.error.404": "Not Found.",
        "api.error.422": "Unprocessable Entity."
    }
}

Empuxa\LocaleViaApi\Http\Controllers\GetLocaleController

This controller returns the contents of a locale directory as JSON. If the directory does not exist, it will return an error 404.

Route::get('/locales/{locale}', GetLocaleController::class);

Security

Since this package reads your lang files (and could theoretically read any other files as well), it is important to protect your API routes. Make sure that you only share the locales that you want to share. Add route pattern to do so.

Security Best Practices

1. Protect your routes - Always use authentication middleware on the locale API routes:

   Route::middleware('auth:sanctum')->group(function () {
       Route::get('/locales', ListLocalesController::class);
       Route::get('/locales/{locale}', GetLocaleController::class);
   });

2. Restrict locale patterns - Use route constraints to limit valid locale values:

   Route::get('/locales/{locale}', GetLocaleController::class)
       ->where('locale', '[a-z]{2}');

3. Protect your lang directory - This package uses File::getRequire() which executes PHP code from locale files. Never allow untrusted users to write to your lang/ directory.

4. Use vendor safelist - If you enable load_vendor_files, consider using the vendor_safelist config option to restrict which vendor packages are exposed.

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Marco Raddatz
• All Contributors

License

The MIT License (MIT). Please see License File for more information.