gt-vue 0.1.0-iris.0 → 0.1.0-iris.2

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # gt-vue
 
+## 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
+
+- f2204b9: 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.
+- 5d8b78a: Migrate the package license from FSL-1.1-ALv2 to MIT.
+- Updated dependencies [f2204b9]
+- Updated dependencies [b05b470]
+- Updated dependencies [5d8b78a]
+  - generaltranslation@9.1.3-iris.0
+  - gt-i18n@1.0.13-iris.0
+
 ## 0.1.0-iris.0
 
 ### Minor Changes

package/LICENSE.md

@@ -1,105 +1,21 @@
-# Functional Source License, Version 1.1, ALv2 Future License
-
-## Abbreviation
-
-FSL-1.1-ALv2
-
-## Notice
+MIT License
 
 Copyright 2025 General Translation, Inc.
 
-## Terms and Conditions
-
-### Licensor ("We")
-
-The party offering the Software under these Terms and Conditions.
-
-### The Software
-
-The "Software" is each version of the software that we make available under
-these Terms and Conditions, as indicated by our inclusion of these Terms and
-Conditions with the Software.
-
-### License Grant
-
-Subject to your compliance with this License Grant and the Patents,
-Redistribution and Trademark clauses below, we hereby grant you the right to
-use, copy, modify, create derivative works, publicly perform, publicly display
-and redistribute the Software for any Permitted Purpose identified below.
-
-### Permitted Purpose
-
-A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
-means making the Software available to others in a commercial product or
-service that:
-
-1. substitutes for the Software;
-
-2. substitutes for any other product or service we offer using the Software
-   that exists as of the date we make the Software available; or
-
-3. offers the same or substantially similar functionality as the Software.
-
-Permitted Purposes specifically include using the Software:
-
-1. for your internal use and access;
-
-2. for non-commercial education;
-
-3. for non-commercial research; and
-
-4. in connection with professional services that you provide to a licensee
-   using the Software in accordance with these Terms and Conditions.
-
-### Patents
-
-To the extent your use for a Permitted Purpose would necessarily infringe our
-patents, the license grant above includes a license under our patents. If you
-make a claim against any party that the Software infringes or contributes to
-the infringement of any patent, then your patent license to the Software ends
-immediately.
-
-### Redistribution
-
-The Terms and Conditions apply to all copies, modifications and derivatives of
-the Software.
-
-If you redistribute any copies, modifications or derivatives of the Software,
-you must include a copy of or a link to these Terms and Conditions and not
-remove any copyright notices provided in or with the Software.
-
-### Disclaimer
-
-THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
-PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
-
-IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
-SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
-EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
-
-### Trademarks
-
-Except for displaying the License Details and identifying us as the origin of
-the Software, you have no right under these Terms and Conditions to use our
-trademarks, trade names, service marks or product names.
-
-## Grant of Future License
-
-We hereby irrevocably grant you an additional license to use the Software under
-the Apache License, Version 2.0 that is effective on the second anniversary of
-the date we make the Software available. On or after that date, you may use the
-Software under the Apache License, Version 2.0, in which case the following
-will apply:
-
-Licensed under the Apache License, Version 2.0 (the "License"); you may not use
-this file except in compliance with the License.
-
-You may obtain a copy of the License at
-
-http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software distributed
-under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
-CONDITIONS OF ANY KIND, either express or implied. See the License for the
-specific language governing permissions and limitations under the License.
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <a href="https://generaltranslation.com/docs/vue">
+  <a href="https://generaltranslation.com/docs">
     <picture>
       <source media="(prefers-color-scheme: dark)" srcset="https://generaltranslation.com/brand/gt-logo-dark.svg">
       <img alt="General Translation" src="https://generaltranslation.com/brand/gt-logo-light.svg" width="100" height="100">
@@ -8,7 +8,7 @@
 </p>
 
 <p align="center">
