Download the PHP package tobento/app-translation without Composer

App Translation

Integrates the service-translation package into your application and provides tools for scanning, managing, and customizing translation messages.

Table of Contents

• Getting Started
  • Requirements
• Documentation
  • App
  • Translation Boot
  • Basic Usage
    • Translate Message
  • Configure Translator
    • Configure Locales
    • Configure Missing Translation Handler
  • Managing Translations
    • Migrate Translations
    • Add Translations
  • Customize Translations
    • Using Resources
    • Using Directory
    • Using Translation Web App
  • Scanning Messages
    • Message Scanner
      • Default Patterns
    • Run Scanner
  • Console
    • List Translations Command
    • Resources Command
    • Scan Messages Command
• Credits

  ---

Getting Started

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

Requirements

• PHP 8.4 or greater

Documentation

App

Check out the App Skeleton if you are using the skeleton.

You may also check out the App to learn more about the app in general.

Translation Boot

The translation boot does the following:

• implements TranslatorInterface
• adds app macro

By default, Files Resources are used for the translator.

Translate Message

You can translate messages in several ways:

Using the app

Using autowiring

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

Using the translation boot

Check out the Translation Service to learn more about it.

Using the trans function

Configure Translator

Configure Locales

Configure locale using the app language

First install the app-language bundle:

Then, just boot the . That's all. The locales will be set based on the .

Configure locale manually

Configure Missing Translation Handler

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

You can find more handlers in the Missing Translation Handler section of the Translation Service.

Managing Translations

Migrate Translations

By default, Files Resources are used for the translator. Therefore, you might install and use the App Migration bundle:

Writing a migration

Migration Boot

App example

Add Translations

You can simply add more translations by the following way:

You may check out the Add Resources section to learn more about it.

Customize Translations

Customizing translations allows you to override existing messages or provide alternative translations without modifying the original translation files. Tobento’s translation system is fully resource-driven and priority-based, so you can extend or replace translations using resources, directories, or external tools such as the Translation Web App.

Using Resources

Resources let you override or extend translations programmatically.
By adding a resource with a higher priority, your custom translations take precedence over the default ones.
You only need to specify the translations you want to override - resources with the same name are automatically merged.

You may check out the Add Resources section to learn more about how resources work in the underlying Translation Service.

Example

Using Directory

You can also customize translations by adding a new translation directory with a higher priority.
Any translation file placed in this directory overrides the corresponding file in the default trans directory.
If a file does not exist in your custom directory, the default file is used automatically.

This approach is ideal when you want to override entire translation files or maintain custom translations separately from the application's default ones.

Example

Using Translation Web App

For a more convenient workflow, you can manage, override, and publish translations using the App Translation Web package.
It provides a full browser-based interface for editing, organizing, importing, exporting, and onboarding translations across one or multiple apps.

Check out App Translation Web for more details.

Scanning Messages

The translation system includes a message scanner that can automatically detect translation messages in your source code.
This is useful when creating a new app, customizing existing features, or adding new translation messages during development.
It helps you keep your translation resources aligned with the messages used in your application code.

The scanner analyzes your project using configurable patterns, allowing you to adapt it to different coding styles or message formats.

Message Scanner

The Message Scanner is responsible for locating translation messages throughout your application.
It supports multiple patterns and flexible configuration so you can tailor the scanning process to your project structure.

Default Output Path and Directory

By default, the Translation Boot registers the MessageScannerInterface with:

• a default output path
• a default directory (src)
• the default patterns

This ensures the scanner works out-of-the-box without requiring any command-line options.

The file collected-messages.json is created in your project root directory and is used when running the scanner with the --output option.

If you want to change where scanned messages are stored see next section.

Customizing Scanner

When the scanner is executed, a default scanner instance is provided by the Translation Boot.
It uses the default patterns and directories defined in the boot configuration.

You may customize the scanner by modifying the MessageScannerInterface implementation.
This allows you to add or override patterns, adjust directories, or extend the scanning behavior to match your application's needs.

Available Methods

All with* methods are immutable, returning a new scanner instance.

Default Patterns

The default scanner provides a set of default patterns that detect common translation usages.
These patterns cover typical message calls and are suitable for most applications.

The following patterns are added:

Run Scanner

The message scanner can be executed through the console using the Scan Messages Command.
See the Scan Messages Command for details on how to run it and how to configure directories, output formats, and storage behavior.

Console

List Translations Command

If you have installed the App Console, you may list all available translations using the translations:list command.
This is useful for inspecting which messages exist for each locale and verifying that your translation resources are loaded correctly.

List all translations

Available Options

Resources Command

You may inspect all registered translation resources using the translations:resources command.
This helps you understand which resources are loaded, their priority, and how they contribute to the final translation set.

List all translation resources

Available Options

Scan Messages Command

You may scan your source code for translation messages using the translations:scan command.
This is useful when creating a new app, customizing existing functionality, or adding new translation messages during development.

Scan messages using the default scanner configuration

Available Options

Credits

• Tobias Strub
• All Contributors