Download the PHP package dialect/transedit without Composer

TransEdit

TransEdit is a Laravel plugin designed to store and manage localization strings in a database with built-in caching. It offers a flexible and interactive way to handle language translations, including an optional edit mode, which allows users to edit translations directly in the browser by simply double-clicking any highlighted text.

Table of Contents

1. Features
2. Installation
3. Configuration
4. Usage
   • Using Keys
   • Using Phrases
5. Artisan Commands
   • Add Existing Translations
   • Add Missing Translations (with Migration Option)
6. Examples
7. Publishing and Assets

Features

• Database-driven localizations – Store translations in the database instead of the traditional file-based approach.
• Built-in cache support – Improve performance by caching translations.
• Browser-based editing – Enable an edit mode that allows users to directly modify translations by double-clicking them.
• Laravel integration – Seamless integration with Laravel’s localization features.
• Vue and Inertia integration – Easily incorporate TransEdit with Vue or Inertia-based applications.

Installation

1. Require the package via Composer:

2. Publish the configuration, assets, and migrations:

   This command will publish:

   • Config file to config/transedit.php
   • Assets (JavaScript and Vue components) to your resources folder
   • Migrations to database/migrations

3. Add the Vue component
   If you’re using Laravel Mix, add the TransEdit Vue component to your main JavaScript file (commonly resources/assets/js/app.js or resources/js/app.js) and recompile:

   Then, run:

   or

   according to your build process.

4. Run the database migrations:

   This will create the necessary tables for storing translations.

5. Enable TransEdit in your front-end

   • Include the TransEdit script in your layout (e.g., resources/views/layout.blade.php):

   • If you are using Vue, register TransEdit as a global property in your app.js (or equivalent):

   • If you are using Inertia, attach transEdit in your Inertia app setup, like so:

That’s it! TransEdit is now installed and ready for use in your Laravel project.

Configuration

After running the publish command, a configuration file will be placed at config/transedit.php. This file allows you to customize how TransEdit handles caching, database settings, default locale behavior, and more. Adjust these settings as desired to suit your application’s needs.

Usage

Using Keys

TransEdit offers convenient helper methods to set and retrieve translations using keys.

1. Setting a translation key and value

2. Retrieving a translation by key

3. Helper function shorthand

4. Working with variables

5. Enable/Disable edit mode

   Note: Locale settings and edit-mode are session-based, meaning they apply to individual user sessions.

Using Phrases

TransEdit also supports using full phrases or sentences directly in place of a key.

1. Setting a phrase

2. Retrieving a phrase

3. Using variables in a phrase

4. Editing phrases in-browser

   Anywhere you have transEdit('A new phrase here') in your Blade view, you can double-click and edit it directly in the browser (if your Vue/JS setup is correct).

5. Why use phrases?
   • Speed & Convenience: No need to manage separate key strings or maintain complex nested arrays.
   • Automatic Handling: TransEdit manages insertion, updates, and caching for these phrases.
   • Iterative Development: Wrap new text in transEdit('...'). Later, if you want more structure, you can easily rename or reorganize these translations.

Artisan Commands

1. Add Existing Translations

This command scans your lang folder for Laravel language files and imports them into the TransEdit database:

For example, if you have a file lang/sv/article.php containing:

TransEdit will import the key article.recipe into the database. You can then retrieve it with:

just like you would with @lang('article.recipe').

2. Add Missing Translations (with Migration Option)

The Add Missing Phrases command scans your resources/ folder for any calls to transEdit('...') that do not already exist in the database. It then either inserts them into your database directly or creates a migration so you can manage and track these new phrases in version control.

• Default behavior: Creates a new migration file in database/migrations/.

  • After running the command, you’ll see a message indicating a migration has been created.
  • You can then run php artisan migrate to insert the missing phrases into your database.
  • This is ideal if you want to keep version control records of when new phrases are added.

• Pushing directly to the database:

  This immediately inserts any missing phrases for all locales into the database without creating a migration file.

Below is a summary of the two approaches:

Why choose a migration approach?

• Ensures that adding translations is tracked in source control.
• Allows rollback with php artisan migrate:rollback if needed.
• Useful in team environments where changes to translations should be approved or reviewed.

Why choose the direct approach?

• Faster and easier for quick adjustments.
• Ideal for smaller projects or development environments where versioning of translations is not critical.

Examples

Below is a short snippet demonstrating how to use TransEdit in your application:

Publishing and Assets

• Assets
  Published to resources/assets (or the equivalent path for your setup).
  They include Vue components and the JavaScript file transedit.js.

• Config
  Published to config/transedit.php.

• Migrations
  Published to database/migrations.

Make sure to run:

to get all these files where they need to be.

That’s everything you need to start translating and editing your Laravel app with TransEdit!

Feel free to open an issue or submit a pull request on GitHub if you have any questions or improvements. Enjoy!