Skip to content
js-localization / 1

API reference

Last updated:

On this page

PHP

JsLocalization facade

Javaabu\JsLocalization\Facades\JsLocalization, a facade for the Javaabu\JsLocalization\JsLocalization singleton.

Method Returns
locales(): array The exported locales: js-localization.locales, or every locale the app has files for plus app.locale and app.fallback_locale. Sorted.
hasLocale(string $locale): bool Whether a locale is exported.
forLocale(string $locale): array One locale's exported lines, as @javaabu/i18n loads them: JSON lines at the top, then groups by name ('messages', 'forum/thread', 'shop::cart'). Cached.
all(?array $locales = null): array Every locale's lines, keyed by locale.
url(?string $locale = null): string The endpoint's path for a locale, or its template: /js-localization/{locale}.json.
fingerprint(): string A hash of every language file and the export settings. It's the endpoint's ETag.
flush(): void Forget lines collected in this process, after language files change in a long-running process (Octane, queue workers).
sourcePaths(): array Every folder language files are read from.
groups(string $locale, bool $exported_only = false): array The groups a locale has files for.
exports(string $group): bool Whether groups and except export a group.
isGroup(string $group): bool Whether any locale has a file for a group.
jsonLines(string $locale): array A locale's JSON lines, packages' included.
loadGroup(string $locale, string $group): array One group's lines, with lang/vendor overrides for packages.
flatLines(string $locale, bool $namespaced = true): array Every line, exported or not, by the key you pass to __(): 'messages.nested.title' => '...'.
use Javaabu\JsLocalization\Facades\JsLocalization;

JsLocalization::forLocale('dv')['messages']['welcome']; // ':app އަށް މަރުޙަބާ'
JsLocalization::url('dv');                              // '/js-localization/dv.json'

Route macro

Route::jsLocalization(?string $prefix = null): Illuminate\Routing\Route registers GET {prefix}/{locale}.json, named js-localization.show (route.name). See The endpoint.

Commands

Command Page
php artisan lang:js [target] [--locale=] [--format=] [--pretty] [--stdout] [--no-sort] [--source=] Exporting translations
php artisan lang:missing [--locale=] [--base=] [--path=] [--vendor] [--json] Missing translations
php artisan lang:translate --to= [--from=] [--driver=] [--model=] [--group=] [--vendor] [--force] [--batch=] [--glossary=] [--dry-run] AI translation

Manifest asset

Asset What it is
js-localization::i18n The Blade script (resources/js/blade.ts). Its tag carries the endpoint in data-js-localization.

The package also registers resources/js as @javaabu/js-localization and asks apps to install @javaabu/i18n (php artisan manifest:check).

Publishing

Tag What
js-localization-config config/js-localization.php
js-localization-translations The package's own command output, to lang/vendor/js-localization
manifest-dist-js-localization The prebuilt Blade script, for apps without Vite (manifest's tag)

AI translation classes

Class What it is
Javaabu\JsLocalization\Translate\TranslationAgent The laravel/ai agent. TranslationAgent::fake() and its assertions work as for any laravel/ai agent.
Javaabu\JsLocalization\Translate\AiTranslator Sends a batch and returns translations by key. available() says whether laravel/ai is installed.
Javaabu\JsLocalization\Translate\LineValidator problem($source, $translation): null, or why a translation breaks placeholders, plurals or tags.

JavaScript

@javaabu/js-localization/translations

Needs the Vite plugin.

Export What it is
loader(locale): Promise<Messages> @javaabu/i18n's loader option: imports a locale's chunk. Unknown locales resolve to {}. Also the default export.
locales: string[] Every exported locale.

Importing it also listens for the plugin's updates in development.

@javaabu/js-localization

Export What it is
useEndpoint(url?) configure({ loader: url }), with the page's endpoint by default.
endpoint(root = document): string The page's endpoint: <meta name="js-localization">, then the Blade script's data-js-localization, then /js-localization/{locale}.json.
listenForUpdates(import.meta.hot, translator?) Applies the Vite plugin's updates to a translator (the shared one by default).
applyUpdate({ locale, messages }, translator?) Merges one update.
DEFAULT_ENDPOINT, ENDPOINT_ATTRIBUTE, UPDATE_EVENT "/js-localization/{locale}.json", "data-js-localization", "js-localization:update"

Vite plugin

vendor/javaabu/js-localization/dist/vite.js, registered with manifest (->vitePlugin('../dist/vite.js')), so manifest() runs it. The default export is jsLocalization(options); see Vite plugin for the options and adding it by hand. It also exports exportTranslations(root, command), VIRTUAL_MODULE_ID ("virtual:js-localization") and UPDATE_EVENT.

Documentation
All packages

javaabu/js-localization

Source on GitHub