README

Manage translations in Laravel across PHP files, JSON files, CSV files, and database.

Requirements

Laravel	PHP
12.x	8.2, 8.3, 8.4
11.x	8.2, 8.3, 8.4

Supported Formats

Format	Constant	Description
php_file	`TranslationOptions::PHP`	Standard Laravel PHP translation files
json_file	`TranslationOptions::JSON`	JSON translation files
csv_file	`TranslationOptions::CSV`	CSV translation files
db	`TranslationOptions::DB`	Database-backed translations

Installation

composer require brunoscode/laravel-translation-handler

Publish the configuration file:

php artisan vendor:publish --provider="BrunosCode\TranslationHandler\TranslationHandlerServiceProvider"

Quick Start

# Import translations from PHP to JSON
php artisan translation-handler:import --from=php_file --to=json_file

# Export translations from JSON to PHP, overwriting existing
php artisan translation-handler:export --from=json_file --to=php_file --force

# Move translations interactively
php artisan translation-handler php_file json_file --guided

# Get a specific translation
php artisan translation-handler:get php_file test.welcome en

# Set a specific translation
php artisan translation-handler:set php_file test.welcome en "Welcome!"

Or use the Facade:

use BrunosCode\TranslationHandler\Facades\TranslationHandler;
use BrunosCode\TranslationHandler\Data\TranslationOptions;

// Import PHP → JSON
TranslationHandler::import(TranslationOptions::PHP, TranslationOptions::JSON);

// Export JSON → PHP, overwriting existing
TranslationHandler::export(TranslationOptions::JSON, TranslationOptions::PHP, force: true);

Commands

Shared Options

These options are available on translation-handler, translation-handler:import, and translation-handler:export:

Option	Type	Default	Description
`--force`	bool	`false`	Overwrite existing translations
`--fresh`	bool	`false`	Delete existing translations before writing
`--file-names`	array	config `fileNames`	Translation file names to process
`--locales`	array	config `locales`	Locales to process
`--from-path`	string	format default	Custom source path
`--to-path`	string	format default	Custom destination path
`--guided`	bool	`false`	Interactive mode, prompts for each option

`translation-handler`

Move translations from one format to another. Source and destination are positional arguments.

php artisan translation-handler {from?} {to?} [options]

If from or to are omitted, you will be prompted to choose.

`translation-handler:import`

Import translations. Source and destination are passed via --from and --to options, defaulting to config values (defaultImportFrom, defaultImportTo).

php artisan translation-handler:import [options]

`translation-handler:export`

Export translations. Source and destination are passed via --from and --to options, defaulting to config values (defaultExportFrom, defaultExportTo).

php artisan translation-handler:export [options]

`translation-handler:get`

Get a single translation value.

php artisan translation-handler:get {from?} {key?} {locale?} {--from-path=}

`translation-handler:set`

Set a single translation value.

php artisan translation-handler:set {to?} {key?} {locale?} {value?} {--to-path=} {--force}

Facade API

use BrunosCode\TranslationHandler\Facades\TranslationHandler;

import / export

Both methods share the same signature:

TranslationHandler::import(
    from: ?string,     // source format (default: config value)
    to: ?string,       // destination format (default: config value)
    force: bool,       // overwrite existing (default: false)
    fromPath: ?string, // custom source path (default: null)
    toPath: ?string,   // custom destination path (default: null)
): bool;

TranslationHandler::export(/* same signature */): bool;

get

$translations = TranslationHandler::get(
    from: string,      // source format
    path: ?string,     // custom path (default: null)
): TranslationCollection;

set

$count = TranslationHandler::set(
    translations: TranslationCollection,
    to: string,        // destination format
    path: ?string,     // custom path (default: null)
    force: bool,       // overwrite existing (default: false)
): int;

Example:

use BrunosCode\TranslationHandler\Collections\TranslationCollection;
use BrunosCode\TranslationHandler\Data\Translation;
use BrunosCode\TranslationHandler\Data\TranslationOptions;

$translation = new Translation('welcome', 'en', 'Welcome!');
$collection = new TranslationCollection([$translation]);

TranslationHandler::set($collection, TranslationOptions::JSON);

delete

$count = TranslationHandler::delete(
    from: string,      // format to delete from
    path: ?string,     // custom path (default: null)
): int;

Options Management

// Get/set individual options
TranslationHandler::setOption('keyDelimiter', '_');
$value = TranslationHandler::getOption('keyDelimiter');

// Replace all options
TranslationHandler::setOptions(new TranslationOptions([...]));

// Reset to defaults
TranslationHandler::resetOptions();

Configuration

The config/translation-handler.php file contains:

General

Option	Default	Description
`keyDelimiter`	`.`	Delimiter used in translation keys
`fileNames`	`['translation-handler']`	Translation file names to process
`locales`	`['en']`	Supported locales

Default Formats

Option	Default	Description
`defaultImportFrom`	`php_file`	Default source format for import
`defaultImportTo`	`json_file`	Default destination format for import
`defaultExportFrom`	`json_file`	Default source format for export
`defaultExportTo`	`php_file`	Default destination format for export

PHP

Option	Default	Description
`phpPath`	`lang_path()`	Path to PHP translation files
`phpFormat`	`false`	Format PHP output
`phpHandlerClass`	`PhpFileHandler::class`	Handler class

JSON

Option	Default	Description
`jsonPath`	`lang_path()`	Path to JSON translation files
`jsonFileName`	`''`	File name (empty = use locale as filename, set = use locale as folder)
`jsonNested`	`false`	Nest output like PHP files
`jsonFormat`	`true`	Pretty-print JSON output
`jsonHandlerClass`	`JsonFileHandler::class`	Handler class

CSV

Option	Default	Description
`csvPath`	`storage_path('lang')`	Path to CSV files
`csvFileName`	`translations`	CSV file name
`csvDelimiter`	`;`	CSV delimiter (must differ from `keyDelimiter`)
`csvHandlerClass`	`CsvFileHandler::class`	Handler class

Database

Option	Default	Description
`dbHandlerClass`	`DatabaseHandler::class`	Handler class

Contributing

Contributions are welcome! Please submit a pull request or open an issue to discuss what you would like to change.

License

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

brunoscode / laravel-translation-handler

Maintainers

Package info

Fund package maintenance!

Statistics

Security