Transmatic

<p align="center"> <a href="https://laravel.com"><img alt="Laravel v10.x" src="https://img.shields.io/badge/Laravel-v10.x-FF2D20?style=for-the-badge&logo=laravel"></a> <a href="https://php.net"><img alt="PHP 8.1" src="https://img.shields.io/badge/PHP-8.1-777BB4?style=for-the-badge&logo=php"></a> <a href="https://packagist.org/packages/andrewdwallo/transmatic"><img alt="Latest Version on Packagist" src="https://img.shields.io/packagist/v/andrewdwallo/transmatic.svg?style=for-the-badge"></a> <a href="https://packagist.org/packages/andrewdwallo/transmatic"><img alt="Total Downloads" src="https://img.shields.io/packagist/dt/andrewdwallo/transmatic.svg?style=for-the-badge"></a> </p>

Transmatic is a Laravel package for real-time machine translation, enabling instant and dynamic translation across your entire application. Suitable for projects ranging from simple websites to complex SaaS platforms and more, Transmatic offers customization and flexibility. Using advanced machine translation, it makes your app globally accessible. While AWS Translate is the default engine, the package can easily integrate with other translation services.

Common Use Cases

⚡️ Application Auto-Translation

With this package, developers can automatically translate their entire application to multiple languages using services like AWS Translate. Say goodbye to manually specifying translations for each language and achieve a multilingual platform in minutes.

Benefits

• Speed - Translate your application in minutes.
• Auto Locale Management - The package manages and updates the source locale translations based on the provided text.

👤 Personalized User Experience

Empower users to customize their experience by selecting their preferred language. Once selected, the application dynamically adjusts its locale.

Benefits

• Enhanced User Experience - Interact in the user's native language.
• Real-Time Translation - Adapt instantly to the user's language selection.

🏢 SaaS Tenant-Specific Translations

Optimize the experience for SaaS businesses by offering tenant-specific translations. Each tenant can view their dashboard in their desired language.

Benefits

• Personalization - Address each tenant's language choice.
• Engagement Boost - Increase interaction by presenting content in the tenant's chosen language.

🛍️ E-Commerce for a Global Audience

Position your e-commerce platform or global marketplace for worldwide reach. Offer product descriptions, reviews, and more in numerous languages.

Benefits

• Global Reach - Cater to a global audience.
• Enhanced Sales - Improve conversion rates by engaging customers in their native language.

Installation

Start by installing the package via Composer:

composer require andrewdwallo/transmatic

After the package is installed, run the following command:

php artisan transmatic:install

Setting Up Transmatic

Queue and Batch Processing Setup

This package utilizes Laravel's queue jobs and batch processing features. The specific setup requirements depend on the queue driver configured in your Laravel application.

Database Queue Driver

If you are using the database queue driver, you'll need the following tables in your database:

• jobs: For managing queued jobs.
• job_batches: For batch processing.

If these tables are not already present in your database, you can create them by running the following commands:

php artisan queue:table
php artisan queue:batches-table

Once the tables are created, run the following command to migrate them:

php artisan migrate

For users utilizing other queue drivers (such as redis, sqs, beanstalkd, etc.), refer to the official Laravel documentation on queues for specific setup instructions.

🚧 It's important to configure and manage the queue system as per your application's requirements. Proper configuration ensures efficient handling of background jobs and tasks by the package.

AWS Translate Integration

By default, the package leverages AWS Translate. Ensure you've set the necessary configurations as specified in the AWS Service Provider for Laravel documentation, and have the following environment variables:

AWS_ACCESS_KEY_ID=your-access-key-id
AWS_SECRET_ACCESS_KEY=your-secret-access-key
AWS_REGION=your-region  # default is us-east-1

These are essential for the AWS SDK to authenticate and interact with AWS services. Once these are set, you don't need to do anything else for AWS Translate to work.

Custom Translation Service Integration

While AWS Translate is the default, Transmatic allows integration with other translation services. For integration, create a class that adheres to the Wallo\Transmatic\Contracts\Translator contract and update the transmatic.php config file accordingly.

Configuration Overview

