feat(vue): add lightweight Vue runtime

.changeset/calm-pandas-translate.md

@@ -0,0 +1,9 @@
+---
+'gt-vue': minor
+---
+
+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.

.changeset/tidy-vue-messages.md

@@ -0,0 +1,10 @@
+---
+'gt-i18n': patch
+---
+
+Make `msg(..., { $format: 'STRING' })` preserve source text literally instead
+of applying ICU interpolation. For example, `msg('Hello {name}', {
+$format: 'STRING', name: 'Ada' })` now encodes `Hello {name}` rather than
+`Hello Ada`. Add lightweight shared helpers for registering, hashing, and
+decoding literal STRING messages, browser cookie access, and canonical GT
+cookie names, and validate encoded fields by type.

.claude/CLAUDE.md

@@ -74,7 +74,7 @@ Turbo tasks: `build`, `test`, `lint`, `lint:fix`, `format`, `format:fix`, `trans
 - Never repeat a library fallback as a literal in production source. Import the canonical constant so a default change propagates across every package. Before adding a fallback, search the owning package's settings and constants modules for an existing default.
 - The canonical locale is `libraryDefaultLocale`. Inside `packages/core`, import it from `src/settings/settings.ts`; inside `packages/format`, import its local copy from `src/settings/settings.ts` because core depends on format; everywhere else, import it from `generaltranslation/internal`.
 - Core's canonical request timeout is `defaultTimeout` in `packages/core/src/settings/settings.ts`. Its service endpoints are `defaultBaseUrl`, `defaultCacheUrl`, and `defaultRuntimeApiUrl` in `packages/core/src/settings/settingsUrls.ts`; other packages consume the endpoint defaults from `generaltranslation/internal`.
-- The canonical locale, region, feature-flag, and reset cookie names live in `packages/react-core/src/setup/cookieNames.ts` and are available from `@generaltranslation/react-core/pure`. The Next.js routing cookie and locale header defaults live in `packages/next/src/utils/cookies.ts` and `packages/next/src/utils/headers.ts`; gt-next source should import those constants instead of repeating their values.
+- The canonical locale, region, feature-flag, and reset cookie names live in `packages/i18n/src/utils/cookieNames.ts` and are available from `gt-i18n/internal/cookies`; React integrations also re-export them from `@generaltranslation/react-core/pure` for compatibility. The Next.js routing cookie and locale header defaults live in `packages/next/src/utils/cookies.ts` and `packages/next/src/utils/headers.ts`; gt-next source should import those constants instead of repeating their values.
 - `packages/core` and `packages/format` intentionally define matching locale and timeout defaults to preserve their dependency direction. Keep the copies synchronized.
 - Tests, fixtures, examples, and documentation may use explicit values when the value itself matters to the scenario. Prefer canonical constants when testing default behavior.
 - Run `pnpm check:library-defaults` after changing a canonical default or adding fallback behavior. If a literal matches a canonical value but has a distinct meaning, add only a narrow, documented exception to `scripts/check-library-defaults.mjs`.

.github/workflows/ci.yml

@@ -162,6 +162,53 @@ jobs:
           pnpm exec turbo build --filter=general-cases... --force
           pnpm exec turbo build:turbopack --filter=general-cases... --force
 
+  test-vue-versions:
+    strategy:
+      matrix:
+        vue: ['3.3.13', '3.5.40']
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Check if gt-vue changed
+        id: gt_vue_changed
+        shell: bash
+        run: |
+          if git diff --name-only origin/${{ github.base_ref }}...HEAD | grep -q "^packages/vue/"; then
+            echo "changed=true" >> $GITHUB_OUTPUT
+          else
+            echo "changed=false" >> $GITHUB_OUTPUT
+          fi
+
+      - uses: pnpm/action-setup@v4
+        if: steps.gt_vue_changed.outputs.changed == 'true'
+        name: Install pnpm
+
+      - name: Setup Node.js
+        if: steps.gt_vue_changed.outputs.changed == 'true'
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        if: steps.gt_vue_changed.outputs.changed == 'true'
+        run: pnpm install
+
+      - name: Use Vue ${{ matrix.vue }}
+        if: steps.gt_vue_changed.outputs.changed == 'true'
+        run: pnpm --filter gt-vue add --save-dev --save-exact --lockfile=false vue@${{ matrix.vue }}
+
+      - name: Build and test gt-vue
+        if: steps.gt_vue_changed.outputs.changed == 'true'
+        run: |
+          pnpm exec turbo build --filter=gt-vue...
+          pnpm --filter gt-vue typecheck
+          pnpm --filter gt-vue test
+
   test-cli-binaries:
     strategy:
       matrix:
@@ -279,7 +326,8 @@ jobs:
           script: pnpm exec size-limit --json
 
   run-tests:
-    needs: [lint, tests, test-builds, test-cli-binaries, size]
+    needs:
+      [lint, tests, test-builds, test-vue-versions, test-cli-binaries, size]
     runs-on: ubuntu-latest
     steps:
       - run: echo "All tests passed"

.size-limit.cjs

@@ -38,6 +38,11 @@ const react = (name, file, limit = '50 kB') =>
     ignore: reactPeerIgnore,
   });
 
+const vue = (name, file, limit = '15 kB') =>
+  entry(name, `packages/vue/dist/${file}.mjs`, limit, {
+    ignore: ['vue'],
+  });
+
 const reactNode = (name, file, limit = '50 kB') =>
   nodeEntry(name, `packages/react/dist/${file}.mjs`, limit, {
     ignore: reactPeerIgnore,
@@ -91,6 +96,8 @@ module.exports = [
   i18n('gt-i18n', 'index'),
   i18n('gt-i18n/types', 'types'),
   i18n('gt-i18n/internal', 'internal'),
+  i18n('gt-i18n/internal/cookies', 'internal-cookies'),
+  i18n('gt-i18n/internal/string', 'internal-string'),
   i18n('gt-i18n/internal/types', 'internal-types'),
 
   reactCore('@generaltranslation/react-core/pure', 'pure'),
@@ -103,6 +110,8 @@ module.exports = [
   reactNode('gt-react (server)', 'index.server', '55 kB'),
   react('gt-react/macros', 'macros'),
 
+  vue('gt-vue', 'index'),
+
   next('gt-next (client)', 'index.client', '75 kB'),
   nextNode('gt-next (rsc)', 'index.rsc', '85 kB'),
   nextNode('gt-next (server)', 'index.server', '85 kB'),

README.md

@@ -35,6 +35,7 @@ Visit [https://generaltranslation.com/docs](https://generaltranslation.com/docs)
 | ------------------------------------------------------------------- | ------------------------------------------------- |
 | [gt-next](packages/next)                                            | Automatic i18n for Next.js                        |
 | [gt-react](packages/react)                                          | Automatic i18n for React                          |
+| [gt-vue](packages/vue)                                              | Lightweight i18n for Vue                          |
 | [gt-i18n](packages/i18n)                                            | Pure JavaScript i18n library                      |
 | [gt](packages/cli)                                                  | CLI tool for continuous localization              |
 | [gt-sanity](packages/sanity)                                        | Plugin for Sanity Studio v3                       |

packages/i18n/package.json

@@ -86,6 +86,26 @@
         "default": "./dist/internal.mjs"
       }
     },
+    "./internal/cookies": {
+      "require": {
+        "types": "./dist/internal-cookies.d.cts",
+        "default": "./dist/internal-cookies.cjs"
+      },
+      "import": {
+        "types": "./dist/internal-cookies.d.mts",
+        "default": "./dist/internal-cookies.mjs"
+      }
+    },
+    "./internal/string": {
+      "require": {
+        "types": "./dist/internal-string.d.cts",
+        "default": "./dist/internal-string.cjs"
+      },
+      "import": {
+        "types": "./dist/internal-string.d.mts",
+        "default": "./dist/internal-string.mjs"
+      }
+    },
     "./internal/types": {
       "require": {
         "types": "./dist/internal-types.d.cts",
@@ -105,6 +125,12 @@
       "internal": [
         "./dist/internal.d.cts"
       ],
+      "internal/cookies": [
+        "./dist/internal-cookies.d.cts"
+      ],
+      "internal/string": [
+        "./dist/internal-string.d.cts"
+      ],
       "internal/types": [
         "./dist/internal-types.d.cts"
       ]

packages/i18n/src/internal-cookies.ts

@@ -0,0 +1,11 @@
+export {
+  defaultEnableI18nCookieName,
+  defaultLocaleCookieName,
+  defaultRegionCookieName,
+  defaultResetLocaleCookieName,
+} from './utils/cookieNames';
+export {
+  getBrowserCookieValue,
+  setBrowserCookieValue,
+} from './utils/browserCookies';
+export { getCookieValue } from './utils/request';

packages/i18n/src/internal-string.ts

@@ -0,0 +1,4 @@
+export { decodeOptions } from './translation-functions/msg/decodeOptions';
+export { msgString } from './translation-functions/msg/msgString';
+export { isEncodedTranslationOptions } from './translation-functions/utils/isEncodedTranslationOptions';
+export { hashStringMessage } from './utils/hashStringMessage';

packages/i18n/src/translation-functions/msg/__tests__/msg.test.ts

@@ -1,6 +1,7 @@
 import { describe, it, expect } from 'vitest';
 import { msg } from '../msg';
 import { decodeMsg } from '../decodeMsg';
+import { decodeOptions } from '../decodeOptions';
 import { derive, declareVar } from 'generaltranslation/internal';
 import type { RegisterableMessages } from '../../types/message';
 
@@ -17,6 +18,20 @@ describe('msg function integration', () => {
     expect(decoded).toBe('Hello World');
   });
 
+  it('preserves literal braces for STRING messages', () => {
+    const result = msg('Hello {name}', {
+      $context: 'literal example',
+      $format: 'STRING',
+    });
+
+    expect(decodeMsg(result)).toBe('Hello {name}');
+    expect(decodeOptions(result)).toMatchObject({
+      $context: 'literal example',
+      $format: 'STRING',
+      $_source: 'Hello {name}',
+    });
+  });
+
   it('should not format variables in quoted text', () => {
     const result = msg("'Hello {name}'");
     const decoded = decodeMsg(result);

packages/i18n/src/translation-functions/msg/encodeMsg.ts

@@ -0,0 +1,10 @@
+import { encode } from 'generaltranslation/internal';
+import type { EncodedTranslationOptions } from '../types/options';
+
+/** Encodes message metadata for later resolution by an `m` function. */
+export function encodeMsg(
+  message: string,
+  options: EncodedTranslationOptions
+): string {
+  return `${message}:${encode(JSON.stringify(options))}`;
+}

packages/i18n/src/translation-functions/msg/msg.ts

@@ -4,7 +4,6 @@ import type {
 } from '../types/options';
 import { formatMessage } from '@generaltranslation/format';
 import {
-  encode,
   libraryDefaultLocale,
   VAR_IDENTIFIER,
 } from 'generaltranslation/internal';
@@ -13,6 +12,8 @@ import logger from '../../logs/logger';
 import { extractVariables } from '../../utils/extractVariables';
 import { hashMessage } from '../../utils/hashMessage';
 import { RegisterableMessages } from '../types/message';
+import { encodeMsg } from './encodeMsg';
+import { msgString } from './msgString';
 
 /**
  * Registers a message to be translated. Returns the message unchanged if no options are provided.
@@ -57,6 +58,8 @@ export function msg(
   message: RegisterableMessages,
   options?: GTTranslationOptions
 ): RegisterableMessages {
+  if (options?.$format === 'STRING') return msgString(message, options);
+
   // Handle array
   if (typeof message !== 'string') {
     if (!options) return message;
@@ -73,11 +76,8 @@ export function msg(
     return message;
   }
 
-  // Extract variables
   const variables = extractVariables(options);
-
-  // Interpolate string
-  let interpolatedString: string = message;
+  let interpolatedString: string;
   try {
     interpolatedString = formatMessage(message, {
       locales: [libraryDefaultLocale], // TODO: use compiler to insert locales
@@ -105,8 +105,5 @@ export function msg(
     $_source,
     $_hash,
   };
-  const optionsEncoding = encode(JSON.stringify(encodedOptions));
-
-  // Construct result
-  return `${interpolatedString}:${optionsEncoding}`;
+  return encodeMsg(interpolatedString, encodedOptions);
 }

packages/i18n/src/translation-functions/msg/msgString.ts

@@ -0,0 +1,42 @@
+import type { GTTranslationOptions } from '../types/options';
+import type { RegisterableMessages } from '../types/message';
+import { hashStringMessage } from '../../utils/hashStringMessage';
+import { encodeMsg } from './encodeMsg';
+
+/**
+ * Registers one or more literal STRING messages without applying ICU
+ * interpolation.
+ *
+ * Framework integrations should narrow the options they expose in their
+ * public API.
+ */
+export function msgString<T extends RegisterableMessages = string>(
+  message: T
+): T;
+export function msgString<T extends RegisterableMessages = string>(
+  message: T,
+  options?: GTTranslationOptions
+): T extends string ? string : string[];
+export function msgString(
+  message: RegisterableMessages,
+  options?: GTTranslationOptions
+): RegisterableMessages {
+  if (typeof message !== 'string') {
+    if (!options) return message;
+    return message.map((entry, index) =>
+      msgString(entry, {
+        ...options,
+        ...(options.$id && { $id: `${options.$id}.${index}` }),
+      })
+    );
+  }
+  if (!options) return message;
+
+  const stringOptions = { ...options, $format: 'STRING' as const };
+  const $_hash = hashStringMessage(message, stringOptions);
+  return encodeMsg(message, {
+    ...stringOptions,
+    $_hash,
+    $_source: message,
+  });
+}

packages/i18n/src/translation-functions/utils/__tests__/isEncodedTranslationOptions.test.ts

@@ -0,0 +1,16 @@
+import { describe, expect, it } from 'vitest';
+import { isEncodedTranslationOptions } from '../isEncodedTranslationOptions';
+
+describe('isEncodedTranslationOptions', () => {
+  it('accepts encoded empty source strings', () => {
+    expect(isEncodedTranslationOptions({ $_hash: 'hash', $_source: '' })).toBe(
+      true
+    );
+  });
+
+  it('rejects non-string encoded fields', () => {
+    expect(isEncodedTranslationOptions({ $_hash: {}, $_source: {} })).toBe(
+      false
+    );
+  });
+});

packages/i18n/src/translation-functions/utils/isEncodedTranslationOptions.ts

@@ -7,5 +7,8 @@ import { EncodedTranslationOptions } from '../types/options';
 export function isEncodedTranslationOptions(
   decodedOptions: Record<string, unknown> // TODO: next major version, this should be Record<string, string>
 ): decodedOptions is EncodedTranslationOptions {
-  return !!(decodedOptions.$_hash && decodedOptions.$_source);
+  return (
+    typeof decodedOptions.$_hash === 'string' &&
+    typeof decodedOptions.$_source === 'string'
+  );
 }

packages/i18n/src/utils/__tests__/browserCookies.test.ts

@@ -0,0 +1,51 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import {
+  getBrowserCookieValue,
+  setBrowserCookieValue,
+} from '../browserCookies';
+import {
+  defaultEnableI18nCookieName,
+  defaultLocaleCookieName,
+  defaultRegionCookieName,
+  defaultResetLocaleCookieName,
+} from '../cookieNames';
+
+describe('browser cookies', () => {
+  afterEach(() => vi.unstubAllGlobals());
+
+  it('keeps the canonical GT cookie names in one dependency-free module', () => {
+    expect(defaultLocaleCookieName).toBe('generaltranslation.locale');
+    expect(defaultRegionCookieName).toBe('generaltranslation.region');
+    expect(defaultEnableI18nCookieName).toBe('generaltranslation.enable-i18n');
+    expect(defaultResetLocaleCookieName).toBe(
+      'generaltranslation.locale-reset'
+    );
+  });
+
+  it('reads and decodes an exact browser cookie name', () => {
+    vi.stubGlobal('document', {
+      cookie:
+        'other=value; generaltranslation.locale=brand%2Dfrench%3Dca; generaltranslation.locale-extra=es',
+    });
+
+    expect(getBrowserCookieValue(defaultLocaleCookieName)).toBe(
+      'brand-french=ca'
+    );
+  });
+
+  it('writes the path-wide session-cookie contract used by GT web runtimes', () => {
+    const cookieDocument = { cookie: '' };
+    vi.stubGlobal('document', cookieDocument);
+
+    setBrowserCookieValue('custom-locale', 'fr-CA');
+
+    expect(cookieDocument.cookie).toBe('custom-locale=fr-CA;path=/');
+  });
+
+  it('does not access browser globals during SSR', () => {
+    expect(getBrowserCookieValue(defaultLocaleCookieName)).toBeUndefined();
+    expect(() =>
+      setBrowserCookieValue(defaultLocaleCookieName, 'fr')
+    ).not.toThrow();
+  });
+});