Download the PHP package wazza/dom-translate without Composer

Laravel Translate Package

A library that leverages Laravel Directives to provide automated translations for all your Blade phrases or words.

Example: Write HTML static data in English and display it in a different language in real-time.

Overview

The library uses three database tables (_domtphrases, _domttranslations, and _domtlanguages) to manage translations efficiently.

1. On page load, the system searches for a specific translation using the provided phrase in the @transl8() directive from the _domttranslations table.

   Laravel generally cache views, so if the content of the entire page didn't change, steps 1 - 4 will not fire as the cached view will simply load.

2. If the translation is found, it is returned and displayed on the page without making an API call.
3. If the translation is not found (not translated yet), the Google Translate API (or another defined provider) is called to retrieve the new translation.
4. The newly translated text is then inserted into the database to avoid future API calls for the same phrase.

Note: To ensure quick retrieval of translations, each phrase is hashed and stored in an indexed table column. All searches are performed against this indexed column for optimal performance.

Installation

PHP 8.0 is the minimum requirement for this project.

Follow these steps to install the package:

Add DOM_TRANSLATE_GOOGLE_KEY={your_google_api_key} to your .env file and run:

Below are all the supported .env keys with their default values if not provided. The KEY (i.e., DOM_TRANSLATE_GOOGLE_KEY) is required.

• If DOM_TRANSLATE_USE_SESSION is true, translations will be saved in the session and used as the first point of retrieval.
• If no translations are found in the session, or if DOM_TRANSLATE_USE_SESSION is false, translations will be retrieved from the database, provided they have been previously stored there.
• If translations are still not found, or if both DOM_TRANSLATE_USE_SESSION and DOM_TRANSLATE_USE_DATABASE are false, translations will be sourced from a third-party translation service (e.g., Google Translate).
• Depending on whether DOM_TRANSLATE_USE_SESSION and DOM_TRANSLATE_USE_DATABASE are true, the retrieved translation will be saved to either the session or the database.
• We strongly recommend setting DOM_TRANSLATE_USE_DATABASE to true (default is true if not specified in your .env) to ensure we don't make repeated API calls (also it's slower calling the API verses db/session lookup).

Note: If you don't have a Google Cloud Platform account, sign up and create a new project. Add the Cloud Translation API to it. You can use Insomnia to test your API key.

Review any configuration file changes that you might want to make. The config file is published to the main config folder.

You're all set! 😉

Restart your service and update your Blade files with the @transl8 directive. Only new untranslated phrases will trigger an API call. Future requests for the same phrase will be retrieved from the database.

HTML Blade Example

Here are a few examples of how to use the translate Blade directive in your HTML (Blade) files:

Blade Directive Example

Four directives are available by default (@transl8() is the main one). You can add more in your Laravel AppServiceProvider file (under the register() method).

Future Development (Backlog)

• Translations are not always perfect. Create a Phrase vs Translation admin section that will allow admin users to change (update) a translated phase with corrections.
• Create alternative translation engines. Currently, only Google Translate is supported via Wazza\DomTranslate\Controllers\ApiTranslate\GoogleTranslate(). Other options to consider include NLP Translation, Microsoft Translator, etc.

Running Local Tests

Run the following command to execute tests:

Important: For the final two assert tests to work, add your personal Google Translate key as DOM_TRANSLATE_GOOGLE_KEY=xxx in your .env file (free options are available at the time of writing), or directly in the phpunit.xml file under DOM_TRANSLATE_GOOGLE_KEY.