Several configuration options are available, including setting the source locale, defining translation storage methods ( cache or JSON files), and specifying batch processing behavior. Refer to the config/transmatic.php file for a comprehensive look.

Using Transmatic

Translating Text

The translate method provides an easy way to translate a single string of text. It allows you to optionally specify replacement data for placeholders as well as the target locale. If the target locale is not specified, the application's current locale will be used.

Using Traditional Arguments:

use Wallo\Transmatic\Facades\Transmatic;

$translatedText = Transmatic::translate('Hello World', [], 'es'); // Hola Mundo

Using Named Arguments (PHP 8.0+):

use Wallo\Transmatic\Facades\Transmatic;

$translatedText = Transmatic::translate(text: 'Hello World', to: 'es'); // Hola Mundo

This method also updates the translations in your Source Locale based on the text passed in, ensuring that new strings are stored for future use.

Translating Multiple Strings

For translating multiple strings at once, use the translateMany method. This method accepts an array of strings to translate, as well as an optional target locale. If not specified, the application's current locale will be used.

use Wallo\Transmatic\Facades\Transmatic;

$texts = ['Hello World', 'Goodbye World'];

$translatedTexts = Transmatic::translateMany(texts: $texts, to: 'fr'); // ['Bonjour le monde', 'Au revoir le monde']

Like the translate method, this method will also update the translations in your Source Locale based on the text passed in.

Using Translation Placeholders

You may use placeholders in your translations. To do so, use the :placeholder syntax in your translation strings. When translating, pass in an array of values to replace the placeholders.

use Wallo\Transmatic\Facades\Transmatic;

$translatedText = Transmatic::translate(text: 'Hello :name', replace: ['name' => 'John'], to: 'es'); // Hola John

Fetching Supported Locales

To retrieve a list of supported locales, use the getSupportedLocales method. This method will return an array of locales supported by your application. For example, if in your specified file path for storing translations you have a fr.json file, this method will return ['en', 'fr'].

use Wallo\Transmatic\Facades\Transmatic;

$supportedLocales = Transmatic::getSupportedLocales(); // ['en', 'fr']

Fetching Supported Languages

To retrieve a list of supported languages along with their corresponding locales, use the getSupportedLanguages method. This method returns an associative array where the key is the locale and the value is the displayable name of the language. You can also pass a display locale as an optional parameter to get the language names in a specific language. If no display locale is specified, the application's current locale is used.

use Wallo\Transmatic\Facades\Transmatic;

$supportedLanguages = Transmatic::getSupportedLanguages();
// Output: ['en' => 'English', 'fr' => 'French']

$supportedLanguages = Transmatic::getSupportedLanguages(displayLocale: 'fr');
// Output: ['en' => 'Anglais', 'fr' => 'Français']

Getting Language from Locale

You can get the displayable name of a language from a locale using the getLanguage method. This method takes in the locale you're interested in and an optional display locale parameter. If no display locale is specified, it defaults to the application's current locale.

use Wallo\Transmatic\Facades\Transmatic;

$language = Transmatic::getLanguage(locale: 'de'); 
// Output: 'Deutsch'

$language = Transmatic::getLanguage(locale: 'de', displayLocale: 'en'); 
// Output: 'German'

Global Helper

For quick and easy translations, you may use the translate() and translateMany() helper functions.

$translatedText = translate(text: 'Hello World', to: 'es'); // Hola Mundo

$translatedTexts = translateMany(texts: ['Hello World', 'Goodbye World'], to: 'fr'); // ['Bonjour le monde', 'Au revoir le monde']

Overriding the Global Locale

If you want to override the default locale for all translation methods that do not have a specified $to parameter, you can use the setGlobalLocale method. This will set a global locale override, ensuring that the provided locale is used as the default for translations.

Setting the Global Locale in a Service Provider

In your Service Provider's boot method, you can call the setGlobalLocale method to set the global locale override.

use Wallo\Transmatic\Facades\Transmatic;

public function boot()
{
    Transmatic::setGlobalLocale(locale: 'fr');
}

When you use the translation methods after setting this global locale, they will d