gt-vue 0.1.0-iris.1 → 0.1.0

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # gt-vue
 
+## 0.1.0
+
+### Minor Changes
+
+- [#2012](https://github.com/generaltranslation/gt/pull/2012) [`8d376e2`](https://github.com/generaltranslation/gt/commit/8d376e23c80828dfd8756e2f0fbf0f7725e0f178) Thanks [@eoinest](https://github.com/eoinest)! - Add a lightweight Vue 3 runtime with catalog-backed string and rich-content
+  translation, cookie-backed reactive locale switching, child-only variables,
+  and typed value props for number, currency, and date formatting. Browser SPAs
+  restore the locale from a configurable cookie, while an explicit server locale
+  wins during SSR hydration.
+
+### Patch Changes
+
+- [#2068](https://github.com/generaltranslation/gt/pull/2068) [`f2204b9`](https://github.com/generaltranslation/gt/commit/f2204b990278865c54d14d337392930ea1ec31bf) Thanks [@eoinest](https://github.com/eoinest)! - Translate statically authored custom-component default slots, preserve authored
+  Fragments, and align Branch and Plural wire values, rendering fallbacks, and
+  locale selection with React. Add React-compatible `context`, `id`, `maxChars`,
+  and `requiresReview` metadata to `<T>`, including compiler-facing `$` aliases.
+
+- [#2080](https://github.com/generaltranslation/gt/pull/2080) [`5d8b78a`](https://github.com/generaltranslation/gt/commit/5d8b78a1085d5dadc5bdc7435b3c6addf8981c38) Thanks [@eoinest](https://github.com/eoinest)! - Migrate the package license from FSL-1.1-ALv2 to MIT.
+
+- [#2090](https://github.com/generaltranslation/gt/pull/2090) [`95b48df`](https://github.com/generaltranslation/gt/commit/95b48df677d27f41a336f13e01ae7aa9aa484c73) Thanks [@eoinest](https://github.com/eoinest)! - Add browser SPA initialization and synchronous module-level `t()` translations
+  to gt-vue.
+- Updated dependencies [[`f2204b9`](https://github.com/generaltranslation/gt/commit/f2204b990278865c54d14d337392930ea1ec31bf), [`b05b470`](https://github.com/generaltranslation/gt/commit/b05b4703fbbfd34a3cbee335c786e2e606346167), [`8d376e2`](https://github.com/generaltranslation/gt/commit/8d376e23c80828dfd8756e2f0fbf0f7725e0f178)]:
+  - @generaltranslation/format@0.1.8
+  - generaltranslation@9.1.7
+  - gt-i18n@1.0.17
+
+## 0.1.0-iris.2
+
+### Patch Changes
+
+- 95b48df: Add browser SPA initialization and synchronous module-level `t()` translations
+  to gt-vue.
+
 ## 0.1.0-iris.1
 
 ### Patch Changes

package/README.md

@@ -84,6 +84,90 @@ const setLocale = useSetLocale();
 `$context`; braces are literal text and no ICU formatting or interpolation is
 applied.
 
+## Module-level translations in a Vite SPA
+
+Browser-only SPAs can call `t()` at module scope after `initializeGTSPA()` has
+loaded the active locale. Use an async bootstrap function, and dynamically
+import the rest of the application only after initialization.
+This complements rather than replaces the `gt()` callback from `useGT()`,
+which remains the normal API inside Vue components and for SSR applications.
+
+```ts
+// src/index.ts
+import { initializeGTSPA } from 'gt-vue';
+import gtConfig from '../gt.config.json';
+import loadTranslations from './loadTranslations';
+
+async function bootstrap() {
+  const gt = await initializeGTSPA({ ...gtConfig, loadTranslations });
+  const { mount } = await import('./main');
+  mount(gt);
+}
+
+void bootstrap().catch((error: unknown) => {
+  console.error(error);
+});
+```
+
+Configure the CLI output and the Vite loader to use the same directory:
+
+```json
+{
+  "defaultLocale": "en",
+  "locales": ["fr"],
+  "files": {
+    "gt": {
+      "output": "src/_gt/[locale].json"
+    }
+  }
+}
+```
+
+```ts
+// src/loadTranslations.ts
+export default async function loadTranslations(locale: string) {
+  const translations = await import(`./_gt/${locale}.json`);
+  return translations.default;
+}
+```
+
+Create an empty JSON file for each configured target locale before the first
+translation run (for example, `src/_gt/fr.json` containing `{}`). The default
+locale uses source content and does not need a loader file.
+
+```ts
+// src/main.ts
+import { createApp } from 'vue';
+import type { GTPlugin } from 'gt-vue';
+import App from './App.vue';
+
+export function mount(gt: GTPlugin) {
+  createApp(App).use(gt).mount('#app');
+}
+```
+
+Install the plugin returned by `initializeGTSPA()` rather than creating a
+second plugin. The returned instance is already preloaded and is the exact
+runtime used by `t()`.
+
+```ts
+// src/navigation.ts (loaded by the dynamic application import)
+import { t } from 'gt-vue';
+
+export const navigation = [
+  t('Documentation', { $context: 'primary navigation' }),
+];
+```
+
+Like `useGT()`, `t()` supports only plain STRING content and static `$context`.
+It does not support ICU syntax, interpolation, tagged templates, `$format`, or
+`$maxChars`. The extractor registers static `t()` calls in the catalog.
+
+SPA locale changes write the locale cookie and reload the page. Reloading is
+intentional: it lets every module-level translation execute again after the new
+locale catalog is preloaded. `initializeGTSPA()` and `t()` are not valid in SSR;
+use one request-scoped `createGT({ locale })` instance there.
+
 Statically authored default-slot content inside a custom component participates
 in the surrounding translation. The component itself, its props, and its
 listeners are preserved while the translated content replaces its default
@@ -173,12 +257,18 @@ from `createGT()`, that cookie wins over `defaultLocale`. Use
 `localeCookieName` to share a different cookie with your routing or server
 integration.
 
-`setLocale()` loads a missing catalog before writing the cookie and rerendering
-consumers. A failed or superseded request leaves both the cookie and rendered
-locale unchanged. Direct changes to `document.cookie` are reflected by
-`plugin.getLocale()` and the next Vue render, but browsers do not emit cookie
-change events, so they do not schedule a render by themselves. Use gt-vue's
-setter for reactive locale changes.
+For plugins created with `createGT()`, `setLocale()` loads a missing catalog
+before writing the cookie and rerendering consumers. A failed or superseded
+request leaves both the cookie and rendered locale unchanged. Direct changes to
+`document.cookie` are reflected by `plugin.getLocale()` and the next Vue render,
+but browsers do not emit cookie change events, so they do not schedule a render
+by themselves. Use gt-vue's setter for reactive locale changes.
+
+`initializeGTSPA()` instead pins the preloaded locale for the lifetime of the
+page. Its `setLocale()` writes the cookie and reloads the document so
+module-level `t()` calls execute again with the new catalog. Direct cookie
+changes do not change the mounted SPA; they are resolved during the next page
+initialization, and unsupported locales fall back to `defaultLocale`.
 
 For SSR, resolve the request locale on the server and pass it as
 `createGT({ locale })`. An explicit locale wins over a stale browser cookie,

package/dist/index.cjs

@@ -6,37 +6,48 @@ let generaltranslation_types = require("generaltranslation/types");
 let generaltranslation_id = require("generaltranslation/id");
 let gt_i18n_internal_string = require("gt-i18n/internal/string");
 //#region src/runtime/localeCookie.ts
-function createCookieBackedLocale({ defaultLocale, locale: explicitLocale, localeCookieName }) {
+function createCookieBackedLocale({ defaultLocale, locale: explicitLocale, localeCookieName, resolveLocale = identityLocale$1 }) {
 	const cookieLocale = (0, gt_i18n_internal_cookies.getBrowserCookieValue)(localeCookieName);
-	const resolvedLocale = explicitLocale ?? (cookieLocale || defaultLocale);
-	const browserFallbackLocale = explicitLocale ?? defaultLocale;
+	const resolvedLocale = resolveLocale(explicitLocale ?? (cookieLocale || defaultLocale));
+	const browserFallbackLocale = resolveLocale(explicitLocale ?? defaultLocale);
 	let serverLocale = resolvedLocale;
 	(0, gt_i18n_internal_cookies.setBrowserCookieValue)(localeCookieName, resolvedLocale);
 	return {
 		getLocale() {
-			if (typeof document !== "undefined") return (0, gt_i18n_internal_cookies.getBrowserCookieValue)(localeCookieName) || browserFallbackLocale;
+			if (typeof document !== "undefined") return resolveLocale((0, gt_i18n_internal_cookies.getBrowserCookieValue)(localeCookieName) || browserFallbackLocale);
 			return serverLocale;
 		},
 		setLocale(nextLocale) {
-			serverLocale = nextLocale;
-			(0, gt_i18n_internal_cookies.setBrowserCookieValue)(localeCookieName, nextLocale);
+			const resolvedNextLocale = resolveLocale(nextLocale);
+			serverLocale = resolvedNextLocale;
+			(0, gt_i18n_internal_cookies.setBrowserCookieValue)(localeCookieName, resolvedNextLocale);
 		}
 	};
 }
+function identityLocale$1(locale) {
+	return locale;
+}
 //#endregion
 //#region src/runtime/state.ts
-const gtContextKey = Symbol("gt-vue");
-function createGT({ defaultLocale = generaltranslation_internal.libraryDefaultLocale, loadTranslations, locale: explicitLocale, localeCookieName = gt_i18n_internal_cookies.defaultLocaleCookieName } = {}) {
+const gtContextKey = Symbol.for("generaltranslation.gt-vue.context");
+function createGT(options = {}) {
+	return createGTRuntime(options).plugin;
+}
+function createGTRuntime({ defaultLocale = generaltranslation_internal.libraryDefaultLocale, loadTranslations, locale: explicitLocale, localeCookieName = gt_i18n_internal_cookies.defaultLocaleCookieName } = {}, runtimeOptions = {}) {
 	const localeAccessor = createCookieBackedLocale({
 		defaultLocale,
 		locale: explicitLocale,
-		localeCookieName
+		localeCookieName,
+		resolveLocale: runtimeOptions.resolveLocale
 	});
 	const revision = (0, vue.ref)(0);
 	const catalogs = new Map([[defaultLocale, {}]]);
 	const pending = /* @__PURE__ */ new Map();
+	const initialLocale = localeAccessor.getLocale();
+	const getLocale = runtimeOptions.pinLocale ? () => initialLocale : () => localeAccessor.getLocale();
 	let localeRequest = 0;
-	const load = async (targetLocale) => {
+	const load = async (locale) => {
+		const targetLocale = runtimeOptions.resolveLocale?.(locale) ?? locale;
 		const cached = catalogs.get(targetLocale);
 		if (cached) return cached;
 		const currentPending = pending.get(targetLocale);
@@ -60,36 +71,42 @@ function createGT({ defaultLocale = generaltranslation_internal.libraryDefaultLo
 		pending.set(targetLocale, promise);
 		return promise;
 	};
-	const setLocale = async (targetLocale) => {
+	const setLocale = runtimeOptions.reloadDocument ? async (targetLocale) => {
+		localeAccessor.setLocale(targetLocale);
+		runtimeOptions.reloadDocument?.();
+	} : async (targetLocale) => {
 		const request = ++localeRequest;
 		await load(targetLocale);
 		if (request !== localeRequest) return;
 		localeAccessor.setLocale(targetLocale);
 		revision.value += 1;
 	};
-	const getLocale = () => {
-		revision.value;
-		return localeAccessor.getLocale();
-	};
 	const state = {
 		defaultLocale,
 		getCatalog() {
 			revision.value;
 			return catalogs.get(getLocale()) ?? {};
 		},
-		getLocale,
+		getLocale() {
+			revision.value;
+			return getLocale();
+		},
 		loadTranslations: load,
+		resolveFormattingLocale: runtimeOptions.resolveFormattingLocale,
 		revision,
 		setLocale
 	};
 	return {
-		getLocale,
-		install(app) {
-			app.provide(gtContextKey, state);
-			load(getLocale()).catch(() => void 0);
+		plugin: {
+			getLocale: state.getLocale,
+			install(app) {
+				app.provide(gtContextKey, state);
+				load(state.getLocale()).catch(() => void 0);
+			},
+			loadTranslations: load,
+			setLocale
 		},
-		loadTranslations: load,
-		setLocale
+		state
 	};
 }
 function useGTState() {
@@ -99,7 +116,7 @@ function useGTState() {
 		source: "gt-vue",
 		severity: "Error",
 		whatHappened: "The GT Vue plugin is not installed",
-		fix: "Install the plugin with app.use(createGT(options))"
+		fix: "Install the exact plugin returned by initializeGTSPA() with app.use(plugin), or install app.use(createGT(options)) for non-SPA usage"
 	}));
 }
 //#endregion
@@ -120,13 +137,18 @@ const NON_BRANCH_ATTRIBUTE_NAMES = new Set([
 function withGTMetadata(component, metadata) {
 	return Object.assign(component, { _gtt: metadata });
 }
-function getFormatLocales(locales, locale, defaultLocale = generaltranslation_internal.libraryDefaultLocale) {
-	if (locale === defaultLocale) return [defaultLocale];
+function getFormatLocales(locales, locale, defaultLocale = generaltranslation_internal.libraryDefaultLocale, resolveLocale = identityLocale) {
+	const resolvedLocale = resolveLocale(locale);
+	const resolvedDefaultLocale = resolveLocale(defaultLocale);
+	if (resolvedLocale === resolvedDefaultLocale) return [resolvedDefaultLocale];
 	return [...new Set([
 		...locales ?? [],
 		locale,
 		defaultLocale
-	])];
+	].map(resolveLocale))];
+}
+function identityLocale(locale) {
+	return locale;
 }
 function asFragmentRoot(children) {
 	if (Array.isArray(children)) return children;
@@ -162,7 +184,7 @@ const Plural = /* @__PURE__ */ withGTMetadata(/* @__PURE__ */ (0, vue.defineComp
 		const state = useGTState();
 		return () => {
 			const branches = getBranchNames(attrs, slots).filter(generaltranslation_internal.isAcceptedPluralForm);
-			const branch = (0, generaltranslation_internal.getPluralForm)(props.n, branches, getFormatLocales(props.locales, state.getLocale(), state.defaultLocale));
+			const branch = (0, generaltranslation_internal.getPluralForm)(props.n, branches, getFormatLocales(props.locales, state.getLocale(), state.defaultLocale, state.resolveFormattingLocale));
 			const namedSlot = branch && slots[branch];
 			return asFragmentRoot(branch && attrs[branch] === null && typeof namedSlot !== "function" ? slots.default?.() ?? null : getBranchContent(branch, attrs, slots));
 		};
@@ -637,7 +659,7 @@ function getBranchKey(source) {
 function getPluralKey(n, branches, state, locale = state.getLocale()) {
 	const forms = branches.filter(generaltranslation_internal.isAcceptedPluralForm);
 	if (!forms.length) return void 0;
-	return (0, generaltranslation_internal.getPluralForm)(n, forms, getFormatLocales(void 0, locale, state.defaultLocale)) || void 0;
+	return (0, generaltranslation_internal.getPluralForm)(n, forms, getFormatLocales(void 0, locale, state.defaultLocale, state.resolveFormattingLocale)) || void 0;
 }
 function getSelectedSourceBranch(source, branch) {
 	if (!branch || !Object.hasOwn(source.branches, branch)) return {
@@ -885,7 +907,7 @@ const Currency = /* @__PURE__ */ withGTMetadata(/* @__PURE__ */ (0, vue.defineCo
 	}
 }), "variable-currency");
 function getVariableFormatLocales(props, state) {
-	return props._locale === void 0 ? getFormatLocales(props.locales, state.getLocale(), state.defaultLocale) : getFormatLocales(void 0, props._locale, state.defaultLocale);
+	return props._locale === void 0 ? getFormatLocales(props.locales, state.getLocale(), state.defaultLocale, state.resolveFormattingLocale) : getFormatLocales(void 0, props._locale, state.defaultLocale, state.resolveFormattingLocale);
 }
 //#endregion
 //#region src/composables/locale.ts
@@ -926,6 +948,95 @@ function msg(message, options) {
 	return (0, gt_i18n_internal_string.msgString)(message, options);
 }
 //#endregion
+//#region src/runtime/spa.ts
+async function initializeGTSPA(options = {}) {
+	assertBrowser(createInitializeOnServerError);
+	const manager = getSPARuntimeManager();
+	if (manager.runtime) return manager.runtime.plugin;
+	if (!manager.initialization) manager.initialization = createSPARuntime(options);
+	const initialization = manager.initialization;
+	try {
+		const runtime = await initialization;
+		if (manager.initialization === initialization) manager.runtime = runtime;
+		return runtime.plugin;
+	} finally {
+		if (manager.initialization === initialization) manager.initialization = void 0;
+	}
+}
+const t = (message, options = {}) => {
+	assertBrowser(createTranslateOnServerError);
+	const runtime = getSPARuntimeManager().runtime;
+	if (!runtime) throw new Error(createTranslateBeforeInitializationError());
+	return translateString(runtime.state, message, options);
+};
+async function createSPARuntime(options) {
+	const { customMapping, locales, ...createOptions } = options;
+	const { determineLocale, resolveCanonicalLocale } = await import("@generaltranslation/format");
+	const resolveFormattingLocale = (locale) => {
+		const canonicalLocale = resolveCanonicalLocale(locale, customMapping);
+		return determineLocale(canonicalLocale, [canonicalLocale]) ?? canonicalLocale;
+	};
+	const runtime = createGTRuntime(createOptions, {
+		pinLocale: true,
+		reloadDocument: () => window.location.reload(),
+		resolveFormattingLocale,
+		resolveLocale: createSupportedLocaleResolver(createOptions.defaultLocale ?? generaltranslation_internal.libraryDefaultLocale, locales, determineLocale, resolveFormattingLocale)
+	});
+	await runtime.plugin.loadTranslations(runtime.plugin.getLocale());
+	return runtime;
+}
+function createSupportedLocaleResolver(defaultLocale, locales, determineLocale, canonicalizeLocale) {
+	if (locales === void 0) {
+		const canonicalDefaultLocale = canonicalizeLocale(defaultLocale);
+		return (locale) => locale.toLowerCase() === defaultLocale.toLowerCase() || canonicalizeLocale(locale) === canonicalDefaultLocale ? defaultLocale : locale;
+	}
+	const configuredLocales = Array.from(new Set([defaultLocale, ...locales]));
+	const canonicalLocales = configuredLocales.map(canonicalizeLocale);
+	return (locale) => {
+		const exactIndex = configuredLocales.findIndex((configuredLocale) => configuredLocale.toLowerCase() === locale.toLowerCase());
+		if (exactIndex !== -1) return configuredLocales[exactIndex];
+		const matchedLocale = determineLocale(canonicalizeLocale(locale), canonicalLocales);
+		if (matchedLocale === void 0) return defaultLocale;
+		return configuredLocales[canonicalLocales.indexOf(matchedLocale)] ?? defaultLocale;
+	};
+}
+function getSPARuntimeManager() {
+	const globalObject = globalThis;
+	const registry = globalObject.__generaltranslation ??= {};
+	const vueNamespace = registry.vue ??= {};
+	return vueNamespace.spaRuntime ??= {};
+}
+function assertBrowser(createDiagnostic) {
+	if (typeof window === "undefined" || typeof document === "undefined") throw new Error(createDiagnostic());
+}
+function createInitializeOnServerError() {
+	return (0, generaltranslation_internal.createDiagnosticMessage)({
+		source: "gt-vue",
+		severity: "Error",
+		whatHappened: "initializeGTSPA() cannot run in a server-rendered environment",
+		why: "it creates browser-global translation state and changes locales by reloading the document",
+		fix: "Use createGT({ locale }) once per server request and preload that request locale before rendering"
+	});
+}
+function createTranslateOnServerError() {
+	return (0, generaltranslation_internal.createDiagnosticMessage)({
+		source: "gt-vue",
+		severity: "Error",
+		whatHappened: "t() cannot run in a server-rendered environment",
+		why: "module-level translation state cannot be safely shared across server requests",
+		fix: "Use request-scoped createGT({ locale }) with useGT() inside Vue components, or register module strings with msg() and resolve them through useMessages()"
+	});
+}
+function createTranslateBeforeInitializationError() {
+	return (0, generaltranslation_internal.createDiagnosticMessage)({
+		source: "gt-vue",
+		severity: "Error",
+		whatHappened: "t() ran before the GT Vue SPA runtime finished initializing",
+		why: "module-level translations require the active locale catalog to be loaded first",
+		fix: "Await initializeGTSPA() in a bootstrap module, then dynamically import the application entry point"
+	});
+}
+//#endregion
 exports.Branch = Branch;
 exports.Currency = Currency;
 exports.DateTime = DateTime;
@@ -934,7 +1045,9 @@ exports.Plural = Plural;
 exports.T = T;
 exports.Var = Var;
 exports.createGT = createGT;
+exports.initializeGTSPA = initializeGTSPA;
 exports.msg = msg;
+exports.t = t;
 exports.useGT = useGT;
 exports.useLocale = useLocale;
 exports.useMessages = useMessages;