Ashampoo ATS Client

Laravel client for the Ashampoo Translation Studio (ATS) API.

Wraps the ATS HTTP endpoints in a typed, testable client with declarative endpoint definitions, query-parameter validation, and wrapped exceptions.

• PHP: ^8.3
• Laravel: ^12.0 || ^13.0

Installation

The package is auto-discovered once it's in the packages/ tree and declared in the root composer.json repositories/require sections:

composer require ashampoo/ats-client

Publish the config (optional — the package ships with sensible defaults):

php artisan vendor:publish --tag=ats-config

Configuration

Set in .env:

ATS_BASEURL=https://translationstudio.ashampoo.com
ATS_TOKEN=your-bearer-token
ATS_PROJECT_ID=your-product-id
ATS_TIMEOUT=30

ATS_BASEURL, ATS_TOKEN, and ATS_PROJECT_ID are required when resolving the client from the container; the service provider throws InvalidArgumentException early with a clear message if one is missing. ATS_TIMEOUT is optional and defaults to 30 seconds.

Usage

The public API consists of typed methods, one per endpoint. Each method returns Laravel's Illuminate\Http\Client\Response.

Via dependency injection

use Ashampoo\AtsClient\Contracts\AtsClientInterface;

class ExportController
{
    public function __construct(private AtsClientInterface $ats) {}

    public function __invoke()
    {
        $response = $this->ats->getTranslations(language: 'de');

        return $response->json();
    }
}

Via facade

use Ashampoo\AtsClient\Facades\Ats;

$response = Ats::getLangInfo('de');

GET — fetching translations

Ats::getTranslations(
    language: 'de',
    filter: 'untranslated',
    formatId: 'xliff',
    contextSplitting: true,
);

Ats::getAllTranslations(filter: 'untranslated');

POST — JSON import

use Ashampoo\AtsClient\Requests\TranslationImportRequest;

Ats::importTranslations(new TranslationImportRequest(
    language: 'de',
    importIds: true,
    importTranslations: true,
    overWriteTranslations: false,
    body: [
        'id-1' => 'Hallo Welt',
        'id-2' => 'Guten Tag',
    ],
));

Machine translation / Translation memory

Ats::generateMachineTranslation('de');
Ats::generateAllMachineTranslations();
Ats::generateMemoryTranslation('de');
Ats::generateAllMemoryTranslations();

Endpoints

Defined in AtsEndpoint:

Case	Method	Path
Translations	GET	/api/project/{projectId}/translations
TranslationsAll	GET	/api/project/{projectId}/translations/all
LangInfo	GET	/api/project/{projectId}/language/info
TranslationImport	POST	/api/project/{projectId}/import
MachineTranslation	POST	/api/machinetranslations/{projectId}/generate
MachineTranslationAll	POST	/api/machinetranslations/{projectId}/generate/all
MemoryTranslation	POST	/api/translationmemory/{projectId}/generate
MemoryTranslationAll	POST	/api/translationmemory/{projectId}/generate/all

Each case also declares its allowed query parameters via AtsEndpoint::queryParams(). Required parameters are enforced by the client before any HTTP call is made.

Exceptions

All exceptions extend the abstract AtsException and live in Ashampoo\AtsClient\Exceptions\:

Exception	When
MissingQueryParamException	Required query parameter not provided before the HTTP call.
MissingBodyException	Endpoint requires a JSON body but none was supplied.
UnresolvedPathPlaceholderException	A {placeholder} in the endpoint path was never substituted.
AtsRequestException	Server returned 4xx/5xx. getResponse(): Response exposes it.

Typical handling:

use Ashampoo\AtsClient\Exceptions\AtsRequestException;
use Ashampoo\AtsClient\Exceptions\MissingQueryParamException;

try {
    $response = Ats::getTranslations('de');
} catch (MissingQueryParamException $e) {
    // caller bug — log, surface to user
} catch (AtsRequestException $e) {
    $status = $e->getResponse()->status();
    $body   = $e->getResponse()->json();
    // decide: retry, surface, escalate
}

Development

composer install       # dependencies
composer test          # PHPUnit
composer analyse       # PHPStan (Larastan), level 8
composer check         # analyse + test

Tests use Http::fake() throughout — no network calls.

License

Proprietary. See LICENSE.