Sylius Gemini Local Translate Plugin Laravel Package

Getting Started

Minimal Steps

1. Verify Chrome Compatibility:

   • Ensure Chrome 127+ is installed.
   • Enable Prompt API for Gemini Nano via chrome://flags/#prompt-api-for-gemini-nano.
   • Download the Gemini Nano model (chrome://components).

2. Installation:

   composer require barth/sylius-gemini-local-translate-plugin
   yarn install --force
   yarn build
   

3. Symfony Setup:

   • The bundle auto-registers via Symfony Flex. If not, add to config/bundles.php:

     Barth\SyliusGeminiLocalTranslatePlugin\BarthSyliusGeminiLocalTranslatePlugin::class => ['all' => true],
     

   • Register routes in config/routes.yaml:

     barth_gemini_local_translate_plugin:
         resource: "@BarthSyliusGeminiLocalTranslatePlugin/config/routes/admin_routing.yaml"
     

4. First Use Case:

   • Navigate to any translatable field in the Sylius admin panel (e.g., product names, descriptions).
   • Select a target language and tone (e.g., formal, casual).
   • Click the "Translate" button to generate translations via Chrome’s local Gemini Nano model.

Implementation Patterns

Workflows

1. Translation Workflow:

   • Select Field: Click on any translatable field in Sylius admin.
   • Language/Tone Selection: Choose target language and tone (e.g., "Formal" for professional contexts).
   • Trigger Translation: Click the "Translate" button. The plugin:
     • Extracts the field content.
     • Sends it to Chrome’s Prompt API for local inference.
     • Replaces the field value with the translated result.
   • Review: Manually verify the translation before saving (critical for accuracy).

2. Bulk Translation:

   • Use the plugin for multiple fields sequentially (e.g., translate all product descriptions in a batch).
   • Combine with Sylius’s bulk edit features for efficiency.

3. Integration with Custom Fields:

   • For custom translatable fields, add the translation button via Twig hooks (see Add to Custom Fields).
   • Example hook in config/packages/sylius_twig.yaml:

     sylius_twig_hooks:
       hooks:
         'sylius_admin.my_entity.create.content.sections.form.translations':
           gemini_translate_button:
             template: '@BarthSyliusGeminiLocalTranslatePlugin/admin/form/translations/button.html.twig'
             priority: -10
     

Tips for Daily Use

• Batch Processing: Translate multiple fields in one session to avoid repeated API calls.
• Tone Consistency: Stick to one tone (e.g., "Formal") for brand consistency across translations.
• Fallback Workflow: If translations are inaccurate, manually edit or use a secondary translation tool.

Gotchas and Tips

Pitfalls

1. Chrome Dependency:

   • Prompt API Unavailable: If the /admin/gemini-local-translate-plugin/diagnostic route returns an error, ensure:
     • Chrome is updated to 127+.
     • The Prompt API for Gemini Nano flag is enabled.
     • The Gemini Nano model is downloaded (chrome://components).
   • Workaround: Use a different browser or device if Chrome compatibility is an issue.

2. Translation Accuracy:

   • AI Limitations: Gemini Nano may produce errors (e.g., incorrect terminology, tone mismatches).
   • Mitigation: Always review translations before saving. Use the plugin as a starting point, not a final output.

3. Custom Field Visibility:

   • Missing Buttons: If the translate button doesn’t appear on custom fields, ensure the Twig hook is correctly configured (see Add to Custom Fields).
   • Debugging: Check the Twig template path and hook priority in sylius_twig_hooks.

4. Performance:

   • Local Processing: Translations run on-device, so performance depends on Chrome’s Prompt API speed. Avoid overloading with very long texts.

Debugging

• Diagnostic Route: Use /admin/gemini-local-translate-plugin/diagnostic to verify Chrome API availability.
• Browser Console: Check for errors in Chrome DevTools (F12) if the translate button fails to load.
• Symfony Logs: Enable debug mode (APP_DEBUG=true) to log plugin-related issues.

Extension Points

1. Custom Templates:

   • Override the button template (button.html.twig) to match your admin theme.
   • Example: Copy from vendor/barth/sylius-gemini-local-translate-plugin/templates/admin/form/translations/button.html.twig to templates/admin/barth_gemini_local_translate/button.html.twig.

2. Language/Tone Extensions:

   • Extend the available languages or tones by modifying the plugin’s JavaScript (e.g., assets/js/admin.js).
   • Submit changes upstream or fork the plugin for customizations.

3. Event Listeners:

   • Hook into Sylius events (e.g., sylius.entity.translation.updated) to log or validate translations post-generation.

Configuration Quirks

• Yarn Build: Always run yarn build after installation or dependency updates to ensure frontend assets are compiled.
• Caching: Clear Symfony cache (php bin/console cache:clear) if the plugin behaves unexpectedly after updates.