gt-vue 0.0.0 → 0.1.0-iris.0

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# gt-vue
+
+## 0.1.0-iris.0
+
+### Minor Changes
+
+- 8d376e2: 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
+
+- Updated dependencies [8d376e2]
+  - gt-i18n@1.0.12-iris.0

package/LICENSE.md

@@ -0,0 +1,105 @@
+# Functional Source License, Version 1.1, ALv2 Future License
+
+## Abbreviation
+
+FSL-1.1-ALv2
+
+## Notice
+
+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.

package/README.md

@@ -1,3 +1,175 @@
+<p align="center">
+  <a href="https://generaltranslation.com/docs/vue">
+    <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">
+    </picture>
+  </a>
+</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>
+</p>
+
 # gt-vue
 
-Placeholder while we work on this! :)
+A lightweight General Translation runtime for Vue 3.
+
+> [!WARNING]
+> `gt-vue` is currently unstable. Its API and behavior may change between
+> releases while the package is under active development. Its 0.x releases
+> are versioned independently from the stable React framework packages.
+
+## Installation
+
+```bash
+npm install gt-vue
+```
+
+## Quick Start
+
+Register one plugin instance with your Vue app. Translation files are loaded
+once per locale and cached for the lifetime of that instance. The
+`defaultLocale` uses source text as its catalog, so `loadTranslations` is never
+called for that locale.
+
+```ts
+// main.ts
+import { createApp } from 'vue';
+import { createGT } from 'gt-vue';
+import App from './App.vue';
+
+const loadTranslations = async (locale: string) => {
+  try {
+    return (await import(`./_gt/${locale}.json`)).default;
+  } catch {
+    return {};
+  }
+};
+
+createApp(App)
+  .use(createGT({ defaultLocale: 'en', loadTranslations }))
+  .mount('#app');
+```
+
+Use `<T>` for rich content. `<Var>` values are provided as slot children, not
+through `name` or `value` props.
+
+```vue
+<script setup lang="ts">
+import { T, Var, useGT, useLocale, useSetLocale } from 'gt-vue';
+
+const name = 'Ada';
+const gt = useGT();
+const locale = useLocale();
+const setLocale = useSetLocale();
+</script>
+
+<template>
+  <main>
+    <T context="welcome">
+      Hello,
+      <Var>{{ name }}</Var>
+      !
+    </T>
+    <p>{{ gt('A plain string', { $context: 'homepage' }) }}</p>
+    <button @click="setLocale(locale === 'en' ? 'fr' : 'en')">
+      {{ locale }}
+    </button>
+  </main>
+</template>
+```
+
+`useGT()` performs a synchronous catalog lookup. Its only option is
+`$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
+boundaries instead:
+
+```vue
+<Suspense>
+  <T>Translatable content</T>
+  <template #fallback><T>Loading…</T></template>
+</Suspense>
+```
+
+## Registered Messages
+
+`msg()` marks a string at module scope and `useMessages()` resolves it inside
+a component.
+
+```vue
+<script setup lang="ts">
+import { msg, useMessages } from 'gt-vue';
+
+const title = msg('Settings', { $context: 'page title' });
+const m = useMessages();
+</script>
+
+<template>
+  <h1>{{ m(title) }}</h1>
+</template>
+```
+
+## Components
+
+- `<T context="...">` translates rich slot content.
+- `<Var>` preserves a dynamic slot value inside `<T>`.
+- `<Num>`, `<DateTime>`, and `<Currency>` require typed runtime values through
+  `:value`; formatter slot children are not supported.
+- `<Plural :n="count">` selects named slots such as `#one` and `#other`.
+- `<Branch :branch="key">` selects an arbitrary named slot.
+
+Use the required `value` prop for every formatting value.
+
+```vue
+<Num :value="count" />
+<Currency :value="price" currency="USD" />
+<DateTime :value="createdAt" :options="{ dateStyle: 'medium' }" />
+```
+
+When the active locale is the configured default, formatting ignores explicit
+`locales` and uses only that default locale. Otherwise, an explicit `locales`
+list on a standalone formatter is tried first, followed by the active locale
+and then the default locale. Inside `<T>`, the rich translation pipeline owns
+formatting locales: source fallbacks use the default locale, while translated
+content uses the active locale followed by the default.
+
+In a browser, gt-vue persists the active locale in the
+`generaltranslation.locale` path-wide session cookie. When `locale` is omitted
+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 SSR, resolve the request locale on the server and pass it as
+`createGT({ locale })`. An explicit locale wins over a stale browser cookie,
+which keeps hydration consistent and synchronizes the client cookie. Call and
+await `plugin.loadTranslations(locale)` or `plugin.setLocale(locale)` before
+server rendering. Create and preload the client plugin with the same locale
+before hydrating; starting hydration before its asynchronous catalog is ready
+can produce source text and a hydration mismatch. Create a fresh `createGT()`
+instance for every server request so locale and catalog state remain
+request-scoped.