CHANGELOG.md

Changelog

All notable changes to this project will be documented in this file.

v5.1.1 - 2026-08-28

Everything below is new since v5.1.0.

🔧 Refactoring & Modernization

• JavaScript Code Quality Tooling: Introduced new JS development configurations including package.json, package-lock.json, eslint.config.js, .prettierrc, and .prettierignore to format and lint Blade-embedded JS and stylesheets (these files were not present in v5.1.0). The accompanying npm run modernize script is written in pure Node.js to run natively on Windows, macOS, and Linux out-of-the-box, without requiring any external tools (such as xargs or ripgrep).
• PHP 8.3 standard features: Integrated #[Override] attribute annotations on service providers.
• Optimized Laravel error wrappers: Replaced conventional if/throw blocks with native, optimized Laravel helper wrappers (throw_if and throw_unless) across commands and runners to lower overhead.
• Refined types & validation: Eliminated redundant variables/type validation checks, such as is_object checks on container-resolved objects and redundant isset/is_string POSIX array validations.
• Removed useless casts: Cleaned up redundant (string) casts on file retrieve statements (File::get) across the test suite.

🐛 Fixed & Cross-Platform Reliability

• Framework & Testing Robustness:
  • Fixed test runner failures on newer Laravel/Testbench versions by adding a package-root vendor folder fallback for missing framework language catalogs.
  • Refined vendor path checks (isComposerVendorPath) to correctly bypass Testbench dummy application paths, preventing false positives during testing.
  • Embedded a default APP_KEY environment setup in phpunit.xml to allow executing test suites out-of-the-box.

v5.1.0 - 2026-08-14

Everything below is new since v5.0.1.

⭐ Added

• Translation Manager at /translations-manager (prefix, enable flag, and middleware are configurable). Routes and JSON APIs register automatically: data, languages, existing map, scan, save, add-languages. Guests must sign in when the host already has login/register/sign-in routes (browser redirect or JSON 401 + unauthenticated view). If the host has no auth routes, the manager is open. Publish tags: gemini-translator-config, gemini-translator-views, gemini-translator-assets, gemini-translator-manager. ManagerViewComposer inlines CSS/JS so the page works without publishing assets. Optional @include('gemini-translator::partials.workspace') for an existing layout. Writes name the PHP process user in errors (not a hard-coded www-data). Add-languages continues if one lang tree writes and another is not writable.
• Manager UI: semantic component CSS (no Tailwind/Bootstrap utilities), native <dialog> / <search> / popover, light/dark theme (localStorage key gemini-translator-theme), sticky KEY column, pagination footer (default 5 rows, last two pages always visible with an ellipsis; pager labels are not taken from lang/{locale}/pagination.php), Type / Module / Pack / Scope / PHP-files / Language / “show only missing” / Highlight script faults filters, Add Languages, Sync, Save. Checkboxes use a ✓ mark on the monochromatic tokens (sun stays yellow, Save stays green).
• Manager script-fault highlighter: optional checkbox (off by default, stored as gemini-translator-malform-detector). Uses LocaleHelper::detectorCatalog() / malformReasons(). Flags letters that do not belong to the cell’s locale — including Latin inside Gujarati/Hindi/etc. Placeholders (:name, {0}, [2,*]) and Common marks (danda ।) are ignored. Faulty editors get an amber outline/background and a tooltip of the unexpected scripts. Stricter than the CLI hasDisallowedScript() check, which still allows Latin in native scripts.
• Lang packs (manager + CLI): extra folders such as lang/app3/ and lang/web/ are first-class trees, separate from lang/. A 2–3 letter folder name (web) is a pack when it holds locale JSON or locale dirs, not a locale. Nested PHP such as foo/bar.php stays on the root pack unless the first segment is a known pack. The manager Pack filter appears only after you select a module (or Non-module) that actually has more than one pack. PHP file pickers list files from the selected pack. A selected language lists only keys that exist in that locale file.
• Registered / published lang paths: the manager also scans loadJsonTranslationsFrom() / loadTranslationsFrom() directories (for example base_path('custom_dir')) and published resources/lang/modules/{name} (published copy wins on the same key). Composer vendor/ lang trees are skipped.
• CLI pack step: after you pick a module that has extra lang folders, translations:extract-and-generate asks which packs to process. The JSON/PHP file list is then limited to those packs. Modules with only lang/ skip the prompt. Pack PHP files load and write as lang/{pack}/{locale}/messages.php.
• 249-language catalog (LanguageCatalog) with display names and fallbacks (zh → zh_CN, pt → pt_BR, pa → pa_GURU, and similar). Short file codes still resolve to the primary variant.
• Multi-OS adapter layer: PromptInterface and TaskRunnerInterface via PlatformFactory on PHP_OS_FAMILY
  • Unix: Laravel Prompts + spatie/fork (pcntl)
  • Windows: isolated kernel32.dll FFI console binder + Symfony Process workers
  • Sequential sync runner on every OS, with cooperative stop
