Moonshine Laravel Package

Getting Started

Minimal Steps

1. Installation Run composer require laravel-lang/moonshine --dev in your project root. Ensure your project uses MoonShine v4+ (verified via release notes).

2. Update Translations Execute php artisan lang:update to sync all available locales (e.g., en, es, ru, ja). This populates resources/lang/vendor/moonshine/ with translation files.

3. First Use Case

   • Localize MoonShine UI: Set your app’s locale (e.g., config/app.php):

     'locale' => 'es', // Spanish translations will now apply to MoonShine components.
     

   • Verify: Refresh your MoonShine admin panel; UI labels (buttons, tables, modals) should reflect the new language.

Where to Look First

• Translation Files: Browse resources/lang/vendor/moonshine/ for locale-specific keys (e.g., moonshine::buttons.save).
• MoonShine Docs: Refer to MoonShine’s localization guide for key references.
• Package Releases: Check releases for MoonShine v4 compatibility notes (e.g., #608).

Implementation Patterns

Core Workflows

1. Adding New Locales

   • Manual Addition: Copy en.json to a new locale (e.g., resources/lang/vendor/moonshine/fr.json) and translate keys.
   • Machine Translations: Run php artisan lang:update to auto-generate translations for unsupported locales (e.g., sw, ur). Note: Machine translations may require manual review (see Gotchas).

2. Overriding Default Translations

   • Per-Locale Overrides: Create a custom translation file in resources/lang/{locale}/moonshine.php:

     return [
         'buttons' => [
             'save' => 'Guardar cambios', // Overrides Spanish 'save' button
         ],
     ];
     

   • Global Overrides: Publish the package’s translations:

     php artisan vendor:publish --provider="LaravelLang\MoonShine\MoonShineServiceProvider" --tag="moonshine-translations"
     

     Then edit config/moonshine.php to customize default keys.

3. Dynamic Locale Switching

   • Use MoonShine’s built-in locale selector (if configured) or manually set the locale in your app:

     app()->setLocale(request('locale')); // e.g., via a route parameter
     

Integration Tips

• MoonShine Plugins: Ensure plugins (e.g., moonshine-table, moonshine-form) are compatible with your MoonShine version. Test after lang:update.
• Fallback Locale: Configure config/app.php to fall back to English:

  'fallback_locale' => 'en',
  

• Testing: Use Laravel’s trans() helper to verify translations in Blade:

  {{ trans('moonshine::buttons.cancel') }}
  

Gotchas and Tips

Pitfalls

1. MoonShine Version Mismatch

   • Issue: Running lang:update on MoonShine v3 with this package may break UI strings (keys differ between v3/v4).
   • Fix: Upgrade MoonShine to v4+ before installing the package. Check release notes for key changes.

2. Machine Translation Quality

   • Issue: Auto-generated translations (e.g., for ak, ln) may contain errors or awkward phrasing.
   • Fix: Review translations in resources/lang/vendor/moonshine/{locale}.json and manually correct keys like:

     "buttons": {
         "save": "Simpan" // Auto-translated to "Save" → corrected to Indonesian
     }
     

3. Missing Keys

   • Issue: New MoonShine releases may introduce UI strings not covered by the package.
   • Fix:
     • Check the MoonShine source for new keys.
     • Add missing keys to your locale files or request updates via GitHub Issues.

4. Caching

   • Issue: Translations may not update immediately due to Laravel’s view caching.
   • Fix: Clear caches after lang:update:

     php artisan view:clear
     php artisan cache:clear
     

Debugging Tips

• Log Missing Keys: Enable Laravel’s translation logging in config/app.php:

  'debug' => env('APP_DEBUG', true),
  

  Missing keys will appear in logs (e.g., translation missing: moonshine::tables.no_results).

• Key Reference: Use MoonShine’s Blade components to find the correct translation key for a UI element (e.g., moonshine-table::no_results).

Extension Points

1. Custom Translation Sources

   • Extend the package by publishing translations and modifying the provider:

     // app/Providers/MoonShineTranslationServiceProvider.php
     use LaravelLang\MoonShine\MoonShineServiceProvider;
     
     class MoonShineTranslationServiceProvider extends MoonShineServiceProvider {
         public function register() {
             $this->mergeConfigFrom(__DIR__.'/../config/moonshine.php', 'moonshine');
             $this->loadTranslationsFrom(__DIR__.'/../lang', 'moonshine');
         }
     }
     

2. Locale-Specific Plugins

   • Override plugin translations by extending the moonshine namespace in your locale files:

     return [
         'plugins' => [
             'table' => [
                 'actions' => [
                     'edit' => 'Editar registro', // Overrides table edit button
                 ],
             ],
         ],
     ];
     

3. Dynamic Translation Loading

   • Load translations on-demand for large apps:

     // In a service provider
     app()->loadLanguageFiles(app()->getLocale());