PHPackages                             smartness/translation-client - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Localization & i18n](/categories/localization)
4. /
5. smartness/translation-client

ActiveLibrary[Localization & i18n](/categories/localization)

smartness/translation-client
============================

Laravel package to sync translations with SmartPMS Translation Manager

1.4.0(1mo ago)01.2k↑1000%MITPHPPHP ^8.1CI passing

Since Feb 3Pushed 1mo agoCompare

[ Source](https://github.com/smartpricing/php-translation-client)[ Packagist](https://packagist.org/packages/smartness/translation-client)[ RSS](/packages/smartness-translation-client/feed)WikiDiscussions main Synced today

READMEChangelogDependencies (18)Versions (17)Used By (0)

Smartness Translation Client
============================

[](#smartness-translation-client)

[![Latest Version on Packagist](https://camo.githubusercontent.com/3a49ea46cec6ba0cc3b44622e3b3f028465e19812de215e5c8a8c49896ba78d8/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f736d6172746e6573732f7472616e736c6174696f6e2d636c69656e742e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/smartness/translation-client)[![Total Downloads](https://camo.githubusercontent.com/dfc9bfff2d94ea6b816e016581cf17c0e3b0ec1003be423f77c4c4211c78d12e/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f736d6172746e6573732f7472616e736c6174696f6e2d636c69656e742e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/smartness/translation-client)

A Laravel package to synchronize translations between your Laravel application and a centralized translation management system. Pull translations from the server or push local translations back to keep everything in sync.

Features
--------

[](#features)

- 🚀 **One Command Install** - Get started in seconds
- 🔄 **Bi-directional Sync** - Pull and push translations with simple commands
- 🌍 **Multi-language** - Support for all languages
- 📦 **Laravel Compliant** - Generates proper Laravel translation files with nested arrays
- ⚡ **CI/CD Ready** - Perfect for automated deployments
- 🔒 **Secure** - API token authentication
- 🎯 **Smart Filtering** - Filter by language, status, or specific files
- ⬆️ **Push Support** - Send local translations back to the server
- 🔎 **Source-Code Sync** - `translations:missing` and `translations:cleanup` reconcile the catalog with the actual `$t()` / `trans()` / `__()` / `@lang` usage in your code
- 🏠 **Centralized Scan Config** - Scan settings live on the project so every developer uses the same patterns (local `.env` still wins)

Requirements
------------

[](#requirements)

- PHP 8.1 or higher
- Laravel 10, 11, 12, or 13

Installation
------------

[](#installation)

Install via Composer:

```
composer require smartness/translation-client
```

The package will automatically register itself via Laravel's package auto-discovery.

Configuration
-------------

[](#configuration)

### Step 1: Publish Configuration (Optional)

[](#step-1-publish-configuration-optional)

```
php artisan vendor:publish --tag=translation-client-config
```

This creates a `config/translation-client.php` file where you can customize settings.

### Step 2: Configure Environment Variables

[](#step-2-configure-environment-variables)

Add these variables to your `.env` file:

```
# Required: Your API token
TRANSLATION_API_TOKEN=your_api_token_here

# Required: API endpoint URL
TRANSLATION_API_URL=https://your-translation-service.com/api

# Optional: Override default settings
TRANSLATION_OUTPUT_DIR=  # Default: lang_path()
TRANSLATION_FORMAT=php   # Options: php, json, raw
TRANSLATION_STATUS=approved  # Filter: approved, pending, rejected
TRANSLATION_TIMEOUT=30   # HTTP timeout in seconds

# Optional: Source-scanning overrides (used by translations:cleanup and translations:missing).
# These are fetched from the server's project config by default, so most teams
# don't need to set them. Local values always override the server config.
SMARTPMS_TRANSLATION_SCAN_DIRS="resources,app"
SMARTPMS_TRANSLATION_SCAN_EXTENSIONS="php,blade.php,ts,tsx,js,jsx,vue"
SMARTPMS_TRANSLATION_KEY_PATTERN=
SMARTPMS_TRANSLATION_PREFIX_PATTERN=
```

**Note:** You'll receive your API token and endpoint URL from your translation service administrator.

Usage
-----

[](#usage)

### Pulling Translations (Download)

[](#pulling-translations-download)

Pull all translations from the server:

```
php artisan translations:pull
```

Pull translations for a specific language:

```
php artisan translations:pull --language=en
```

Preview changes without saving (dry-run):

```
php artisan translations:pull --dry-run
```

Test API connection:

```
php artisan translations:pull --test
```

#### Advanced Pull Options

[](#advanced-pull-options)

```
# Override format for this pull
php artisan translations:pull --format=json

# Override status filter
php artisan translations:pull --status=approved

# Combine multiple options
php artisan translations:pull --language=de --status=approved --dry-run
```

### Pushing Translations (Upload)

[](#pushing-translations-upload)

Push all local translations to the server:

```
php artisan translations:push
```

Push translations for a specific language:

```
php artisan translations:push --language=en
```

Push a specific translation file:

```
php artisan translations:push --language=en --file=messages
```

Preview without actually pushing:

```
php artisan translations:push --dry-run
```

Overwrite existing translations on the server:

```
php artisan translations:push --overwrite
```

Use a custom translation directory:

```
php artisan translations:push --dir=/path/to/translations
```

#### Advanced Push Options

[](#advanced-push-options)

```
# Combine multiple options
php artisan translations:push --language=en --file=auth --overwrite

# Preview what will be pushed
php artisan translations:push --dry-run --language=de
```

### Reconciling the Catalog with Source Code

[](#reconciling-the-catalog-with-source-code)

These two commands scan your local source for `$t('…')`, `useTranslate('…')`, `i18n.t('…')`, `trans('…')`, `__('…')` and `@lang('…')` calls and reconcile what they find with what the server stores.

Both commands first fetch the project's central scan configuration from `GET /translation-projects/config`. Local config (`config/translation-client.php` or `SMARTPMS_TRANSLATION_*` env vars) always wins; the server values are a shared default; package defaults are used if neither is set. The resolved config is printed at the start of each run so you can verify which source provided each value.

#### `translations:missing` — Find Keys Used in Code but Absent Remotely

[](#translationsmissing--find-keys-used-in-code-but-absent-remotely)

```
# Dry-run: report keys referenced in source that don't exist on the server.
php artisan translations:missing

# Create those keys as placeholder rows on the project's primary language
# (value=null, missing=true, is_new=true), so they show up in the New Keys UI.
php artisan translations:missing --insert
```

Sample output:

```
Scan configuration:
  scan_dirs        (server ) resources, app
  scan_extensions  (server ) php, blade.php, ts, tsx, vue
  key_pattern      (default) (?:^|[^\w$])(?:\$?t|useTranslat(?:e|ion)|i18n…
  prefix_pattern   (default) (?:^|[^\w$])(?:\$?t|useTranslat(?:e|ion)|i18n…

Scanned 412 files.
Found 837 unique used key(s).
Remote keys: 540
Used keys sent: 837
Missing keys: 12
  - dashboard.banner.welcome
  - dashboard.banner.dismiss
  …

```

#### `translations:cleanup` — Find Keys Stored Remotely but Unused in Code

[](#translationscleanup--find-keys-stored-remotely-but-unused-in-code)

```
# Dry-run: report stale keys.
php artisan translations:cleanup

# Actually delete them from the remote project.
php artisan translations:cleanup --delete
```

Dynamic keys built with template literals (e.g. `$t(`amenities.${name}`)`) contribute a static prefix that protects every matching remote key from deletion — no false positives when the key set is computed at runtime.

Output Structure
----------------

[](#output-structure)

The package creates translation files following Laravel's standard structure:

```
lang/
├── en/
│   ├── messages.php
│   ├── validation.php
│   └── auth.php
├── de/
│   ├── messages.php
│   ├── validation.php
│   └── auth.php
└── es/
    ├── messages.php
    ├── validation.php
    └── auth.php

```

### Example Generated File

[](#example-generated-file)

```