• --driver=process: concurrent Symfony Process workers (also used when --driver=fork is selected on Windows)
• Hidden translations:run-payload worker command for Windows/process child jobs
• Suggested extensions: ext-pcntl (fork) and ext-ffi (native Windows menus)
• --refresh-clean: rebuild existing keys only, ignoring stale file wording. Official Laravel English is the source for auth / pagination / passwords / validation (not ucwords of the key)
• Dated Gemini quota snapshot in publishable config/gemini-translator.php (as of 2026-08-13). Add, raise, lower, zero, or remove rows when Google changes RPM/RPD. 0 RPM/RPD is “no free-tier budget”, not a crash. GEMINI_TRANSLATOR_APPLY_FREE_TIER_CAPS can turn snapshot caps off
• Configurable Gemini model: --model=, GEMINI_MODEL / GEMINI_TRANSLATOR_MODEL, then config/gemini-translator.php, then config('gemini.model'), then the package default. Paid/ListModels ids are allowed and are not free-tier capped unless listed in the snapshot
• Per-locale writing-system map on LocaleHelper (Unicode sc= so shared danda । is Common, not a mix) plus looksUntranslated / disallowed-script checks that reduce mixed-script output (they do not eliminate it). Map now includes Tibetan, N’Ko, Tifinagh, Ol Chiki, Meitei, Canadian Aboriginal, extra Devanagari/Cyrillic/Arabic catalog codes, and script tags (_latn, _cyrl, _arab, _deva, _guru, _hans/_hant, _tfng, _olck, _syll)

🔧 Changed

• Interactive prompts and parallel execution go through the platform factory instead of branching on PHP_OS_FAMILY inside the command/services
• --driver=fork on Windows runs Process workers instead of silently falling back to sync
• Windows FFI menus match Laravel Prompts (boxed list, checkboxes, arrows, space, enter). Process workers match fork: ordered results, inherited env, no cooperative mid-flight stop, same progress UX
• --refresh is the original refresh again: existing keys only, current file wording is the source
• Default Gemini model is gemini-3.5-flash-lite (15 RPM / 500 RPD in the snapshot and present in ListModels). Snapshot rows for ids missing from ListModels (gemini-2.5-flash-exp, gemini-3-flash) were removed
• JSON writes keep dotted PHP-style keys (messages.welcome, validation.required) when that group is selected. Blank literal JSON values are filled from the key; empty/whitespace source is treated as missing
• Translation prompts include source text and checks that reduce mixed-script, leftover-English, placeholder, and plural-token drift. Detected bad output falls back to source. The checks do not catch every mixed or off-language row
• Command summary records processed_chunks from the translation runner
• CLI file picker labels pack PHP as lang/{pack}/{file}.php
• CLI writing-system check reduces mixed-script Gemini output (Gujarati + Kannada ೋ, Hindi + Gujarati, leftover English in Indic locales). It does not eliminate those cases; some mixed or leftover-English rows can still be written

🐛 Fixed

• JSON-only file selection no longer treats file.subkey keys that belong to a PHP lang group as JSON keys when that PHP group is also in play
• Selecting a single CLI file group returns that file (it previously returned array_keys of a list)

📚 Tests

• Suite covers the manager routes/views/auth, language catalog, script guard, malform detector catalog, model resolution, refresh source map, platform factory, Windows process runner, pack discovery, pack PHP I/O, and pack CLI prompts

v5.0.1 - 2026-04-27

⭐ Added

• driftingly/rector-laravel plus rector:dry / rector:debug composer scripts

🔧 Changed

