README

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 default to this overridden locale unless another locale is specified.

Example

use Wallo\Transmatic\Facades\Transmatic;

Transmatic::setGlobalLocale(locale: 'fr');

$translatedText = Transmatic::translate(text: 'Hello World'); // Bonjour le monde

Remember, specifying a locale in the translation methods will always take precedence over the global locale override.

use Wallo\Transmatic\Facades\Transmatic;

Transmatic::setGlobalLocale(locale: 'fr');

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

Processing Missing Translations

To ensure all your translations are up-to-date, especially when there are missing translations for certain locales, you can utilize the functionality to process missing translations. This will help in generating the missing translations for all the supported locales excluding the source locale.

Using the Facade in a Service Provider

In your Service Provider's boot method, you have two options when calling the facade to process missing translations:

Specifying Locales

You can process missing translations for a specific list of locales using the processMissingTranslationsFor method.

use Wallo\Transmatic\Facades\Transmatic;

public function boot()
{
    Transmatic::processMissingTranslationsFor(locales: ['fr', 'de']);
}

Processing All Supported Locales

You can process all the missing translations for all the supported locales excluding the source locale using the processMissingTranslations method.

use Wallo\Transmatic\Facades\Transmatic;

public function boot()
{
    Transmatic::processMissingTranslations();
}

Using the Artisan Command

If you would prefer to manually trigger the processing of missing translations, you may use the console command transmatic:process-missing-translations. This command will provide you with a list of all the supported locales excluding the source locale, and you can choose which locales you would like to process. You may choose to process all the locales at once by selecting the All option.

This command is especially useful during development when you're adding new translations to your source locale and want to process the missing translations for all the supported locales.

php artisan transmatic:process-missing-translations

Behind the Scenes

Managing Translations

When you call the translate or translateMany methods, Transmatic will first check to see if the translation already exists in your application's source locale. If it does, it will process and return the translations for the specified target locale. If not, it will update your source locale's translations with the new text, and then continue with the translation process.

Transmatic checks if a batch translation process is running for the target locale you specify. If a batch is running, the package fetches the translations from either cache or JSON language files, depending on your configuration.

New vs. Existing Translations

For new target locales, Transmatic initiates a queued batch translation process managed by the underlying TranslateService class. This allows the package to efficiently handle large volumes of text for translation in one go, thanks to a queuing mechanism.

For existing target locales where most translations are already in place, the dispatchSync method is used for immediate, synchronous translation.

Importance of a Robust Source Locale

To make the most out of the batch processing feature for new target locales, it's recommended to have a well-populated source locale language file. While the code ensures that the source locale is up-to-date before proceeding with translations, having a robust set of translations in the source locale maximizes the efficiency of the batch processing for new languages.

Contributing

Thank you for considering contributing to Transmatic! Follow these steps to get started:

Fork the Repository: Fork this repository to your GitHub account.
Create a Fresh Laravel Project: If you don't already have a Laravel project set up, create one.
Clone Your Forked Repository: Clone your forked Transmatic repository into your Laravel application's root directory.

git clone https://github.com/your-github-username/transmatic.git

Create a New Branch: Inside the '/transmatic' directory, create a branch for your fix or feature. For instance, if you're working on an error message fix, you might name your branch fix/error-message.

git checkout -b fix/error-message

Install the Package Locally: Update your application's composer.json file to include the local package. Use the dev prefix followed by your branch's name:

{
    // ...
    "require": {
        "andrewdwallo/transmatic": "dev-fix/error-message"
    },
    "repositories": [
        {
            "type": "path",
            "url": "transmatic/"
        }
    ],
    // ...
}

Update Composer: Run composer update to install the local version of the package in your Laravel project.

Once you've made your changes, commit them, push to your branch, and then create a pull request. Your contributions are highly valued and appreciated!

Need Help?

Thank you for your interest in Transmatic! Whether you're just getting started, have spotted a bug, or are thinking of a new feature, here's how you can get help:

🐛 Spotted a Bug?

If you think you've found a bug in Transmatic:

First, check the Issues section to see if someone else has already reported the same problem.
If it's an unreported bug, please open a new issue, providing as much detail as possible, including steps to reproduce the issue.
Feel free to fix the bug yourself! Follow the Contributing guidelines to get started.

🙋‍♂️ Have a Question or Feature Request?

If you have questions about how to use Transmatic or ideas for new features:

Start by checking the Documentation to see if your question is already answered.
For specific questions or general discussion, visit Discussions.
- Have a question? Head over to Q&A.
- Want to share an idea or feature request? Share it in Feature Requests.

🔐 Discovered a Security Vulnerability?

Security is a top priority. If you discover any issue regarding security:

Please DO NOT open an issue on GitHub. Disclosing security vulnerabilities publicly can be harmful.
Instead, review the Security Policy for instructions on how to report a security vulnerability.
I'm dedicated to keeping users safe and will address valid security concerns diligently.

Changelog

Please see CHANGELOG for more information on what has changed recently.

License

The MIT License (MIT). Please see License File for more information.

andrewdwallo / transmatic

Maintainers

Details

README

Common Use Cases

⚡️ Application Auto-Translation

Benefits

👤 Personalized User Experience

Benefits

🏢 SaaS Tenant-Specific Translations

Benefits

🛍️ E-Commerce for a Global Audience

Benefits

Installation

Setting Up Transmatic

Queue and Batch Processing Setup

Database Queue Driver

AWS Translate Integration

Custom Translation Service Integration

Configuration Overview

Using Transmatic

Translating Text

Using Traditional Arguments:

Using Named Arguments (PHP 8.0+):

Translating Multiple Strings

Using Translation Placeholders

Fetching Supported Locales

Fetching Supported Languages

Getting Language from Locale

Global Helper

Overriding the Global Locale

Setting the Global Locale in a Service Provider

Example

Processing Missing Translations

Using the Facade in a Service Provider

Specifying Locales

Processing All Supported Locales

Using the Artisan Command

Behind the Scenes

Managing Translations

New vs. Existing Translations

Importance of a Robust Source Locale

Contributing

Need Help?

🐛 Spotted a Bug?

🙋‍♂️ Have a Question or Feature Request?

🔐 Discovered a Security Vulnerability?

Changelog

License