PHPackages                             tobento/app-machine-translator - 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. tobento/app-machine-translator

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

tobento/app-machine-translator
==============================

Machine translation integration with optional UI support for applications.

2.0.1(2mo ago)031MITPHPPHP >=8.4

Since Apr 1Pushed 2mo agoCompare

[ Source](https://github.com/tobento-ch/app-machine-translator)[ Packagist](https://packagist.org/packages/tobento/app-machine-translator)[ Docs](https://www.tobento.ch)[ RSS](/packages/tobento-app-machine-translator/feed)WikiDiscussions 2.x Synced 4w ago

READMEChangelog (2)Dependencies (32)Versions (3)Used By (1)

App Machine Translator
======================

[](#app-machine-translator)

Application-level integration for machine translation, built on top of the [Machine Translator Service](https://github.com/tobento-ch/service-machine-translator).

Table of Contents
-----------------

[](#table-of-contents)

- [Getting Started](#getting-started)
    - [Requirements](#requirements)
- [Documentation](#documentation)
    - [App](#app)
    - [Machine Translator Boot](#machine-translator-boot)
        - [Machine Translator Config](#machine-translator-config)
    - [Basic Usage](#basic-usage)
    - [Features](#features)
        - [Translate Feature](#translate-feature)
    - [JavaScript Translator](#javascript-translator)
    - [Learn More](#learn-more)
        - [Events For Translators](#events-for-translators)
- [Credits](#credits)

---

Getting Started
===============

[](#getting-started)

Add the latest version of the app machine-translator project running this command.

```
composer require tobento/app-machine-translator

```

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

[](#requirements)

- PHP 8.4 or greater

Documentation
=============

[](#documentation)

App
---

[](#app)

Check out the [**App Skeleton**](https://github.com/tobento-ch/app-skeleton) if you are using the skeleton.

You may also check out the [**App**](https://github.com/tobento-ch/app) to learn more about the app in general.

Machine Translator Boot
-----------------------

[](#machine-translator-boot)

The `MachineTranslator` boot integrates the Tobento [Machine Translator Service](https://github.com/tobento-ch/service-machine-translator) into your application.

It provides:

- loading of the `machine-translator.php` configuration
- binding of all service-machine-translator interfaces
- installing the machine-translator migration
- registering configured translation features
- setting up lazy machine translators and the default translator

```
use Tobento\App\AppFactory;
use Tobento\Service\MachineTranslator\MachineTranslatorInterface;
use Tobento\Service\MachineTranslator\MachineTranslatorsInterface;

// Create the app
$app = new AppFactory()->createApp();

// Add directories:
$app->dirs()
    ->dir(realpath(__DIR__.'/../'), 'root')
    ->dir(realpath(__DIR__.'/../app/'), 'app')
    ->dir($app->dir('app').'config', 'config', group: 'config')
    ->dir($app->dir('root').'public', 'public')
    ->dir($app->dir('root').'vendor', 'vendor');

// Booting:
$app->boot(\Tobento\App\MachineTranslator\Boot\MachineTranslator::class);
$app->booting();

// Implemented interfaces
$machineTranslator = $app->get(MachineTranslatorInterface::class);
$machineTranslators = $app->get(MachineTranslatorsInterface::class);

// Run the app
$app->run();
```

### Machine Translator Config

[](#machine-translator-config)

The configuration for the machine translator is located in the `app/config/machine-translator.php` file at the default [**App Skeleton**](https://github.com/tobento-ch/app-skeleton) config location.

Here you can define the [Machine Translators](https://github.com/tobento-ch/service-machine-translator#translator) available to your application, as well as enable optional [Translation Features](#features).

### Basic Usage

[](#basic-usage)

If you're new to working with machine translators in Tobento, start with the
[Basic Usage section of the Machine Translator Service](https://github.com/tobento-ch/service-machine-translator#basic-usage).
It explains how to create and use translators, how translation results are structured, and provides the foundation for how App-Machine-Translator builds on top of the underlying service.

Features
--------

[](#features)

### Translate Feature

[](#translate-feature)

The **Translate** feature provides an HTTP endpoint for performing machine translations directly from your application.
It is designed for any workflow that requires on-demand machine translation through a simple HTTP API, such as backend services, admin tools, automation scripts, or JavaScript integrations.

This feature offers:

- a POST `/machine-translate` endpoint (optionally localized per locale)
- support for translating **one** or **many** texts in a single request
- automatic validation of input fields
- automatic selection of the default translator if none is specified
- ACL-protected access (`machine-translate` permission)
- structured JSON responses for both success and error cases
- logging of translation failures via the `LoggerTrait`
- optional route localization using the `RouteLocalizerInterface`

The feature installs an extended migration to support translation logging and tracking.

#### Config

[](#config)

Enable the feature in your [machine-translator.php config](#machine-translator-config):

```
'features' => [
    new \Tobento\App\MachineTranslator\Feature\Translate(
        withAcl: false, // WARNING: Disables permission checks. Only use in development.
        localizeRoute: true, // Localize the route per locale
    ),
],
```

Warning

**Security Warning:**
Disabling ACL (`withAcl: false`) removes all permission checks for the translation endpoint.
This should only be used during development or in trusted internal environments.

**ACL Permissions**

This feature defines the following ACL permission:

- `machine-translate` - User can perform machine translations.

If you are using the [App Backend](https://github.com/tobento-ch/app-backend), you can assign these permissions to roles or users in the backend interface.

#### Request Format

[](#request-format)

You may send either:

- a single text:
    `text: string`

or

- multiple texts:
    `texts: array`

Additional fields:

- `locale` - the target locale (required)
- `translator` - the translator name (optional; defaults to the first configured translator)

#### Example Request (single)

[](#example-request-single)

```
POST /machine-translate
{
    "text": "Hello world",
    "locale": "de"
}
```

Example Success Response

```
{
    "translated": "Hallo Welt",
    "locale": "de",
    "text": "Hello world"
}
```

#### Example Request (many)

[](#example-request-many)

```
POST /machine-translate
{
    "texts": {
        "title": "Hello",
        "body": "How are you?"
    },
    "locale": "fr"
}
```

Example Success Response

```
{
    "translated": {
        "title": "Bonjour",
        "body": "Comment allez-vous?"
    },
    "locale": "fr",
    "texts": {
        "title": "Hello",
        "body": "How are you?"
    }
}
```

For programmatic usage from JavaScript (e.g., admin tools, automation, UI helpers), see the [JavaScript Translator](#javascript-translator).

#### Logging

[](#logging)

The [App Logging Boot](https://github.com/tobento-ch/app-logging#logging-boot) is enabled by default, so no additional setup is required to log machine translation activity.

In the `app/config/logging.php` file you may define the logger to be used, otherwise the default logger will be used:

```
'aliases' => [
    // Log translation failures using the "daily" logger:
    \Tobento\App\MachineTranslator\Feature\Translate::class => 'daily',

    // Or disable logging entirely:
    \Tobento\App\MachineTranslator\Feature\Translate::class => 'null',
],
```

JavaScript Translator
---------------------

[](#javascript-translator)

The **JavaScript Translator** provides a lightweight client for performing machine translations from JavaScript.
It is intended for use in admin interfaces, tooling, automation, or any environment where translations need to be requested from the browser or another JS runtime.

This module communicates with the [Translate Feature](#translate-feature) endpoint and offers a simple API for translating one or many texts.

### Example

[](#example)

The following example demonstrates how to use the JavaScript Translator together with [App View](https://github.com/tobento-ch/app-view).
Make sure App View is installed and its boot is enabled before using this example.

```
$app->boot(\Tobento\App\View\Boot\View::class);
$app->boot(\Tobento\App\View\Boot\Form::class);
```

This setup allows you to attach translation behavior to any element using `data-machine-translator` attributes.
When clicked, the element triggers a request to the [Translate Feature](#translate-feature) endpoint and writes the translated text into the target field.

**Example View**

```