PHPackages                             tobento/app-translation - 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-translation

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

tobento/app-translation
=======================

App translation support.

2.0(9mo ago)0105↓86.7%16MITPHPPHP >=8.4

Since Jun 18Pushed 9mo ago1 watchersCompare

[ Source](https://github.com/tobento-ch/app-translation)[ Packagist](https://packagist.org/packages/tobento/app-translation)[ Docs](https://www.tobento.ch)[ RSS](/packages/tobento-app-translation/feed)WikiDiscussions 2.x Synced today

READMEChangelog (4)Dependencies (7)Versions (6)Used By (16)

App Translation
===============

[](#app-translation)

Translation support for the app.

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

[](#table-of-contents)

- [Getting Started](#getting-started)
    - [Requirements](#requirements)
- [Documentation](#documentation)
    - [App](#app)
    - [Translation Boot](#translation-boot)
        - [Translate Message](#translate-message)
        - [Configure Translator](#configure-translator)
        - [Migrate Translations](#migrate-translations)
        - [Add Translations](#add-translations)
        - [Customize Translations](#customize-translations)
- [Credits](#credits)

---

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

[](#getting-started)

Add the latest version of the app translation project running this command.

```
composer require tobento/app-translation

```

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.

Translation Boot
----------------

[](#translation-boot)

The translation boot does the following:

- implements [TranslatorInterface](https://github.com/tobento-ch/service-translation#create-translator)
- adds `trans` app macro

```
use Tobento\App\AppFactory;

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

// Add directories:
$app->dirs()->dir(realpath(__DIR__.'/../app/'), 'app');

// You might add trans directory:
$app->dirs()
    ->dir($app->dir('app').'trans', 'trans', group: 'trans', priority: 100);
// if not set, the same dir is specified by the boot as default!

// Adding boots
$app->boot(\Tobento\App\Translation\Boot\Translation::class);

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

By default, [Files Resources](https://github.com/tobento-ch/service-translation#files-resources) are used for the translator.

### Translate Message

[](#translate-message)

You can translate messages in several ways:

**Using the app**

```
use Tobento\App\AppFactory;
use Tobento\Service\Translation\TranslatorInterface;

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

// Add directories:
$app->dirs()->dir(realpath(__DIR__.'/../app/'), 'app');

// Adding boots
$app->boot(\Tobento\App\Translation\Boot\Translation::class);
$app->booting();

$translator = $app->get(TranslatorInterface::class);

$translated = $translator->trans(
    message: 'Hi :name',
    parameters: [':name' => 'John'],
    locale: 'de'
);

// or using the app macro:
$translated = $app->trans(
    message: 'Hi :name',
    parameters: [':name' => 'John'],
    locale: 'de'
);

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

**Using autowiring**

You can also request the `TranslatorInterface::class` in any class resolved by the app.

```
use Tobento\Service\Translation\TranslatorInterface;

class SomeService
{
    public function __construct(
        protected TranslatorInterface $translator,
    ) {}
}
```

**Using the translation boot**

```
use Tobento\App\Boot;
use Tobento\App\Translation\Boot\Translation;

class AnyServiceBoot extends Boot
{
    public const BOOT = [
        // you may ensure the view boot.
        Translation::class,
    ];

    public function boot(Translation $translation)
    {
        $translated = $translation->trans(
            message: 'Hi :name',
            parameters: [':name' => 'John'],
            locale: 'de'
        );
    }
}
```

Check out the [**Translation Service**](https://github.com/tobento-ch/service-translation) to learn more about it.

**Using the trans function**

```
use function Tobento\App\Translation\{trans};

$translated = trans(
    message: 'Hi :name',
    parameters: [':name' => 'John'],
    locale: 'de'
);
```

### Configure Translator

[](#configure-translator)

**Configure locale using the app language**

First install the [**app-language**](https://github.com/tobento-ch/app-language) bundle:

```
composer require tobento/app-language

```

Then, just boot the `Language::class`. That's all. The locales will be set based on the `Tobento\Service\Language\LanguagesInterface::class`.

```
// ...

$app->boot(\Tobento\App\Language\Boot\Language::class);
$app->boot(\Tobento\App\Translation\Boot\Translation::class);

// ...
```

**Configure locale manually**

```
use Tobento\App\AppFactory;
use Tobento\Service\Translation\TranslatorInterface;

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

// Add directories:
$app->dirs()->dir(realpath(__DIR__.'/../app/'), 'app');

// Adding boots
$app->boot(\Tobento\App\Translation\Boot\Translation::class);
$app->booting();

$translator = $app->get(TranslatorInterface::class);

// set the default locale:
$translator->setLocale('de');

// set the locale fallbacks:
$translator->setLocaleFallbacks(['de' => 'en']);

// set the locale mapping:
$translator->setLocaleMapping(['de' => 'de-CH']);

// or using the app on method:
$app->on(TranslatorInterface::class, function(TranslatorInterface $translator) {
    $translator->setLocale('de');
    $translator->setLocaleFallbacks(['de' => 'en']);
    $translator->setLocaleMapping(['de' => 'de-CH']);
});

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

**Configure missing translations**

If you may want to log missing translation, you can set the `MissingTranslationHandlerInterface::class` implementation to fit your needs.

```
use Tobento\App\AppFactory;
use Tobento\Service\Translation\MissingTranslationHandlerInterface;
use Tobento\Service\Translation\MissingTranslationHandler;
use Psr\Log\LoggerInterface;

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

// Add directories:
$app->dirs()->dir(realpath(__DIR__.'/../app/'), 'app');

// Adding boots
$app->boot(\Tobento\App\Translation\Boot\Translation::class);
$app->booting();

$app->set(MissingTranslationHandlerInterface::class, function()) {
    return new MissingTranslationHandler($logger); // LoggerInterface, any PSR-3 logger
});

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

### Migrate Translations

[](#migrate-translations)

By default, [Files Resources](https://github.com/tobento-ch/service-translation#files-resources) are used for the translator. Therefore, you might install and use the [App Migration](https://github.com/tobento-ch/app-migration) bundle:

**Writing a migration**

```
use Tobento\Service\Migration\MigrationInterface;
use Tobento\Service\Migration\ActionsInterface;
use Tobento\Service\Migration\Actions;
use Tobento\Service\Migration\Action\FilesCopy;
use Tobento\Service\Migration\Action\FilesDelete;
use Tobento\Service\Dir\DirsInterface;

class TranslationFiles implements MigrationInterface
{
    protected array $files;

    /**
     * Create a new TranslationFiles.
     *
     * @param DirsInterface $dirs
     */
    public function __construct(
        protected DirsInterface $dirs,
    ) {
        $transDir = realpath(__DIR__.'/../../').'/resources/trans/';

        $this->files = [
            $this->dirs->get('trans').'en/' => [
                $transDir.'en/en.json',
                $transDir.'en/shop.json',
            ],
            $this->dirs->get('trans').'de/' => [
                $transDir.'de/de.json',
                $transDir.'de/shop.json',
            ],
        ];
    }

    /**
     * Return a description of the migration.
     *
     * @return string
     */
    public function description(): string
    {
        return 'Translation files.';
    }

    /**
     * Return the actions to be processed on install.
     *
     * @return ActionsInterface
     */
    public function install(): ActionsInterface
    {
        return new Actions(
            new FilesCopy($this->files),
        );
    }

    /**
     * Return the actions to be processed on uninstall.
     *
     * @return ActionsInterface
     */
    public function uninstall(): ActionsInterface
    {
        return new Actions(
            new FilesDelete($this->files),
        );
    }
}
```

**Migration Boot**

```
use Tobento\App\Boot;
use Tobento\App\Migration\Boot\Migration;

class TranslationFilesMigration extends Boot
{
    public const BOOT = [
        // you may ensure the migration boot.
        Migration::class,
    ];

    public function boot(Migration $migration)
    {
        // Install migrations
        $migration->install(TranslationFiles::class);
    }
}
```

**App example**

```
use Tobento\App\AppFactory;

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

// Add directories:
$app->dirs()->dir(realpath(__DIR__.'/../app/'), 'app');

// Adding boots
$app->boot(\Tobento\App\Translation\Boot\Translation::class);
$app->boot(TranslationFilesMigration::class);

//...

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

### Add Translations

[](#add-translations)

You can simply add more translations by the following way:

```
use Tobento\App\AppFactory;
use Tobento\Service\Translation\TranslatorInterface;
use Tobento\Service\Translation\Resource;

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

// Add directories:
$app->dirs()->dir(realpath(__DIR__.'/../app/'), 'app');

// Adding boots
$app->boot(\Tobento\App\Translation\Boot\Translation::class);

// using the app on method:
$app->on(TranslatorInterface::class, function(TranslatorInterface $translator) {
    $translator->resources()->add(new Resource('*', 'de', [
        'Hello World' => 'Hallo Welt',
    ]));

    $translator->resources()->add(new Resource('shop', 'de', [
        'Cart' => 'Warenkorb',
    ]));
});

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

You may check out the [Add Resources](https://github.com/tobento-ch/service-translation/tree/1.x#add-resources) section to learn more about it.

### Customize Translations

[](#customize-translations)

You might customize/override translations by the following ways:

**By adding a resource with higher priority**

```
use Tobento\App\AppFactory;
use Tobento\Service\Translation\TranslatorInterface;
use Tobento\Service\Translation\Resource;

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

// Add directories:
$app->dirs()->dir(realpath(__DIR__.'/../app/'), 'app');

// Adding boots
$app->boot(\Tobento\App\Translation\Boot\Translation::class);

// using the app on method:
$app->on(TranslatorInterface::class, function(TranslatorInterface $translator) {

    $translator->resources()->add(new Resource(
        name: 'shop',
        locale: 'de',
        translations: ['Hello World' => 'Hallo Welt'],
        priority: 200, // set a higher the default added
    ));
});

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

You may specify only the translations you want to overrride as same named resources get merged.

You may check out the [Add Resources](https://github.com/tobento-ch/service-translation/tree/1.x#add-resources) section to learn more about it.

**By adding a new trans dir with higher priority**

```
use Tobento\App\AppFactory;

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

// Add directories:
$app->dirs()->dir(realpath(__DIR__.'/../app/'), 'app');

// Add trans directory with higher priority:
$this->app->dirs()->dir(
    dir: $this->app->dir('app').'trans-custom/',

    // do not use 'trans' as name for migration purposes
    name: 'trans.custom',

    group: 'trans',

    // add higher priority as default trans dir:
    priority: 300,
);

// Adding boots
$app->boot(\Tobento\App\Translation\Boot\Translation::class);

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

Then just add the translation files you wish to override in the defined directory. If the file does not exist, the file from the default trans directory is used.

**Using the translation manager**

In progress...

Credits
=======

[](#credits)

- [Tobias Strub](https://www.tobento.ch)
- [All Contributors](../../contributors)

###  Health Score

40

—

FairBetter than 86% of packages

Maintenance58

Moderate activity, may be stable

Popularity11

Limited adoption so far

Community17

Small or concentrated contributor base

Maturity66

Established project with proven stability

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~167 days

Recently: every ~181 days

Total

6

Last Release

274d ago

Major Versions

1.x-dev → 2.02025-10-01

PHP version history (2 changes)1.0.0PHP >=8.0

2.0PHP >=8.4

### Community

Maintainers

![](https://www.gravatar.com/avatar/055d6a1b5c2384bb179c75ab0b55914231d898fdc4dffeb30770f81200e52206?d=identicon)[TOBENTOch](/maintainers/TOBENTOch)

---

Top Contributors

[![tobento-ch](https://avatars.githubusercontent.com/u/16684832?v=4)](https://github.com/tobento-ch "tobento-ch (11 commits)")

---

Tags

packagetranslationtranslatorapptobento

###  Code Quality

TestsPHPUnit

Static AnalysisPsalm

Type Coverage Yes

### Embed Badge

![Health badge](/badges/tobento-app-translation/health.svg)

```
[![Health](https://phpackages.com/badges/tobento-app-translation/health.svg)](https://phpackages.com/packages/tobento-app-translation)
```

###  Alternatives

[waavi/translation

A Translation package for Laravel 5 with database and cache support

367438.2k6](/packages/waavi-translation)[om/potrans

Command line tool for translate Gettext with Google Translator API or DeepL API

10520.2k9](/packages/om-potrans)[longman/laravel-multilang

Package to integrate multi language (multi locale) functionality in Laravel 5.x

5414.6k1](/packages/longman-laravel-multilang)[jrmajor/fluent

Fluent localization system for PHP

2918.2k7](/packages/jrmajor-fluent)[johannschopplich/kirby-content-translator

DeepL & AI-powered content translation for Kirby CMS

2010.8k](/packages/johannschopplich-kirby-content-translator)[jrmajor/laravel-fluent

Fluent translations for Laravel

208.8k](/packages/jrmajor-laravel-fluent)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)