Merge pull request #675 from bezhanSalleh/streamlined-localization

Streamline permission label resolution system

Author: bezhanSalleh

README.md

@@ -105,8 +105,10 @@ The easiest and most intuitive way to add access management to your Filament pan
     - [Generate Command Options (recap)](#generate-command-options-recap)
   - [Localization](#localization)
     - [Configuration](#configuration-4)
-    - [Key](#key)
-    - [Default](#default)
+    - [How It Works](#how-it-works)
+    - [Generating Translation Files](#generating-translation-files)
+    - [Translation Keys](#translation-keys)
+    - [Default Package Translations](#default-package-translations)
 - [Upgrade](#upgrade)
 - [Translations](#translations)
 - [Testing](#testing)
@@ -576,6 +578,8 @@ shield:super-admin [--user=] [--panel=] [--tenant=]
 shield:seeder [--generate] [--option=permissions_via_roles|direct_permissions] [--force]
 
 shield:publish --panel={panel} [--cluster=] [--nested] [--force]
+
+shield:translation {locale} [--panel=] [--path=]
 ```
 
 ### Generate Command Options (recap)
@@ -593,85 +597,93 @@ shield:publish --panel={panel} [--cluster=] [--nested] [--force]
 ```
 
 ## Localization
-Shield supports multiple languages out of the box. When enabled, you can provide translated labels for 
-permissions to create a more localized experience for your international users.
+Shield supports multiple languages out of the box. When enabled, you can provide translated labels for
+permissions to create a more localized experience for your app's users.
 
 ### Configuration
 ```php
 'localization' => [
      'enabled' => false,
-     'key' => 'filament-shield::filament-shield',
+     'key' => 'shield-permissions', // could be any name you want
  ],
 ```
-### Key
-You can translate the permission labels by creating the translations files for your application's 
-supported locales following Laravel's localization conventions. The translation file can be 
-named anything you want. 
-For example, you can create a file named `permissions.php` per locale and then set the 
-`localization.key` in the config as `localization.key' => 'permissions'`. 
-
-Now given that Filament entities(Resources, Pages, Widgets) can be already localized using their own methods,
-you only need to provide translations for the resource prefixes, page and widget names, and any custom permissions you have defined. 
-For custom permissions, the keys will be the same as you define them, but in snake cased format.
-To get the list of keys that you need to provide translations for, you can run the following code snippet in Tinker or wherever you want:
 
-```php
-use BezhanSalleh\FilamentShield\Facades\FilamentShield;
+### How It Works
+
+Shield uses a **fallback chain** for resolving permission labels:
+
+1. **User's translation file** (when `localization.enabled = true`)
+   - Checks `lang/{locale}/{key}.php` where `{key}` is your configured localization key
+2. **Package's default translations**
+   - Falls back to `resource_permission_prefixes_labels` for standard affixes (view, create, update, etc.)
+3. **Headline fallback**
+   - Converts the key to a readable format (e.g., `force_delete_any` → "Force Delete Any")
 
-return collect(FilamentShield::getAllResourcePermissionsWithLabels())
-    ->keys()
-    ->transform(
-        fn($value) => str($value)
-            ->before(config("filament-shield.permissions.separator"))
-            ->snake()
-            ->toString()
-    )
-    ->merge(
-        collect(FilamentShield::getPages())
-            ->merge(FilamentShield::getWidgets())
-            ->flatMap->permissions->keys()
-            ->transform(
-                fn($value) => str($value)
-                    ->after(config("filament-shield.permissions.separator"))
-                    ->snake()
-                    ->toString()
-            )
-    )
-    ->merge(
-        collect(FilamentShield::getCustomPermissions())
-            ->keys()
-            ->transform(fn($value) => str($value)->snake()->toString())
-    )
-    ->unique()
-    ->values()
-    ->toArray();
+### Generating Translation Files
+
+The easiest way to create a translation file is using the `shield:translation` command:
+
+```bash
+php artisan shield:translation en --panel=admin
 ```
-**Example output:** running the above in the Filament Demo app context, with `custom_permissions` => ['Impersonate:User', 'View:IconLibrary'] will give you the following output:
+
+This generates a file at `lang/en/shield-permissions.php` containing all permission labels:
+
 ```php
-[
-    "view_any",
-    "view",
-    "create",
-    "update",
-    "delete",
-    "restore",
-    "force_delete",
-    "force_delete_any",
-    "restore_any",
-    "replicate",
-    "reorder",
-    "products_cluster",
-    "stats_overview_widget",
-    "orders_chart",
-    "customers_chart",
-    "latest_orders",
-    "impersonate:_user",
-    "view:_icon_library",
-]
+<?php
+
+/**
+ * Shield Permission Labels
+ *
+ * Translate the values below to localize permission labels in your application.
+ */
+
+return [
+    // Resource affixes
+    'create' => 'Create',
+    'delete' => 'Delete',
+    'delete_any' => 'Delete Any',
+    'force_delete' => 'Force Delete',
+    'force_delete_any' => 'Force Delete Any',
+    'replicate' => 'Replicate',
+    'reorder' => 'Reorder',
+    'restore' => 'Restore',
+    'restore_any' => 'Restore Any',
+    'update' => 'Update',
+    'view' => 'View',
+    'view_any' => 'View Any',
+
+    // Pages (permission key in snake_case)
+    'view_dashboard' => 'Dashboard',
+
+    // Widgets (permission key in snake_case)
+    'view_stats_overview' => 'Stats Overview',
+
+    // Custom permissions
+    'approve_posts' => 'Approve Posts',
+];
 ```
 
-### Default
-if you want to use the default translations provided by the package for the commonly used set of permissions for resources, you can set the `localization.key` in the config as `localization.key' => 'filament-shield::filament-shield.resource_permission_prefixes_labels'` and enable localization by setting `localization.enabled` to `true`.
+### Translation Keys
+
+All translation keys are in **snake_case** format:
+
+| Permission Type | Original Key | Translation Key |
+|-----------------|--------------|-----------------|
+| Resource affix | `viewAny` | `view_any` |
+| Resource affix | `forceDeleteAny` | `force_delete_any` |
+| Page permission | `view:Dashboard` | `view_dashboard` |
+| Widget permission | `view:StatsOverview` | `view_stats_overview` |
+| Custom permission | `Approve:Posts` | `approve_posts` |
+
+### Default Package Translations
+
+Shield includes translations for standard resource affixes in 32 languages. When `localization.enabled = false`,
+the package automatically uses these translations for affixes like `view`, `create`, `update`, `delete`, etc.
+
+For entity labels (Resources, Pages, Widgets), Filament's entity related methods are used
+(`getModelLabel()`, `getTitle()`, `getHeading()`, etc.).
+
 
 # Upgrade
 Upgrading from `3.x|4.0.0-Beta*` versions to 4.x requires careful consideration due to significant changes in the package's architecture and functionality. Here are the key steps and considerations for a successful upgrade:

src/Commands/Concerns/CanManipulateFiles.php

@@ -14,7 +14,7 @@ protected function checkForCollision(array $paths): bool
     {
         foreach ($paths as $path) {
             if ($this->fileExists($path)) {
-                $this->components->error($path . ' already exists, aborting.');
+                $this->components->warn($path . ' already exists, aborting.');
 
                 return true;
             }

src/Commands/SetupCommand.php

@@ -229,10 +229,11 @@ protected function manageMigrations(): void
             Schema::disableForeignKeyConstraints();
             DB::table('migrations')->where('migration', 'like', '%create_permission_tables')->delete();
             if (config('database.default') === 'pgsql') {
-                $this->getTables()->each(fn (string $table) => DB::statement("DROP TABLE IF EXISTS {$table} CASCADE"));
+                $this->getTables()->each(fn (string $table) => DB::statement(sprintf('DROP TABLE IF EXISTS %s CASCADE', $table)));
             } else {
-                $this->getTables()->each(fn (string $table) => DB::statement("DROP TABLE IF EXISTS {$table}"));
+                $this->getTables()->each(fn (string $table) => DB::statement('DROP TABLE IF EXISTS ' . $table));
             }
+
             Schema::enableForeignKeyConstraints();
         }
 

src/Commands/TranslationCommand.php

@@ -0,0 +1,165 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BezhanSalleh\FilamentShield\Commands;
+
+use BezhanSalleh\FilamentShield\Commands\Concerns\CanManipulateFiles;
+use BezhanSalleh\FilamentShield\Facades\FilamentShield;
+use BezhanSalleh\FilamentShield\Support\Utils;
+use Filament\Facades\Filament;
+use Illuminate\Console\Command;
+use Illuminate\Console\Prohibitable;
+use Illuminate\Contracts\Console\PromptsForMissingInput;
+use Illuminate\Support\Str;
+use Symfony\Component\Console\Attribute\AsCommand;
+
+use function Laravel\Prompts\confirm;
+use function Laravel\Prompts\select;
+use function Laravel\Prompts\text;
+
+#[AsCommand(name: 'shield:translation', description: 'Generate a translation file for permission labels for the given locale.')]
+class TranslationCommand extends Command implements PromptsForMissingInput
+{
+    use CanManipulateFiles;
+    use Prohibitable;
+
+    /** @var string */
+    public $signature = 'shield:translation
+        {locale : The locale to generate the file for}
+        {--panel= : Panel ID to get the permissions from}
+        {--path= : Custom path for the translations file}
+    ';
+
+    public function handle(): int
+    {
+        if ($this->isProhibited()) {
+            return Command::FAILURE;
+        }
+
+        $panel = $this->option('panel') ?: select(
+            label: 'Which panel do you want to generate permission translations for?',
+            options: collect(Filament::getPanels())->keys()->toArray()
+        );
+
+        Filament::setCurrentPanel(Filament::getPanel($panel));
+
+        $locale = $this->argument('locale');
+        $localizationKey = Utils::getConfig()->localization->key;
+
+        $defaultFilename = Str::of($localizationKey)->afterLast('::')->toString();
+        $defaultPath = lang_path(sprintf('%s/%s.php', $locale, $defaultFilename));
+
+        $path = $this->option('path') ?: text(
+            label: 'Where would you like to save the translations file?',
+            default: $defaultPath
+        );
+
+        $translations = $this->gatherPermissionLabels();
+
+        if ($this->checkForCollision([$path])) {
+            $confirmed = confirm('The file already exists. Do you want to overwrite it?', default: false);
+            if (! $confirmed) {
+                return Command::FAILURE;
+            }
+        }
+
+        $this->writeTranslationsFile($path, $translations);
+
+        $this->components->info('Translations file generated at: ' . $path);
+
+        return Command::SUCCESS;
+    }
+
+    protected function gatherPermissionLabels(): array
+    {
+        $translations = [];
+
+        // Resource permission affixes (view, view_any, create, update, delete, etc.)
+        $this->gatherAffixLabels($translations);
+
+        // Page permissions (snake_case of permission key)
+        $this->gatherPageLabels($translations);
+
+        // Widget permissions (snake_case of permission key)
+        $this->gatherWidgetLabels($translations);
+
+        // Custom permissions (snake_case of permission key)
+        $this->gatherCustomPermissionLabels($translations);
+
+        ksort($translations);
+
+        return $translations;
+    }
+
+    protected function gatherAffixLabels(array &$translations): void
+    {
+        $resources = FilamentShield::getResources() ?? [];
+
+        $affixes = collect($resources)
+            ->flatMap(fn (array $resource): array => array_keys($resource['permissions']))
+            ->unique()
+            ->values()
+            ->toArray();
+
+        foreach ($affixes as $affix) {
+            $localizationKey = Utils::toLocalizationKey($affix);
+            $translations[$localizationKey] = FilamentShield::getAffixLabel($affix);
+        }
+    }
+
+    protected function gatherPageLabels(array &$translations): void
+    {
+        $pages = FilamentShield::getPages() ?? [];
+
+        foreach ($pages as $page) {
+            foreach ($page['permissions'] as $key => $label) {
+                $localizationKey = Utils::toLocalizationKey($key);
+                $translations[$localizationKey] = $label;
+            }
+        }
+    }
+
+    protected function gatherWidgetLabels(array &$translations): void
+    {
+        $widgets = FilamentShield::getWidgets() ?? [];
+
+        foreach ($widgets as $widget) {
+            foreach ($widget['permissions'] as $key => $label) {
+                $localizationKey = Utils::toLocalizationKey($key);
+                $translations[$localizationKey] = $label;
+            }
+        }
+    }
+
+    protected function gatherCustomPermissionLabels(array &$translations): void
+    {
+        $customPermissions = FilamentShield::getCustomPermissions() ?? [];
+
+        foreach ($customPermissions as $key => $label) {
+            $localizationKey = Utils::toLocalizationKey($key);
+            $translations[$localizationKey] = $label;
+        }
+    }
+
+    protected function writeTranslationsFile(string $path, array $translations): void
+    {
+        $content = "<?php\n\n";
+        $content .= "/**\n";
+        $content .= " * Shield Permission Labels\n";
+        $content .= " *\n";
+        $content .= " * Translate the values below to localize permission labels in your application.\n";
+        $content .= " */\n\n";
+        $content .= "return [\n";
+
+        foreach ($translations as $key => $label) {
+            $escapedKey = addslashes((string) $key);
+            $escapedLabel = addslashes((string) $label);
+            $content .= "    '{$escapedKey}' => '{$escapedLabel}',\n";
+        }
+
+        $content .= "];\n";
+
+        $this->writeFile($path, $content);
+    }
+}

src/Concerns/HasEntityTransformers.php

@@ -68,20 +68,19 @@ public function transformWidgets(): ?array
             ->toArray();
     }
 
-    /**
-     * @return array<string, string>|null
-     */
-    public function transformCustomPermissions(bool $localizedOrFormatted = false): ?array
+    /** @return array<string, string> */
+    public function transformCustomPermissions(bool $localized = false): ?array
     {
-        $config = Utils::getConfig();
+        $permissionCase = Utils::getConfig()->permissions->case;
 
-        return collect($config->custom_permissions)
-            ->mapWithKeys(function (string $label, int | string $key) use ($config, $localizedOrFormatted): array {
+        return collect(Utils::getConfig()->custom_permissions)
+            ->mapWithKeys(function (string $label, int | string $key) use ($localized, $permissionCase): array {
                 $permission = is_numeric($key) ? $label : $key;
+                $configLabel = is_numeric($key) ? null : $label;
 
                 return [
-                    $this->format($config->permissions->case, $permission) => $localizedOrFormatted
-                        ? $this->getPermissionLabel($permission)
+                    $this->format($permissionCase, $permission) => $localized
+                        ? $this->getCustomPermissionLabel($permission, $configLabel)
                         : Str::of($label)->headline()->toString(),
                 ];
             })