README

A Laravel package for syncing translations between your application and the Translation Manager — translation.metasync.site. Translators work in the UI there, this package moves the result in and out of your lang/ directory. No hosting required to try it.

Requirements

PHP 8.2+
Laravel 11, 12, or 13

Installation

composer require metasyncsite/laravel-translations-client

Publish the config file:

php artisan vendor:publish --tag=translations-client-config

Configuration

Add the following to your .env file:

TRANSLATIONS_URL=https://translations.yourapp.com
TRANSLATIONS_TOKEN=your-api-token

The API token is generated in Translation Manager under API Tokens. Each token is scoped to a project — all pushes go to that project.

Full config reference (config/translations-client.php):

return [
    'url'          => env('TRANSLATIONS_URL'),
    'token'        => env('TRANSLATIONS_TOKEN'),

    // Defaults to Laravel's lang_path(). Override if your lang files live elsewhere.
    'lang_path'    => null,

    // File names to exclude from push (without locale prefix).
    // e.g. ['validation.php', 'passwords.php']
    'exclude_files' => [],

    // Whether to overwrite existing translations on push.
    'overwrite'    => true,
];

Usage

Push translations

Reads your local lang/ directory and uploads translations to Translation Manager.

# Push all locales
php artisan translations:push

# Push a single locale
php artisan translations:push --locale=en

# Force-overwrite existing translations
php artisan translations:push --overwrite

# Preview what would be sent (no HTTP request)
php artisan translations:push --dry-run

Pull translations

Downloads translations from Translation Manager and writes them into your lang/ directory.

# Pull all locales
php artisan translations:pull

# Pull a single locale
php artisan translations:pull --locale=fr

# Write as JSON files instead of PHP arrays
php artisan translations:pull --format=json

# Preview what would be written (no files touched)
php artisan translations:pull --dry-run

translations:pull exits non-zero if any locale could not be fetched or written, so a deploy step that runs it will stop instead of shipping a half-updated lang/ directory. Locales that did succeed are still written.

Files are written through a temporary file and renamed into place. A pull that is interrupted therefore leaves the previous file intact rather than a half-written one — a truncated lang file is PHP source, and the application would fatal on it.

Locale codes and group names arrive in the API response and become path segments, so they are validated before use: anything containing a path separator, or equal to . or .., is refused rather than written outside your lang directory.

How it works

Push reads all PHP translation files (lang/{locale}/*.php) and JSON files (lang/{locale}.json), flattens nested keys to dot-notation, then posts them to the Translation Manager API.

Pull fetches all translations from Translation Manager and writes them back as PHP arrays (default) or JSON files into your lang/ directory.

Generated PHP files are source code, so keys and values are escaped for a single-quoted PHP literal: only \ and ' are escaped. Text containing double quotes — HTML markup, for instance — is written verbatim.

Testing

composer install
composer test

License

MIT

metasyncsite / laravel-translations-client

Package info

Security

Statistics