v3.8: The Reliability & Quality Update

Release Notes

This release builds directly on the foundation of the "Enterprise Edition" (v3.7) by focusing on rock-solid reliability, output quality, and cross-platform compatibility. We've eliminated annoying placeholders, fixed critical output bugs, and ensured the tool works flawlessly for Windows and CI/CD users.

TL;DR: The tool is now automation-friendly and diff-friendly. It skips interactive prompts in CI/CD, guarantees stable file sorting, and hardens the AI integration with intelligent fallbacks.

---

🚀 Key Enhancements

✨ New: Intelligent Fallbacks - No More "NEEDS TRANSLATION"!

The most requested improvement is here. If the AI fails to return a translation, the system now intelligently falls back to the known en source text or the key itself. Your generated files are always usable and ready for review, not filled with useless placeholders.

🧠 New: Hyper-Strict AI Prompting Engine

The prompt sent to Gemini has been re-engineered with a stricter rule set. This resolves a critical bug where the AI would create nested objects in JSON files. All JSON output is now guaranteed to be flat and valid.

💅 New: Deterministic PHP Arrays with Recursive Sorting

Generated PHP translation files are now sorted recursively. This ensures that not only top-level keys but also all nested array keys are sorted alphabetically, leading to clean, stable, and minimal diffs in your version control.

✅ New: Full Windows & CI/CD Compatibility

The tool now detects non-interactive environments (like GitHub Actions, Docker) and automatically proceeds without hanging on prompts. It also includes a dedicated, functional prompt for Windows users, ensuring a smooth experience for everyone.

---

⚠️ Breaking Changes & Upgrade Guide

Please read these notes carefully before upgrading.

1. Default Languages Changed to en

The --langs option now defaults to en only (previously en,ru,uz) to prevent accidental multi-language runs.

• Action Required: If you rely on multiple locales, you must now pass them explicitly:

  php artisan translations:extract-and-generate --langs=en,ru,uz

2. Deterministic Sorting May Reorder Arrays

The new recursive sorting will likely reorder nested arrays in your existing PHP language files.

• Action Required: Expect a one-time, larger-than-usual diff in your language files after the first run. This is expected and will lead to much cleaner diffs in the future.

3. Update Banner Text

• Action Required: Remember to update the version number in the showWelcome() method from (v3.7) to (v3.8) for consistency.

---

Full Changelog

Click to expand for detailed changes

• New: ksortRecursive() method added and implemented when writing PHP language files.
• New: Robust detection of non-interactive and Windows environments in promptForMultiChoice().
• Improved: The AI fallback logic in staticStructureTranslationsFromGemini() now uses the $sourceTextMap instead of generating placeholders.
• Improved: The AI prompt in staticTranslateKeysWithGemini() is now much stricter to enforce flat JSON and improve consistency.
• Fixed: The framework language loader in loadFrameworkTranslations() now safely iterates files and filters by extension.
• Fixed: Parallel tasks now explicitly capture the $sourceTextMap to ensure correct fallbacks in fork mode.
• Changed: The default value for the --langs option in the command signature is now en.

v3.7: The Enterprise Edition - Full Module Support & AI-First Engine

This release transforms the tool into an enterprise-grade utility, introducing comprehensive support for modular applications and a complete overhaul of the AI translation engine for superior accuracy and reliability. This is the most significant update yet, addressing core architectural limitations and delivering the features needed for complex, modern Laravel projects.

✨ Key Features & Enhancements

🧩 Full Module Support & Control (nwidart/laravel-modules)

The tool is now fully aware of modular architectures, with new features and critical fixes for robust handling.

• Automatic Detection: Automatically discovers all enabled nwidart modules.
• Interactive Target Selection: Prompts you to choose which targets to scan—the main application, specific modules, or everything at once.
• Encapsulated Translations (Default): Correctly reads from and writes to the lang directory within each module (Modules/YourModule/lang/), keeping your translations perfectly organized.
• ✨ New - Translation Consolidation: You can now choose to consolidate all module translations into the main application's lang/ directory. This is offered as an interactive prompt or can be forced with the --consolidate-modules flag.
• 🐛 Fixed - Scan Isolation: Fixed a critical bug where scanning the "Main Application" would incorrectly include files from module directories ("leaky scans"). Scans are now properly isolated.

🤖 New "AI-First" Translation Engine

We've completely re-architected the way we interact with the AI, eliminating a whole class of bugs and dramatically improving translation quality.

• Intelligent AI Prompting: The tool no longer tries to guess the source text. It now sends raw keys (like auth.failed or "Save Changes") directly to Gemini with a new, advanced prompt that instructs the AI on how to interpret them based on Laravel conventions.
• Fixes Incorrect Translations: This solves the critical bug where new keys were being translated with the key itself as the value (e.g., 'welcome' => 'messages.welcome').

🧠 Smarter Key & File Handling

The logic for identifying and grouping keys has been made far more robust.

• Context-Aware Grouping: The tool now tracks the origin of every key, ensuring that a key found in the Settings module is correctly associated with the Settings module's translation files.
• Handles Complex Keys: The scanner now correctly identifies full-sentence keys as belonging to JSON files, fixing a bug where it would create incorrect .php files from sentence-like strings.
• Fixes "0 Keys Processed" Bug: The key-to-file mapping logic has been rewritten to correctly assign all discovered keys to your selected files.

🔌 True Offline Mode

If the GEMINI_API_KEY is not set, the tool now enters a dedicated Offline Mode, generating placeholder files with the key as the value. This is perfect for initial setup or working without an internet connection.

v2.7 - Context-Aware AI Translations

✨ New Feature: Context-Aware Translations with --context

You can now use the optional --context flag to provide a short description of your project directly to the AI. This is crucial for applications in domains like finance, healthcare, legal, or any field with specialized vocabulary.

How it works:
The command injects your description into the AI prompt, helping it understand the specific meaning of ambiguous words.

Example: Financial Application
Without context, the AI might translate "position" as a physical location. With context, it understands it as a financial holding.

# NEW: Provide context for a financial trading platform
php artisan translations:extract-and-generate --context="A SaaS platform for financial trading of stocks. Terms like 'position' and 'security' refer to financial concepts."

This update makes the translator significantly more robust and intelligent, ensuring higher-quality translations and a smoother developer experience.