updated docs

athphane · athphane · commit 98b96aa52a08 · 2025-07-31T16:38:35.000Z
diff --git a/docs/contributing-to-docs.md b/docs/contributing-to-docs.md
@@ -1,11 +1,18 @@
 ---
-title: Contributing to the docs
+title: Contributing to the Docs
 sidebar_position: 99
 ---
 
-Should you come across any glitches in our documentation, your discerning eye is much appreciated. If you've got a solution itching to be implemented, feel free to submit a PR – we welcome your contribution.
+# Contributing to the Docs
+
+We believe that documentation is just as important as code, and we're always looking for ways to improve it. If you find any issues with our documentation, or if you have any suggestions for how we can make it better, we'd love to hear from you.
+
+If you're interested in contributing to the documentation, you can do so by submitting a pull request to the [Translatable repository on GitHub](https://github.com/Javaabu/translatable). The documentation is located in the `/docs` directory, and it's written in Markdown.
+
+We use [Docusaurus](https://docusaurus.io) to generate our documentation website, so you can use all of the features that Docusaurus provides, such as:
 
-For your reference, each project's documentation resides snugly in the /docs folder. That's the hub where everything documentation-related unfolds. Just so you're in the loop, we employ [Docusaurus](https://docusaurus.io) to transform those markdown files into the HTML served to the public. And since we are using Docusaurus, there's a lot of special magic that you can use to make the docs even better. Here are a few resources that will be useful:
 - [Markdown Front Matter](https://docusaurus.io/docs/markdown-features#front-matter)
 - [Admonitions](https://docusaurus.io/docs/markdown-features/admonitions)
-- [Sidebar Metadata](https://docusaurus.io/docs/sidebar/autogenerated#autogenerated-sidebar-metadata)
+- [Sidebar Metadata](https://docusaurus.io/docs/sidebar/autogenerated#autogenerated-sidebar-metadata)
+
+We appreciate your help in making our documentation the best it can be!
diff --git a/docs/installation-and-setup.md b/docs/installation-and-setup.md
@@ -3,30 +3,54 @@ title: Installation & Setup
 sidebar_position: 1.2
 ---
 
-# Installation
+# Installation & Setup
 
-You can install the package via composer:
+Getting started with Translatable is a straightforward process. This guide will walk you through installing the package, configuring it, and setting up your models to be translatable.
+
+## 1. Installation
+
+First, pull the package into your project using Composer:
 
 ```bash
 composer require javaabu/translatable
 ```
 
-# Publishing the config file
+Laravel's package auto-discovery feature will automatically register the necessary service provider.
+
+## 2. Publishing Assets
+
+Next, you'll need to publish the package's assets. This includes migrations, configuration files, and optional views.
+
+### Migrations
+
+Publish the migrations file, which will add a `languages` table to your database:
+
+```bash
+php artisan vendor:publish --provider="Javaabu\Translatable\TranslatableServiceProvider" --tag="translatable-migrations"
+```
+
+After publishing, run the migration to create the table:
+
+```bash
+php artisan migrate
+```
+
+### Configuration File (Optional)
 
-Publishing the config file is optional:
+If you need to customize the package's behavior, you can publish the configuration file:
 
 ```bash
 php artisan vendor:publish --provider="Javaabu\Translatable\TranslatableServiceProvider" --tag="translatable-config"
 ```
 
-This is the default content of the config file:
+This will create a `config/translatable.php` file. Here's an overview of the available options:
 
-```php
+```php title="config/translatable.php"
 return [
-    // Allows for custom models
-    'language_model' => \Javaabu\Translatable\Models\Language::class,
+    // Specify a custom model for languages if you need to extend the default one.
+    'language_model'                 => Javaabu\Translatable\Models\Language::class,
 
-    // Standard fields to be ignored for translation on all models
+    // Define fields that should never be translated on any model.
     'fields_ignored_for_translation' => [
         'id',
         'lang',
@@ -35,42 +59,63 @@ return [
         'deleted_at',
     ],
 
-    // Whether attr_dv should fall back to app locale if translations do not exist
-    'lang_suffix_should_fallback' => false,
+    // Set to `true` if you want suffixed attributes (e.g., `title_dv`) to fall back
+    // to the default application locale if a translation doesn't exist.
+    'lang_suffix_should_fallback'    => false,
 
-    // Default locale before translations are added
-    'default_locale' => 'en',
-];
+    // The default locale to use before any translations are added.
+    'default_locale'                 => 'en',
 
+    // Cache configuration for the Language Registrar, which stores language lists.
+    'cache'                          => [
+        'expiration_time' => DateInterval::createFromDateString('24 hours'),
+        'key'             => 'translation.languages.cache',
+        'driver'          => 'default',
+    ],
 
-```
+    // CSS classes for styling the Blade components.
+    'styles' => [
+        'table-cell-wrapper' => 'd-flex justify-content-center align-items-center',
 
-# Setup
+        'icons'              => [
+            'add'  => 'fas fa-plus',
+            'edit' => 'fas fa-edit',
+        ],
+    ],
+];
+```
 
+## 3. Making Your Models Translatable
 
-Translatables currently provides **two** different types of translatables, `Db` and `Json`. Check out [Difference between DB and JSON translatable](./basic-usage/difference-isdbtranslatable-isjsontranslatable.md) to learn the differences and design considerations for both
+Now for the fun part! To make an Eloquent model translatable, you need to perform two steps: update its migration and add a trait to the model itself.
 
-## Setting up your migrations
+Translatable offers two strategies for storing translations:
 
-If you are setting up a new model, you can simply add either `$table->dbTranslatable();` or `$table->jsonTranslatable();` into your migration schema create function.
+- **Database-based (`DbTranslatable`):** Stores each language as a new row in the model's table. Better for complex queries and indexing.
+- **JSON-based (`JsonTranslatable`):** Stores all translations in a single JSON column. Simpler and requires fewer database queries.
 
-:::warning
+:::tip
+To understand the pros and cons of each approach, check out the [Difference between DB and JSON translatable](./basic-usage/difference-isdbtranslatable-isjsontranslatable.md) page.
+:::
 
-Use one or the other, **DON'T use both at the same time**.
+### Step 3.1: Update the Migration
 
-:::
+You need to add the necessary columns to your model's table. Choose **one** of the following methods.
 
-```php
-use Javaabu\Translatable\DbTranslatable\DbTranslatableSchema;
+```php title="database/migrations/your_create_model_table.php"
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
 
 return new class extends Migration {
     public function up(): void
     {
         Schema::create('posts', function (Blueprint $table) {
             $table->id();
+            $table->string('author');
+            // ... other columns
 
-            // ...
-
+            // Choose one of the following:
             $table->dbTranslatable();
             // OR
             $table->jsonTranslatable();
@@ -84,48 +129,59 @@ return new class extends Migration {
 };
 ```
 
-Or if you have already made the model, you can write a migration to add the columns to the existing table.
+If you have an existing table, you can create a new migration to add the columns:
 
 ```php
-use Javaabu\Translatable\DbTranslatable\DbTranslatableSchema;
-
-return new class extends Migration {
-    public function up(): void
-    {
-        Schema::create('posts', function (Blueprint $table) {
-            $table->dbTranslatable();
-            // OR
-            $table->jsonTranslatable();
-        });
-    }
-
-    public function down(): void
-    {
-        Schema::table('posts', function (Blueprint $table) {
-            $table->dropDbTranslatable();
-            // OR
-            $table->dropJsonTranslatable();
-        });
-    }
-};
+Schema::table('posts', function (Blueprint $table) {
+    // Choose one
+    $table->dbTranslatable();
+    // OR
+    $table->jsonTranslatable();
+});
 ```
 
-## Setting up your models
+### Step 3.2: Update the Model
 
+Finally, implement the correct contract and add the corresponding trait to your model. Again, choose the setup that matches the migration you created.
 
-All you need to do is add the `Translatable` implementation using the `IsDbTranslatable` or `IsJsonTranslatable` trait.
+#### For DB-based Translations
 
-```php
-...
-use Javaabu\Translatable\Contracts\Translatable;use Javaabu\Translatable\DbTranslatable\IsDbTranslatable;
+If you used `$table->dbTranslatable()`, your model should implement the `DbTranslatable` contract and use the `IsDbTranslatable` trait.
 
-class Post extends Model implements Translatable
+```php title="app/Models/Post.php"
+use Illuminate\Database\Eloquent\Model;
+use Javaabu\Translatable\Contracts\DbTranslatable as DbTranslatableContract;
+use Javaabu\Translatable\DbTranslatable\IsDbTranslatable;
+
+class Post extends Model implements DbTranslatableContract
 {
     use IsDbTranslatable;
-    // OR
+
+    // ... your model properties
+
+    // IMPORTANT: Add the fields you want to translate here
+    public array $translatable = ['title', 'content'];
+}
+```
+
+#### For JSON-based Translations
+
+If you used `$table->jsonTranslatable()`, your model should implement the `JsonTranslatable` contract and use the `IsJsonTranslatable` trait.
+
+```php title="app/Models/Post.php"
+use Illuminate\Database\Eloquent\Model;
+use Javaabu\Translatable\Contracts\JsonTranslatable as JsonTranslatableContract;
+use Javaabu\Translatable\JsonTranslatable\IsJsonTranslatable;
+
+class Post extends Model implements JsonTranslatableContract
+{
     use IsJsonTranslatable;
 
-...
+    // ... your model properties
+
+    // IMPORTANT: Add the fields you want to translate here
+    public array $translatable = ['title', 'content'];
+}
 ```
 
-Once this is setup, you are good to go!
+And that's it! Your model is now set up for translations. You can start adding and fetching translated attributes right away.
diff --git a/docs/intro.md b/docs/intro.md
@@ -3,11 +3,13 @@ title: Introduction
 sidebar_position: 1.0
 ---
 
-# Translatable
+# Introduction
 
-[Translatable](https://github.com/Javaabu/translatable) adds multi-lingual to Laravel models. 
+Welcome to the documentation for Translatable, a Laravel package that adds multi-lingual support to your models.
 
-This package allows Laravel model attributes to be translated automatically according to the current `app()->getLocale()`.
+This package allows your Laravel model attributes to be translated automatically according to the current `app()->getLocale()`. This means you can easily create applications that cater to a global audience, without having to worry about the complexities of localization.
+
+Here's a quick example of how it works:
 
 ```php
 app()->setLocale('en');
@@ -20,9 +22,11 @@ $post->title_en // This is an English title
 $post->title_dv // Mee dhivehi title eh
 ```
 
-Adding a translation is made easier as well using the language code suffix.
+As you can see, it's incredibly simple to get and set translations for your model attributes. You can even add new translations on the fly:
 
 ```php
 // to add title for dv language
 $post->title_dv = "Mee Dhivehi title eh";
 ```
+
+Throughout this documentation, we'll explore all the features of Translatable in detail, from basic usage to advanced customization. We'll also cover how to contribute to the project and where to find help if you need it.
diff --git a/docs/questions-and-security.md b/docs/questions-and-security.md
@@ -1,8 +1,14 @@
 ---
-title: Questions and Security
+title: Questions & Security
 sidebar_position: 1.5
 ---
 
-Find yourself stuck using the package? Found a bug? Do you have general questions or suggestions for improving this package? Feel free to create an [issue](../../issues) on GitHub, we'll try to address it as soon as possible.
+# Questions & Security
 
-If you've found a bug regarding security please mail [info@javaabu.com](mailto:info@javaabu.com) instead of using the issue tracker.
+Do you have a question? Is something not working as expected? Have you found a bug? Or maybe you have a suggestion for a new feature? We'd love to hear from you! Please feel free to create an [issue on GitHub](https://github.com/Javaabu/translatable/issues), and we'll do our best to get back to you as soon as possible.
+
+## Security Vulnerabilities
+
+If you discover a security vulnerability within this package, please send an e-mail to [info@javaabu.com](mailto:info@javaabu.com). All security vulnerabilities will be promptly addressed.
+
+We take security very seriously, and we appreciate your help in keeping this package secure.
diff --git a/docs/requirements.md b/docs/requirements.md
@@ -3,7 +3,22 @@ title: Requirements
 sidebar_position: 1.1
 ---
 
-This package requires the following:
+# Requirements
 
-- Laravel 10.0 or higher
-- PHP 8.2 or higher
+Before you can start using Translatable, you'll need to make sure your development environment meets the following requirements:
+
+- **Laravel:** Version 9.0 or higher
+- **PHP:** Version 8.2 or higher
+
+Additionally, this package relies on the following dependencies:
+
+- `illuminate/support`: ^9.0 || ^10.0 || ^11.0 || ^12.0
+- `javaabu/helpers`: ^1.61
+
+And for development, you'll need:
+
+- `laravel/pint`: ^1.14
+- `orchestra/testbench`: ^7.0 || ^8.0 || ^9.0 || ^10.0
+- `phpunit/phpunit`: ^9.5 || ^10.5 || ^11.5
+
+We also suggest using `javaabu/forms` for the little buttons and table cells that are provided.