• Rector Laravel rule sets and composer-based versioning; auto-imports and unused-import cleanup (Sleep::usleep(), sprintf(), strict comparisons)

v5.0.0 - 2026-04-27

⚠ BREAKING CHANGES

• PHP 8.3 Required: Minimum PHP version bumped from 8.2 to 8.3 (required for Laravel 13 support)
• Strict Typing: Added declare(strict_types=1) to all PHP files for type safety

⭐ Added

• Laravel 13 Support: Full compatibility with Laravel 13.x
• Comprehensive Test Suite: Added 37 tests with 110 assertions using Orchestra Testbench
  • Unit tests for LocaleHelper and TextHelper utilities
  • Feature tests for CommandRegistration, ServiceProvider, ScannerService, and FileSystemService
• Code Quality Tools: Integrated PHPStan (level 5), Laravel Pint, and Rector
• Type Safety: Strict type declarations and explicit type casting throughout codebase

🔧 Changed

• Strict Comparisons: Replaced empty() with explicit array/string comparisons (=== [], !== [])
• Strict in_array(): Added true parameter for strict type checking
• Command Options: Added explicit (int) casts for chunk-size, retry-delay, and concurrency options
• Removed Unused Code: Cleaned up 3 unused class constants (ALL_FILES_KEY, ALL_TARGETS_KEY, FILE_KEY_SEPARATOR)

🐛 Fixed

• Runtime Type Errors: Fixed usleep() calls to use int instead of float
• Type Safety: Fixed all PHPStan level 5 errors across the codebase

v4.0.2 - 2026-03-19

🐛 Fixed

• JSON-Only File Selection Integrity
  • Fixed unintended creation of locale directories (lang/{locale}) during JSON-only runs.
  • Fixed unintended framework PHP file publication (auth.php, pagination.php, passwords.php, validation.php) when only JSON File (*.json) groups are selected.
  • Framework/vendor translation keys are still loaded and available for JSON output (en.json, hi.json, etc.) without forcing PHP file creation.
  • PHP locale directories and files are now created only when PHP file groups are actually selected for processing.

v4.0.1 - 2025-11-24

🐛 Fixed

• Translation Service
  • Added automatic filtering of empty and whitespace-only translation keys before AI processing
  • Prevents "Syntax error" from Gemini API when empty string keys are present in language files
  • Empty keys are now filtered at two points: in buildTranslationTasks() and staticTranslateKeysWithGemini()

🚀 Performance

• Intelligent Chunk Sizing
  • Added automatic chunk size reduction for extremely long translation keys
  • Keys with average length > 80 characters now limited to max 3 keys per chunk
  • Keys with average length > 60 characters now limited to max 5 keys per chunk
  • Significantly improves success rate for complex validation attribute keys

🔧 Changed

• Error Logging
  • Enhanced error logging to capture raw Gemini API responses on final retry attempt
  • Logs now include truncated API response text for easier debugging
  • Helps diagnose "Syntax error" and other API-related failures

📚 Documentation

• Added critical warning about config/gemini.php type casting requirement
• Added troubleshooting guide for "Configuration value must be an integer" error with solution
• Created comprehensive troubleshooting reference covering configuration errors, rate limiting, and API connectivity
• Documented v4.0.1+ automatic features (empty key filtering, intelligent chunking)

v4.0.0 - 2025-11-23

⚠ BREAKING CHANGES

• Removed deprecated --source option in favor of interactive target selection
• Removed --no-advanced pattern detection option
• Default behavior now canonicalizes language codes using LocaleHelper
• Dry-run mode added - no files written when --dry-run is used

⭐ Added

• New Operational Modes

  • --refresh flag: Re-translate only existing keys from language directories; do NOT generate translations for new/missing keys
  • --dry-run flag: Run full extraction + mapping but show what files would be modified without writing anything
  • --concurrency=N option: Configure number of concurrent processes when using fork driver (defaults to 15)

• Enhanced Locale & Translation Quality

  • Added LocaleHelper utility class with locale canonicalization, script type detection, and humanization rules
  • Support for proper title case vs sentence case based on target language (English uses title case, other Latin languages use sentence case)
  • Script-aware placeholder validation with count checking instead of just presence
  • Pluralization string detection that operates on source text instead of keys
  • Advanced key humanization with namespaced key display extraction
  • Enhanced looksMachineKey() detection with comprehensive pattern matching for PascalCase, snake_case, kebab-case, and dot.notation
  • Optimized looksMachineKey() with fast-path checks for common patterns combined with robust regex validation