-  <a href="https://generaltranslation.com/docs/vue"><strong>Documentation</strong></a> · <a href="https://github.com/generaltranslation/gt/issues">Report Bug</a>
+  <a href="https://generaltranslation.com/docs"><strong>Documentation</strong></a> · <a href="https://github.com/generaltranslation/gt/issues">Report Bug</a>
 </p>
 
 # gt-vue
@@ -84,22 +84,113 @@ const setLocale = useSetLocale();
 `$context`; braces are literal text and no ICU formatting or interpolation is
 applied.
 
-Arbitrary component slots are opaque when placed inside `<T>`. Vue does not
-expose a reliable way to inspect a component slot without executing user code,
-so the component and its real runtime slots are preserved, but their content is
-not part of the surrounding rich translation. To translate slot content, place
-`<T>` inside the slot and wrap runtime values in `<Var>`. Native elements and
-the slots owned by GT's `<Branch>` and `<Plural>` components remain part of the
-surrounding translation. Component tags inside `<T>` must resolve at runtime;
-an unresolved component warning from Vue is a configuration error and is not a
-supported translation source.
-
-Vue `<Suspense>` is the one built-in whose default content participates in an
-outer `<T>`. Prefer literal `<Suspense>` and use a single default root. Immutable
-aliases that the extractor can trace directly to `vue` are also supported; the
-fallback slot is preserved but excluded from the outer translation. Re-exported,
-globally registered, ref/computed-held, and other runtime-wrapped Suspense
-aliases are not supported inside an outer `<T>`. Put `<T>` inside those
+## Module-level translations in a Vite SPA
+
+Browser-only SPAs can call `t()` at module scope after `initializeGTSPA()` has
+loaded the active locale. Use a bootstrap module with top-level `await`, 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';
+
+const gt = await initializeGTSPA({ ...gtConfig, loadTranslations });
+const { mount } = await import('./main');
+mount(gt);
+```
+
+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
+slot:
+
+```vue
+<T>
+  <DocsLink to="/docs">Read the documentation</DocsLink>
+</T>
+```
+
+Content created inside `DocsLink`'s implementation is not visible to the outer
+`<T>`. Runtime values still belong in `<Var>`, and conditional alternatives
+belong in `<Branch>` or `<Plural>`. Scoped and arbitrary named slots depend on
+the child component's runtime behavior, so place `<T>` inside those slots or
+enclose the dynamic component boundary in `<Var>`. Component tags inside `<T>`
+must resolve at runtime; an unresolved component warning from Vue is a
+configuration error and is not a supported translation source. Use direct
+component tags inside an outer `<T>`: Vue's `<component :is>` and
+`is="vue:..."` selector forms are intentionally rejected by extraction because
+global runtime registration can change their component identity after build.
+
+Vue built-ins with statically authored default content follow the same rule.
+`<Suspense>` needs one additional distinction: its default content participates
+in an outer `<T>`, while its fallback slot is preserved but excluded from that
+translation. Prefer literal `<Suspense>` with a single default root. Immutable
+aliases that the extractor can trace directly to `vue` are also supported.
+Re-exported, globally registered, ref/computed-held, and other runtime-wrapped
+Suspense aliases are not supported inside an outer `<T>`. Put `<T>` inside those
 boundaries instead:
 
 ```vue
@@ -129,7 +220,10 @@ const m = useMessages();
 
 ## Components
 
-- `<T context="...">` translates rich slot content.
+- `<T context="..." :max-chars="80" requires-review>` translates rich slot
+  content and supplies translation metadata. The deprecated `id` prop is
+  accepted for React API compatibility but does not replace the content-based
+  catalog hash.
 - `<Var>` preserves a dynamic slot value inside `<T>`.
 - `<Num>`, `<DateTime>`, and `<Currency>` require typed runtime values through
   `:value`; formatter slot children are not supported.
@@ -157,12 +251,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,