Next-gen: javaabu/js-localization v1.0 #12

Activity

1. n4ff4h

   added

   next-genNext-gen Javaabu packagesNext-gen Javaabu packages

   epicTracks a whole packageTracks a whole package

   on Nov 4, 2026
2. n4ff4h commented on Nov 4, 2026

   

   n4ff4h

   on Nov 4, 2026

   CollaboratorAuthor

   More actions

   Implementation plan

   Studied: Javaabu/Laravel-JS-Localization (mariuzzo's lang:js: walks lang/, keys like en.messages, en.strings for JSON, en.vendor::group), @javaabu/i18n (load() shapes, window.Lang pickup, locale detection from <html lang>), and javaabu/manifest (contracts on Javaabu/manifest#13).

   Architecture

   PHP (Javaabu\JsLocalization\)

   • TranslationExporter collects lines through Laravel's own translation loader, not by walking folders, so it sees exactly what __() sees in PHP: lang/{locale}/*.php (including nested groups such as forum/thread), lang/{locale}.json, JSON paths that packages register (loadJsonTranslationsFrom), and namespaced package groups (loadTranslationsFrom) merged with the app's lang/vendor/{ns} overrides.
   • Output is the by-locale shape @javaabu/i18n loads natively: { "dv": { "Save": "…", "validation": { … }, "forum/thread": { … }, "filters::labels": { … } } }. Group names stay as Laravel names them, so __('forum/thread.title') and __('filters::labels.from') behave the same in JS as in PHP.
   • Config (config/js-localization.php, publishable, everything defaulted): locales (auto-detect), groups / except (wildcards), namespaces (*, a list, or false), json (include JSON lines), output path, split (one file per locale vs one file), format (json, or js that sets window.Lang for script-tag pages), route, blade.
   • php artisan lang:js writes the files (--locale, --output, --format, --single, --pretty, --stdout). Old flags that still make sense keep working (--json, -s/--source, --no-sort, a positional target), so the migration is mostly a composer require swap.
   • A cached, ETag-ed JSON endpoint GET /js-localization/{locale}.json serves one locale on demand, so Blade pages need no build step and no export. It's registered automatically (config route.enabled) and also available as Route::jsLocalization() for apps that want their own prefix/middleware.
   • JsLocalization::forLocale('dv') (facade) for Inertia shared props and SSR.

   Shipping @javaabu/i18n through manifest (#3)

   • The provider registers package js-localization with manifest: ->js() (alias @javaabu/js-localization), a script asset js-localization::i18n (Blade entry: installs the __/trans/trans_choice globals and a loader pointing at the endpoint, locale from <html lang>), ->npm(['@javaabu/i18n' => …]), and ->dist() with a prebuilt bundle (i18n included) for apps without Vite.
   • Blade pages get it with no setup: a middleware requires the asset on HTML responses (config blade.auto, on by default; Inertia/JSON responses are untouched by manifest anyway). @manifestScripts('js-localization') for manual placement.
   • Inertia React/Vue: documented setup with configure({ loader }) from the Vite plugin's module, or shared props.

   Vite (#4)

   • A Vite plugin in js/src, built to dist/vite.js and committed (manifest's pattern). On vite build it runs php artisan lang:js before bundling; in dev it watches lang/ (and vendor lang paths), re-exports, and pushes the changed locale to the page over HMR so useTranslation() re-renders without a reload.
   • It provides @javaabu/js-localization/translations (a lazy per-locale loader over the exported files) for SPA/Inertia bundles.
   • Building on manifest's plugin: manifest's manifest() has no hook for package-provided Vite plugins yet. I'll open a cross-package issue asking for one (packages register a Vite plugin module through discovery; manifest() runs it). Until then the plugin works standalone next to manifest(); once manifest supports it, apps won't need to add it.

   AI translation (#5) — lang:translate --to=dv [--from=en] [--driver=] [--model=] [--group=] [--dry-run] [--force], only when laravel/ai is installed (suggest, feature-detected, clear message otherwise). Sends missing lines in batches with a structured-output schema, validates that :placeholders, <tags> and |-plural segments survive (rejects lines that don't), applies a glossary (config array or file), writes PHP/JSON lang files without touching existing lines unless --force, and writes a review report (Markdown + JSON) to storage/. Tests use laravel/ai's fakes only.

   Missing report (#6) — lang:missing [--locale=] [--base=en] [--paths=] [--json]: scans PHP/Blade/JS/TS/TSX/Vue for __(), trans(), trans_choice(), @lang, Lang::get(), $t-style helpers (configurable function names), and reports keys missing per locale, plus lines present in the base locale but missing in the others. Non-zero exit for CI.

   Order of work

   1. Foundations: PHP 8.4 / Laravel 12+, CI matrix, coverage and codestyle #1 Foundations: skeleton from package-skeleton/manifest, PHP 8.4/8.5 × Laravel 12/13 × lowest/stable CI, Pint, JS toolchain (pnpm, TS strict, ESLint, Prettier, Vitest).
   2. Export Laravel translations in @javaabu/i18n's format #2 Exporter, lang:js, config, endpoint.
   3. Ship @javaabu/i18n through javaabu/manifest #3 manifest registration, Blade entry, prebuilt dist.
   4. Hook into the Vite build #4 Vite plugin (+ cross-package issue on manifest).
   5. Missing translations report #6 missing report, then Generate missing translations with AI #5 AI translation.
   6. Dhivehi localization and RTL #10 Dhivehi, Migration guide from Laravel-JS-Localization #7 migration guide, Documentation for people and agents #8 docs/llms.txt/AGENTS.md, Laravel Boost guideline and skill #9 Boost.

   Decisions and open questions

   • @javaabu/i18n isn't on npm. The JS in this repo develops against link:../i18n; CI clones and builds Javaabu/i18n first. Apps get github:Javaabu/i18n#main via ->npm() until it's published (needs Build dist when installed from Git i18n#1).
   • Requires laravel/framework (as manifest does), since it builds on manifest's middleware and Vite integration.
   • Vendor namespaces are exported by default (namespaces => '*') so package UIs work without setup; apps can narrow it. Everything exported is public, as with the old messages.js — documented.
   • Writing PHP lang files from lang:translate uses short-array var_export; comments in the edited file are lost. Documented, and --dry-run + the report make it reviewable.
3. n4ff4h commented on Nov 4, 2026

   

   n4ff4h

   on Nov 4, 2026

   CollaboratorAuthor

   More actions

   Final summary: javaabu/js-localization v1.0 is done on main

   Every next-gen issue is closed except #11 (docs.javaabu.com registration, for you). CI is green on the full matrix: PHP 8.4/8.5 × Laravel 12/13 × lowest/stable, Pint, a job without laravel/ai, and a JS job that runs lint, format, typecheck, checks the committed dist/, runs unit tests, real Vite builds and a Vite dev server.

   What was built

   • Export (Export Laravel translations in @javaabu/i18n's format #2): JsLocalization reads lines through Laravel's translation loader, so JS sees exactly what __() sees: app and framework files, nested groups (forum/thread), JSON lines including packages', and namespaced package groups with lang/vendor overrides. Output is the by-locale shape @javaabu/i18n loads natively. php artisan lang:js writes one file per locale ({locale} in the path), one for all, or a window.Lang script, and keeps Laravel-JS-Localization's target argument, --json/-j, --source/-s, --no-sort and -c. Config: locales, groups/except with wildcards, json, path, sort, pretty.
   • Endpoint: GET /js-localization/{locale}.json, cached by a fingerprint of every language file, with ETag + no-cache revalidation (304s). Auto-registered (configurable prefix/middleware) and Route::jsLocalization() for custom routes.
   • Blade through manifest (Ship @javaabu/i18n through javaabu/manifest #3): asset js-localization::i18n puts __, trans, trans_choice and I18n on window and loads the page's locale (<html lang>) from the endpoint. A middleware inside manifest's injection requires it on full HTML pages only (not JSON, fragments, Inertia responses or Inertia root views). Prebuilt in dist/browser (i18n bundled) for apps without Vite. Inertia React/Vue setup is documented (Vite loader, endpoint, or shared props).
   • Vite plugin (Hook into the Vite build #4): vendor/javaabu/js-localization/dist/vite.js. Runs php artisan lang:js --stdout on start and every build, serves virtual:js-localization (one lazy chunk per locale) behind @javaabu/js-localization/translations, watches lang/ in dev and pushes changed locales over HMR (React/Vue re-render without a reload; Blade pages listen too).
   • lang:missing (Missing translations report #6): scans PHP/Blade/JS/TS/TSX/Vue for literal keys and reports keys a locale lacks (with file:line), lines missing vs. the base locale, and keys JS uses that aren't exported. Non-zero exit for CI, --json.
   • lang:translate (Generate missing translations with AI #5): optional laravel/ai (suggest, feature-detected, require-dev for tests, tested both ways). Batches with structured output, per-locale notes (Thaana/formal Dhivehi for dv) and glossary; rejects translations that change :placeholders, plural segments/ranges or HTML tags; never overwrites unless --force; --dry-run; Markdown + JSON review report. Tests only use TranslationAgent::fake().
   • Parity: tests/Fixtures/parity.json is checked against Laravel's __()/trans_choice() in PHPUnit and against @javaabu/i18n loaded with lang:js output in Vitest.
   • Docs and AI (Migration guide from Laravel-JS-Localization #7, Documentation for people and agents #8, Laravel Boost guideline and skill #9): 19 Docusaurus pages including docs/migrating.md, llms.txt, AGENTS.md/CLAUDE.md, the Boost guideline and javaabu-js-localization skill (with command and troubleshooting references). A test checks every page is linked, links resolve, and every config key and command option is documented.
   • Dhivehi (Dhivehi localization and RTL #10): all command output in lang/en and lang/dv; tests use Thaana; uncertain terms are listed in docs/advanced-usage/localization.md.

   Cross-package

   • Let packages ship a Vite plugin that manifest() runs manifest#14: let packages ship a Vite plugin that manifest() runs. Until then apps add jsLocalization() next to manifest(); nothing is blocked on it.
   • @javaabu/i18n/global doesn't declare the window globals in its types i18n#2: @javaabu/i18n/global's types don't declare the window globals. The Blade entry redeclares them for now.

   Intentionally out of scope / decisions

   • Requires laravel/framework (as manifest does).
   • Everything exported is public, as with the old messages.js; except leaves groups out (documented). The defaults leave out this package's and manifest's command output.
   • The automatic route is registered by default (like manifest's dist route), so Blade needs no setup; the macro is there for apps that want their own group.
   • PHP files written by lang:translate lose comments (documented; --dry-run and the report make it reviewable).
   • Command descriptions and exception messages stay in English; command output is translated.
   • No examples/ folder or changesets: this is a Composer package whose JS ships committed in dist/ (as manifest does); CHANGELOG.md is manual.

   What changes once @javaabu/i18n is on npm

   1. JsLocalizationServiceProvider::I18N_VERSION → ^1.0 (apps are told github:Javaabu/i18n#main today, which needs Build dist when installed from Git i18n#1 merged to install with dist).
   2. package.json: "@javaabu/i18n": "link:../i18n" → ^1.0, and drop the "Build @javaabu/i18n" step and I18N_REF from .github/workflows/tests.yml (CI currently clones Javaabu/i18n at a pinned commit).
   3. Run pnpm build and commit dist/browser (the bundled i18n changes the hash).
   4. When @javaabu/i18n/global doesn't declare the window globals in its types i18n#2 is fixed, remove the redeclared globals in resources/js/blade.ts.

   What you need to do

   1. Codecov: uploads fail with "Token required" (same as manifest). Add the repo on Codecov and make CODECOV_TOKEN available (org secret).
   2. Merge Build dist when installed from Git i18n#1 (or publish @javaabu/i18n) so apps can install it.
   3. Docs: register on docs.javaabu.com (Register with Javaabu Docs (docs.javaabu.com) #11).
   4. Dhivehi review: a native speaker should check the terms in docs/advanced-usage/localization.md.
   5. Release: tag v1.0 and submit to Packagist (Packagist badge).
4. n4ff4h commented on Nov 6, 2026

   

   n4ff4h

   on Nov 6, 2026

   CollaboratorAuthor

   More actions

   Follow-up: the Vite plugin is now registered with javaabu/manifest (Javaabu/manifest#14), so apps only add manifest() to vite.config.js. Options go in manifest({ plugins: { "js-localization": { ... } } }), and false turns the plugin off. Adding jsLocalization() by hand still works with the registered one turned off; manifest warns if both run. Real Vite builds and a dev server are tested both ways, and the docs, llms.txt and Boost skill show the manifest() setup. CI is green (f359e0f, manifest b88528d).