• Framework Integration

  • Added automatic Laravel framework translation bootstrapping that syncs vendor language files to app lang directory
  • Framework translations are merged with app overrides and updated only when new keys are added

• New Extractor Features

  • Support for Vue/Alpine bound attributes (:v-t, :x-text, v-bind:v-t, v-bind:x-text)
  • Multi-line string extraction support with /s (PCRE_DOTALL) modifier
  • Backtick string extraction support
  • Function call extraction from attribute values (e.g., x-text="__('messages.hello')")

• AI Translation Improvements

  • Implemented system instructions separation using withSystemInstruction() from Gemini PHP SDK v2.0
  • Static rules and role definitions now isolated from dynamic query content
  • Enhanced language strictness with multiple validation checkpoints in prompts
  • Improved AI consistency by clearly distinguishing between role/rules and translation tasks

🔧 Changed

• Command Signature

  • Removed deprecated --source option
  • Removed --no-advanced option
  • Renamed description of --langs to clarify English is used as source
  • Added descriptions for new options

• Translation Flow

  • Converted from 2-phase to 3-phase system (Full Sync, Missing-only, Refresh-only)
  • Mode validation: Users can no longer use --refresh and --skip-existing together
  • All language codes are now canonicalized using LocaleHelper::canonicalize()

• File Writing

  • Modernized PHP array syntax from array() to [] in generated translation files
  • File writing is now atomic with proper temp file creation and cleanup
  • Added directory traversal protection for file writing

• Concurrency Handling

  • Fork mode concurrency is now configurable via --concurrency option
  • Improved stop-key messaging: no longer shows misleading message in fork mode
  • Added explicit warning when running in fork mode about inability to stop mid-process

• Error Handling

  • Enhanced JSON parsing from Gemini responses with multiple fallback strategies
  • Better error context with file names, keys, and last error details
  • Differentiated retry logic for quota vs JSON vs network errors

🐛 Fixed

• Critical Security & Safety

  • Fixed directory traversal vulnerability in file writing with proper path validation
  • Fixed race condition in file writing with atomic temp file strategy
  • Fixed Windows compatibility issues with case-sensitive path validation

• Translation Logic

  • Fixed pluralization detection to check source text instead of translation keys
  • Fixed placeholder validation to check counts instead of just presence
  • Fixed machine key detection logic for accurate humanization
  • Fixed key origin mapping to preserve module/app separation

• Module Support

  • Fixed module directory exclusion when scanning main application (prevents double-scanning)
  • Fixed relative path calculation for module files in extraction logs
  • Added null-safe config handling for module paths to prevent basename errors

• Regex Extraction

  • Fixed multi-line string extraction with proper /s modifier
  • Fixed attribute value extraction to handle escaped quotes properly
  • Fixed bound attribute pattern matching

• User Interface & Selection

  • Fixed "-- ALL FILES --" selection returning empty array instead of all available files
  • Fixed manual file selection not being detected when user selects all individual options
  • Enhanced file selection logic to handle edge cases: selecting only "ALL FILES", selecting all manually, or selecting both
  • Fixed language loading to only load explicitly requested languages instead of all available language directories

🚀 Performance

• Memory Optimization

  • Reduced memory usage in concurrent mode by passing only needed subset of $sourceTextMap to each closure
  • Eliminated duplicate helper methods (static vs instance) to reduce code duplication

• Concurrency Improvements

  • Configurable concurrency levels for better API rate limit management
  • Improved retry logic to avoid unnecessary API calls on JSON parsing errors

💥 Deprecated

• --source option (now unused, was for deprecated interactive scanning)
• --no-advanced option (advanced pattern detection removed as it caused false positives)

📝 Notes

• Version jump from v3.8 to v4.0 reflects significant architectural changes and breaking behavioral changes
• The tool now provides production-grade safety with atomic file writes and security validation
• Translation quality has been significantly improved with script-aware formatting and robust fallback mechanisms
• The addition of --refresh and --dry-run modes enables safer integration into deployment pipelines