Actions Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require laravel-lang/actions
   

   The package auto-registers with Laravel’s translation system—no manual configuration is needed.

2. First Use Case Access translations via Laravel’s __() helper or trans() function:

   // Basic action (e.g., "Save")
   echo __('actions.save');
   
   // Dynamic with placeholder (e.g., "Delete User")
   echo __('actions.delete', ['name' => 'User']);
   

3. Where to Look First

   • Documentation: laravel-lang.com/packages-actions.html (covers all keys and usage).
   • Source: github.com/laravel-lang/actions (browse resources/lang/ for locale-specific files).
   • Default Keys: Run php artisan lang:list actions (if using Laravel Lang’s CLI tools) to list all available keys.

Implementation Patterns

Core Workflows

1. Blade Integration Use in buttons, links, or tooltips:

   <button type="submit">
       {{ __('actions.submit') }}
   </button>
   

   Dynamic Context:

   <a href="{{ route('users.destroy', $user) }}">
       {{ __('actions.delete', ['name' => $user->name]) }}
   </a>
   

2. Form Actions Leverage for CRUD operations:

   // In a Form Request or Controller
   return redirect()->route('posts.index')->with('success', __('actions.created'));
   

3. API Responses Return localized messages:

   return response()->json(['message' => __('actions.updated')]);
   

4. JavaScript Localization Publish translations to JS:

   php artisan vendor:publish --tag=laravel-lang-actions
   

   Then use in Vue/React:

   const messages = @json(__('actions'));
   

Advanced Patterns

1. Custom Placeholders Extend with your own variables:

   __('actions.custom_action', [
       'count' => $items->count(),
       'resource' => 'Posts',
   ]);
   

2. Conditional Translations Use Laravel’s trans_choice for pluralization:

   __('actions.items', ['count' => $count]); // "1 item" or "X items"
   

3. Fallback Handling Override defaults in resources/lang/{locale}/actions.php:

   return [
       'save' => 'Guardar cambios', // Spanish override
   ];
   

4. Testing Mock translations in tests:

   $this->app->setLocale('es');
   $this->assertEquals('Guardar cambios', __('actions.save'));
   

Gotchas and Tips

Pitfalls

1. Missing Keys

   • Issue: Using a key not in the package (e.g., __('actions.unknown')).
   • Fix: Check the documentation or run php artisan lang:list actions to verify available keys.
   • Workaround: Add a fallback in config/app.php:

     'fallback_locale' => 'en',
     

2. Placeholder Syntax

   • Issue: Forgetting to pass required placeholders (e.g., __('actions.delete') without ['name']).
   • Fix: Review the translation strings in resources/lang/en/actions.php for required variables.

3. Locale-Specific Quirks

   • Example: Dutch (nl) translations may use ZWSP (Zero-Width Space) characters, which can cause rendering issues in some UI frameworks.
   • Fix: Strip whitespace if needed:

     trim(__('actions.some_key'));
     

4. Caching

   • Issue: Translations not updating after changes.
   • Fix: Clear the view cache:

     php artisan view:clear
     php artisan config:clear
     

Debugging Tips

1. Inspect Translations Dump a translation to debug:

   dd(__('actions.save')); // Check for unexpected characters/placeholders
   

2. Check Loaded Locales Verify the active locale:

   dd(app()->getLocale()); // Should match your expected language
   

3. Override Machine Translations Machine-translated locales (e.g., sa, ug) may be less accurate. Override them in your project’s resources/lang/:

   // resources/lang/sa/actions.php
   return ['save' => 'حفظ']; // Manual Arabic override
   

Extension Points

1. Add New Locales Copy an existing locale file (e.g., en/actions.php) and translate it for your language. Place it in resources/lang/{locale}/actions.php.

2. Custom Action Keys Extend the package by publishing and modifying the translations:

   php artisan vendor:publish --tag=laravel-lang-actions --force
   

   Then edit config/laravel-lang/actions.php or override in your project.

3. Integration with Laravel Lang If using other Laravel Lang packages (e.g., laravel-lang/core), ensure consistent locale handling across packages.

4. CI/CD Considerations

   • Testing: Test translations in CI by setting the locale:

     $this->app->setLocale('fr');
     

   • Updates: Monitor the release notes for breaking changes in new versions.