From 1622e4927fbe1b7230af5c323aef25b4c568fd1a Mon Sep 17 00:00:00 2001 From: Manoj Hortulanus Date: Mon, 7 Jul 2025 15:18:25 +0200 Subject: [PATCH] Redo Laravel Translations docs --- .../laravel-translations/01-introduction.md | 246 ++++++++++++++---- 1 file changed, 192 insertions(+), 54 deletions(-) diff --git a/09-plugins/plugins/translations/sub/laravel-translations/01-introduction.md b/09-plugins/plugins/translations/sub/laravel-translations/01-introduction.md index 35193de..5e8d7cd 100644 --- a/09-plugins/plugins/translations/sub/laravel-translations/01-introduction.md +++ b/09-plugins/plugins/translations/sub/laravel-translations/01-introduction.md @@ -4,72 +4,103 @@ title: Backstage Laravel Translations # Translations for Laravel -## Installation +## Table of Contents -You can install the package via composer: +- [Overview](#overview) +- [Getting Started](#getting-started) + - [Prerequisites](#prerequisites) + - [Installation](#installation) +- [Usage](#usage-with-installation) + - [Add lang types](#add-lang-types) + - [Scan For translations](#scan-for-translations) + - [Translate scanned translations](#translate-scanned-translations) + - [Using the the model translatable attributes feature](#using-the-the-model-translatable-attributes-feature) +- [Features](#features) -```bash -composer require backstage/laravel-translations -``` -You can publish and run the migrations with: +## Overview -```bash -php artisan vendor:publish --provider="Backstage\Translations\Laravel\TranslationServiceProvider" -php artisan migrate -``` +Laravel-Translations is a powerful developer tool that simplifies the management, translation, and synchronization of multilingual content within Laravel applications. It integrates multiple translation providers, automates workflows like language addition and translation updates, and ensures high code quality through static analysis and testing. -This is the contents of the published config file: +**Why laravel-translations?** -```php -use EchoLabs\Prism\Enums\Provider; +This project helps developers build scalable, maintainable multilingual systems with ease. The core features include: -[ - 'scan' => [ - 'paths' => [ - base_path(), - ], - 'files' => [ - '*.php', - '*.blade.php', - '*.json', - ], +- 🧩 **🌐 Globe:** Support for multiple translation providers like Google Translate, DeepL, and AI, enabling flexible localization strategies. +- πŸš€ **βš™οΈ Automation:** Automates adding new languages, scanning source files, and updating translations to streamline workflows. +- πŸ” **πŸ› οΈ Quality:** Integrates static analysis (PHPStan) and automated testing to maintain a robust codebase. +- πŸ”„ **πŸ”§ Synchronization:** Manages language lifecycle events and keeps translation data consistent across the system. +- 🎯 **🧰 Extensibility:** Custom loaders, translation drivers, and models provide a flexible architecture for complex localization needs. - 'functions' => [ - 'trans', - 'trans_choice', - 'Lang::transChoice', - 'Lang::trans', - 'Lang::get', - 'Lang::choice', - '@lang', - '@choice', - '__', - ], - ], +--- - 'translators' => [ - 'default' => env('TRANSLATION_DRIVER', 'google-translate'), +## Features - 'drivers' => [ - 'google-translate' => [ - // no options - ], +| | Component | Details | +| :--- | :------------------- | :------------------------------------------------------------------------------------------ | +| βš™οΈ | **Architecture** | | +| πŸ”© | **Code Quality** | | +| πŸ“„ | **Documentation** | | +| πŸ”Œ | **Integrations** | | +| 🧩 | **Modularity** | | +| πŸ§ͺ | **Testing** | | +| ⚑️ | **Performance** | | +| πŸ›‘οΈ | **Security** | | +| πŸ“¦ | **Dependencies** | | - 'ai' => [ - 'provider' => Provider::OpenAI, // Example provider - 'model' => 'text-davinci-003', // Example model - 'system_prompt' => 'You are an expert mathematician who explains concepts simply. The only thing you do it output what i ask. No comments, no extra information. Just the answer.', // Example system prompt - ], - ], - ], -]; +--- + +## Getting Started + +### Prerequisites + +This project requires the following dependencies: + +- **Programming Language:** PHP +- **Package Manager:** Composer + +### Installation + +Build laravel-translations from the source and install dependencies: + +1. **Clone the repository:** + ```sh + ❯ git clone https://github.com/backstagephp/laravel-translations + ``` + +2. **Navigate to the project directory:** + + ```sh + ❯ cd laravel-translations + ``` + +3. **Install the dependencies:** + +**Using [composer](https://www.php.net/):** + +```sh +❯ composer install +``` + +### Usage (with installation) + +Run the project with: + +**Using [composer](https://getcomposer.org/):** + +You can install the package via composer: + +```bash +composer require backstage/laravel-translations ``` -If you have choosen the AI driver, please read the [Prism documentation](https://prism.echolabs.dev/providers/anthropic.html) on how to configure providers. +You can publish and run the migrations with: -## Usage +```bash +php artisan vendor:publish --provider="Backstage\Translations\Laravel\TranslationServiceProvider" +php artisan migrate +``` ### Add lang types @@ -89,8 +120,6 @@ translations:languages:add en English translations:languages:add fr-BE FranΓ§ais // French specifically for Belgians ``` -The command can also be used without in-command-line parameters - ### Scan for translations To scan for translations within your Laravel application, use the following command: @@ -120,4 +149,113 @@ php artisan translations:translate --code=en php artisan translations:translate --code=fr-BE --update // overwrite existing translations php artisan translations:translate // translate all languages -``` \ No newline at end of file +``` + +### Using the the model translatable attributes feature + +To translate attributes within youre models, import the following to your model: + +```php +use Backstage\Translations\Laravel\Contracts\TranslatesAttributes; +use Backstage\Translations\Laravel\Models\Concerns\HasTranslatableAttributes; +use Illuminate\Database\Eloquent\Model; + +class TestTranslateModel extends Model implements TranslatesAttributes +{ + use HasTranslatableAttributes; +} +``` + +After that register the model inside the ``translations.php``: + +```php + 'eloquent' => [ + 'translatable-models' => [ + // Content::class, + TestTranslateModel::class + ], + ], +``` + +Now add the translatable attributes to the model: + +```php + +use Backstage\Translations\Laravel\Contracts\TranslatesAttributes; +use Backstage\Translations\Laravel\Models\Concerns\HasTranslatableAttributes; +use Illuminate\Database\Eloquent\Model; + +class TestTranslateModel extends Model implements TranslatesAttributes +{ + use HasTranslatableAttributes; + + public function getTranslatableAttributes(): array + { + return [ + 'title', + 'description', + 'body', + 'metadata', + 'views', + ]; + } +} +``` + +After this it's very important that you add the casts per translatable attribute: + +```php + + protected $casts = [ + 'title' => 'string', + 'description' => 'encrypted', + 'body' => 'array', + 'metadata' => 'array', + 'views' => 'integer', + ]; +``` + +After this is done, every time you save an entry, the (new) contents automatticly gets updates (queued). If you want to check every night if the translatable attributes are synced, use this command to schedule: + +```bash + +php artisan translations:sync # this will remove orphaned translations (if existing) and fills translations if they are missing + +``` + +To retrieve the translatable attribute you use: + +```php + +$translatedDescription = $modelInstance->getTranslatedAttribute('description'); + +``` + +If a specific locale is needed, use: + +```php + +$translatedDescription = $modelInstance->getTranslatedAttribute( + attribute: 'description', + locale: 'de' // Can be any language existig in the DB (check translations:languages:add command) + ); + +``` + +If needed to get all translated attributes, use: + +```php + +$translatedAttributes = $modelInstance->getTranslatedAttributes(); + +``` + +If needed to get all translated attributes a specific locale use: + +```php + +$translatedAttributes = $modelInstance->getTranslatedAttributes( + locale: 'de' + ); + +```