gtx-cli 2.6.17 → 2.6.19

package/dist/setup/instructions/gt-next.md

@@ -0,0 +1,107 @@
+# gt-next
+
+This project is using the `gt-next` internationalization library for Next.js App Router.
+
+## gt-next setup
+
+- `GTProvider` must wrap the app in the root layout to provide translation context.
+- The `withGTConfig()` plugin wraps `next.config` in the Next.js config file.
+- (optional) `createNextMiddleware()` is used in `proxy.ts` for automatic locale routing.
+
+## Translating JSX
+
+`gt-next` uses the `<T>` component for translation.
+
+Pass JSX content as the direct children of `<T>` to translate it. Children of `<T>` must be static — no JS expressions or variables directly inside.
+
+```jsx
+import { T } from 'gt-next';
+
+<T>
+  <h1>Welcome to our store</h1>
+  <p>
+    Browse our <a href='/products'>latest products</a> and find something you
+    love.
+  </p>
+</T>;
+```
+
+You can also add a `context` prop to `<T>` to give context to the translator. For example:
+
+```jsx
+import { T } from 'gt-next';
+
+<T context="Cookies as in web cookies">
+  View your <a href="/cookies">Cookies</a>
+</T>;
+```
+
+## Translating simple strings
+
+Use the `gt` function returned by the `useGT()` hook to translate strings directly. Invoke `useGT()` in synchronous components or `await getGT()` in async components only.
+
+```js
+import { useGT } from 'gt-next';
+const gt = useGT();
+gt('Hello, world!'); // returns "Hola, mundo"
+```
+
+```js
+import { getGT } from 'gt-next/server';
+const gt = await getGT(); // use await version in async components only
+gt('Hello, world!');
+```
+
+- Just like with the children of the `<T>` component, all strings passed to `gt()` must be static string literals. No variables or template literals.
+
+## Translating shared or out-of-scope strings
+
+Use `msg()` to register strings for translation, and `useMessages()` to translate them. `const m = useMessages()` should be used equivalently to `const gt = useGT()`.
+
+```js
+import { msg, useMessages } from 'gt-next';
+
+const greeting = msg('Hello, world!');
+
+export default function Greeting() {
+  const m = useMessages();
+  return <p>{m(greeting)}</p>;
+}
+```
+
+- All strings passed to `msg()` must be static string literals. No variables or template literals.
+- Use the equivalent `await getMessages()` for async components.
+- `useMessages()` / `getMessages()` take no arguments.
+
+## Dynamic content inside `<T>`
+
+Use variable components for dynamic values inside `<T>`:
+
+- `<Var>{value}</Var>` — variables (strings, numbers, etc.)
+- `<Num>{value}</Num>` — formatted numbers
+- `<Currency>{value}</Currency>` — formatted currency
+- `<DateTime>{value}</DateTime>` — formatted dates/times
+
+```jsx
+import { T, Var, Num } from 'gt-next';
+
+<T>
+  <Var>{userName}</Var> ordered <Num>{itemCount}</Num> items.
+</T>;
+```
+
+## Utility hooks
+
+### `useLocale()`
+
+`useLocale` returns the user's current language, as a BCP 47 locale tag.
+
+```js
+import { useLocale } from 'gt-next'
+
+const locale = useLocale(); // "en-US"
+```
+
+## Quickstart
+
+See <https://generaltranslation.com/docs/next.md>

package/dist/setup/instructions/gt-react.md

@@ -0,0 +1,98 @@
+# gt-react
+
+This project is using the `gt-react` internationalization library.
+
+## gt-react setup
+
+- `GTProvider` must wrap the app in the root layout to provide translation context.
+
+## Translating JSX
+
+`gt-react` uses the `<T>` component for translation.
+
+Pass JSX content as the direct children of `<T>` to translate it. Children of `<T>` must be static — no JS expressions or variables directly inside.
+
+```jsx
+import { T } from 'gt-react';
+
+<T>
+  <h1>Welcome to our store</h1>
+  <p>
+    Browse our <a href='/products'>latest products</a> and find something you
+    love.
+  </p>
+</T>;
+```
+
+You can also add a `context` prop to `<T>` to give context to the translator. For example:
+
+```jsx
+import { T } from 'gt-react';
+
+<T context="Cookies as in web cookies">
+  View your <a href="/cookies">Cookies</a>
+</T>;
+```
+
+## Translating simple strings
+
+Use the `gt` function returned by the `useGT()` hook to translate strings directly.
+
+```js
+import { useGT } from 'gt-react';
+const gt = useGT();
+gt('Hello, world!'); // returns "Hola, mundo"
+```
+
+- Just like with the children of the `<T>` component, all strings passed to `gt()` must be static string literals. No variables or template literals.
+
+## Translating shared or out-of-scope strings
+
+Use `msg()` to register strings for translation, and `useMessages()` to translate them. `const m = useMessages()` should be used equivalently to `const gt = useGT()`.
+
+```js
+import { msg, useMessages } from 'gt-react';
+
+const greeting = msg('Hello, world!');
+
+export default function Greeting() {
+  const m = useMessages();
+  return <p>{m(greeting)}</p>;
+}
+```
+
+- All strings passed to `msg()` must be static string literals. No variables or template literals.
+- `useMessages()` / `getMessages()` take no arguments.
+
+## Dynamic content inside `<T>`
+
+Use variable components for dynamic values inside `<T>`:
+
+- `<Var>{value}</Var>` — variables (strings, numbers, etc.)
+- `<Num>{value}</Num>` — formatted numbers
+- `<Currency>{value}</Currency>` — formatted currency
+- `<DateTime>{value}</DateTime>` — formatted dates/times
+
+```jsx
+import { T, Var, Num } from 'gt-react';
+
+<T>
+  <Var>{userName}</Var> ordered <Num>{itemCount}</Num> items.
+</T>;
+```
+
+## Utility hooks
+
+### `useLocale()`
+
+`useLocale` returns the user's current language, as a BCP 47 locale tag.
+
+```js
+import { useLocale } from 'gt-react'
+
+const locale = useLocale(); // "en-US"
+```
+
+## Quickstart
+
+See <https://generaltranslation.com/docs/react.md>

package/dist/setup/wizard.js

@@ -15,6 +15,7 @@ import { loadConfig } from '../fs/config/loadConfig.js';
 import { addVitePlugin } from '../react/parse/addVitePlugin/index.js';
 import { exitSync } from '../console/logging.js';
 import { getFrameworkDisplayName } from './frameworkUtils.js';
+import { Libraries } from '../types/libraries.js';
 export async function handleSetupReactCommand(options, frameworkObject, useDefaults = false) {
     const frameworkDisplayName = getFrameworkDisplayName(frameworkObject);
     // Ask user for confirmation using inquirer
@@ -62,20 +63,20 @@ Please let us know what you would like to see added at https://github.com/genera
     }
     // Check if gt-next or gt-react is installed
     if (frameworkType === 'next-app' &&
-        !isPackageInstalled('gt-next', packageJson)) {
+        !isPackageInstalled(Libraries.GT_NEXT, packageJson)) {
         const packageManager = await getPackageManager();
         const spinner = logger.createSpinner('timer');
-        spinner.start(`Installing gt-next with ${packageManager.name}...`);
-        await installPackage('gt-next', packageManager);
-        spinner.stop(chalk.green('Automatically installed gt-next.'));
+        spinner.start(`Installing ${Libraries.GT_NEXT} with ${packageManager.name}...`);
+        await installPackage(Libraries.GT_NEXT, packageManager);
+        spinner.stop(chalk.green(`Automatically installed ${Libraries.GT_NEXT}.`));
     }
     else if (['next-pages', 'react', 'redwood', 'vite', 'gatsby'].includes(frameworkType) &&
-        !isPackageInstalled('gt-react', packageJson)) {
+        !isPackageInstalled(Libraries.GT_REACT, packageJson)) {
         const packageManager = await getPackageManager();
         const spinner = logger.createSpinner('timer');
-        spinner.start(`Installing gt-react with ${packageManager.name}...`);
-        await installPackage('gt-react', packageManager);
-        spinner.stop(chalk.green('Automatically installed gt-react.'));
+        spinner.start(`Installing ${Libraries.GT_REACT} with ${packageManager.name}...`);
+        await installPackage(Libraries.GT_REACT, packageManager);
+        spinner.stop(chalk.green(`Automatically installed ${Libraries.GT_REACT}.`));
     }
     const errors = [];
     const warnings = [];
@@ -105,7 +106,7 @@ Please let us know what you would like to see added at https://github.com/genera
         const spinner = logger.createSpinner();
         spinner.start('Wrapping JSX content with <T> tags...');
         // Wrap all JSX elements in the src directory with a <T> tag, with unique ids
-        const { filesUpdated: filesUpdatedNext } = await wrapContentNext(mergeOptions, 'gt-next', errors, warnings);
+        const { filesUpdated: filesUpdatedNext } = await wrapContentNext(mergeOptions, Libraries.GT_NEXT, errors, warnings);
         filesUpdated = [...filesUpdated, ...filesUpdatedNext];
         spinner.stop(chalk.green(`Success! Updated ${chalk.bold.cyan(filesUpdated.length)} files:\n`) + filesUpdated.map((file) => `${chalk.green('-')} ${file}`).join('\n'));
         // Add the withGTConfig() function to the next.config.js file

package/dist/translation/parse.d.ts

@@ -1,5 +1,6 @@
 import { Updates, TranslateFlags } from '../types/index.js';
 import type { ParsingConfigOptions } from '../types/parsing.js';
+import { InlineLibrary } from '../types/libraries.js';
 /**
  * Searches for gt-react or gt-next dictionary files and creates updates for them,
  * as well as inline updates for <T> tags and useGT()/getGT() calls
@@ -9,7 +10,7 @@ import type { ParsingConfigOptions } from '../types/parsing.js';
  * @param pkg - The package name
  * @returns An object containing the updates and errors
  */
-export declare function createUpdates(options: TranslateFlags, src: string[] | undefined, sourceDictionary: string | undefined, pkg: 'gt-react' | 'gt-next', validate: boolean, parsingOptions: ParsingConfigOptions): Promise<{
+export declare function createUpdates(options: TranslateFlags, src: string[] | undefined, sourceDictionary: string | undefined, pkg: InlineLibrary, validate: boolean, parsingOptions: ParsingConfigOptions): Promise<{
     updates: Updates;
     errors: string[];
     warnings: string[];

package/dist/translation/stage.d.ts

@@ -1,2 +1,3 @@
 import { Settings, TranslateFlags, Updates } from '../types/index.js';
-export declare function aggregateReactTranslations(options: TranslateFlags, settings: Settings, library: 'gt-react' | 'gt-next'): Promise<Updates>;
+import { InlineLibrary } from '../types/libraries.js';
+export declare function aggregateInlineTranslations(options: TranslateFlags, settings: Settings, library: InlineLibrary): Promise<Updates>;

package/dist/translation/stage.js

@@ -3,7 +3,7 @@ import chalk from 'chalk';
 import findFilepath from '../fs/findFilepath.js';
 import { logger } from '../console/logger.js';
 import { createUpdates } from './parse.js';
-export async function aggregateReactTranslations(options, settings, library) {
+export async function aggregateInlineTranslations(options, settings, library) {
     if (!options.dictionary) {
         options.dictionary = findFilepath([
             './dictionary.js',

package/dist/translation/validate.d.ts

@@ -1,4 +1,5 @@
-import { Options, Settings } from '../types/index.js';
+import { Framework, Options, Settings } from '../types/index.js';
+import { InlineLibrary } from '../types/libraries.js';
 export type ValidationLevel = 'error' | 'warning';
 export type ValidationMessage = {
     level: ValidationLevel;
@@ -9,5 +10,5 @@ export type ValidationResult = Record<string, ValidationMessage[]>;
  * Programmatic API for validation - returns structured results instead of logging/exiting.
  * Equivalent to running `gtx-cli validate` but returns data.
  */
-export declare function getValidateJson(settings: Options & Settings, pkg: 'gt-react' | 'gt-next', files?: string[]): Promise<ValidationResult>;
-export declare function validateProject(settings: Options & Settings, pkg: 'gt-react' | 'gt-next', files?: string[]): Promise<void>;
+export declare function getValidateJson(settings: Options & Settings, pkg: Framework, files?: string[]): Promise<ValidationResult>;
+export declare function validateProject(settings: Options & Settings, pkg: InlineLibrary, files?: string[]): Promise<void>;

package/dist/types/index.d.ts

@@ -1,6 +1,7 @@
 import { CustomMapping } from 'generaltranslation/types';
 import { SUPPORTED_FILE_EXTENSIONS } from '../formats/files/supportedFiles.js';
 import { ParsingConfigOptions } from './parsing.js';
+import { Libraries, InlineLibrary } from './libraries.js';
 export type { Updates } from 'generaltranslation/types';
 export type Options = {
     config: string;
@@ -95,7 +96,7 @@ export type GenerateSourceOptions = {
     ignoreErrors: boolean;
     suppressWarnings: boolean;
 };
-export type Framework = 'gt-next' | 'gt-react';
+export type Framework = typeof Libraries.GT_NEXT | typeof Libraries.GT_REACT | typeof Libraries.GT_REACT_NATIVE;
 export type FrameworkObject = {
     name: 'mintlify';
     type?: undefined;
@@ -111,7 +112,7 @@ export type SupportedFrameworks = FrameworkObject['name'];
 export type SupportedReactFrameworks = Extract<FrameworkObject, {
     type: 'react';
 }>['name'];
-export type SupportedLibraries = 'gt-next' | 'gt-react' | 'next-intl' | 'react-i18next' | 'next-i18next' | 'i18next' | 'i18next-icu' | 'base';
+export type SupportedLibraries = InlineLibrary | 'next-intl' | 'react-i18next' | 'next-i18next' | 'i18next' | 'i18next-icu' | 'base';
 export interface ContentScanner {
     scanForContent(options: WrapOptions, framework: Framework): Promise<{
         errors: string[];

package/dist/types/libraries.d.ts

@@ -0,0 +1,31 @@
+/**
+ * A list of all the libraries names supported by the CLI
+ */
+export declare enum Libraries {
+    GT_REACT = "gt-react",
+    GT_NEXT = "gt-next",
+    GT_REACT_NATIVE = "gt-react-native",
+    GT_NODE = "gt-node",
+    GT_I18N = "gt-i18n",
+    GT_REACT_CORE = "@generaltranslation/react-core"
+}
+/**
+ * A list of all the libraries that support the CLI
+ */
+export declare const GT_LIBRARIES: readonly [Libraries.GT_REACT, Libraries.GT_NEXT, Libraries.GT_REACT_NATIVE, Libraries.GT_NODE, Libraries.GT_I18N, Libraries.GT_REACT_CORE];
+export type GTLibrary = (typeof GT_LIBRARIES)[number];
+/**
+ * Libraries that support inline translation
+ */
+export declare const INLINE_LIBRARIES: readonly [Libraries.GT_REACT, Libraries.GT_NEXT, Libraries.GT_NODE, Libraries.GT_REACT_NATIVE, Libraries.GT_REACT_CORE, Libraries.GT_I18N];
+export type InlineLibrary = (typeof INLINE_LIBRARIES)[number];
+export declare function isInlineLibrary(lib: string): lib is InlineLibrary;
+/**
+ * Libraries that support react primitives
+ */
+export declare const REACT_LIBRARIES: readonly [Libraries.GT_NEXT, Libraries.GT_REACT, Libraries.GT_REACT_NATIVE, Libraries.GT_REACT_CORE];
+export type ReactLibrary = (typeof REACT_LIBRARIES)[number];
+/**
+ * A mapping of each library to their upstream dependencies for filtering imports
+ */
+export declare const GT_LIBRARIES_UPSTREAM: Record<GTLibrary, GTLibrary[]>;

package/dist/types/libraries.js

@@ -0,0 +1,72 @@
+/**
+ * A list of all the libraries names supported by the CLI
+ */
+export var Libraries;
+(function (Libraries) {
+    Libraries["GT_REACT"] = "gt-react";
+    Libraries["GT_NEXT"] = "gt-next";
+    Libraries["GT_REACT_NATIVE"] = "gt-react-native";
+    Libraries["GT_NODE"] = "gt-node";
+    Libraries["GT_I18N"] = "gt-i18n";
+    Libraries["GT_REACT_CORE"] = "@generaltranslation/react-core";
+})(Libraries || (Libraries = {}));
+/**
+ * A list of all the libraries that support the CLI
+ */
+export const GT_LIBRARIES = [
+    Libraries.GT_REACT,
+    Libraries.GT_NEXT,
+    Libraries.GT_REACT_NATIVE,
+    Libraries.GT_NODE,
+    Libraries.GT_I18N,
+    Libraries.GT_REACT_CORE,
+];
+/**
+ * Libraries that support inline translation
+ */
+export const INLINE_LIBRARIES = [
+    Libraries.GT_REACT,
+    Libraries.GT_NEXT,
+    Libraries.GT_NODE,
+    Libraries.GT_REACT_NATIVE,
+    Libraries.GT_REACT_CORE,
+    Libraries.GT_I18N,
+];
+export function isInlineLibrary(lib) {
+    return INLINE_LIBRARIES.includes(lib);
+}
+/**
+ * Libraries that support react primitives
+ */
+export const REACT_LIBRARIES = [
+    Libraries.GT_NEXT,
+    Libraries.GT_REACT,
+    Libraries.GT_REACT_NATIVE,
+    Libraries.GT_REACT_CORE,
+];
+/**
+ * A mapping of each library to their upstream dependencies for filtering imports
+ */
+export const GT_LIBRARIES_UPSTREAM = {
+    [Libraries.GT_NEXT]: [
+        Libraries.GT_I18N,
+        Libraries.GT_REACT_CORE,
+        Libraries.GT_REACT,
+        Libraries.GT_NEXT,
+    ],
+    [Libraries.GT_REACT]: [
+        Libraries.GT_I18N,
+        Libraries.GT_REACT_CORE,
+        Libraries.GT_REACT,
+        Libraries.GT_REACT_NATIVE, // allow for cross-library compatibility (gt-react/gt-react-native only)
+    ],
+    [Libraries.GT_REACT_NATIVE]: [
+        Libraries.GT_I18N,
+        Libraries.GT_REACT_CORE,
+        Libraries.GT_REACT_NATIVE,
+        Libraries.GT_REACT, // allow for cross-library compatibility (gt-react/gt-react-native only)
+    ],
+    [Libraries.GT_NODE]: [Libraries.GT_I18N, Libraries.GT_NODE],
+    [Libraries.GT_REACT_CORE]: [Libraries.GT_I18N, Libraries.GT_REACT_CORE],
+    [Libraries.GT_I18N]: [Libraries.GT_I18N],
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gtx-cli",
-  "version": "2.6.17",
+  "version": "2.6.19",
   "main": "dist/index.js",
   "bin": "dist/main.js",
   "files": [
@@ -134,10 +134,10 @@
     "typescript": "^5.5.4"
   },
   "scripts": {
-    "build": "node scripts/generate-version.js && tsc",
+    "build": "node scripts/generate-version.js && tsc && rm -rf dist/setup/instructions && cp -r src/setup/instructions dist/setup/instructions",
     "build:clean": "sh ../../scripts/clean.sh && pnpm bin:restore && rm -rf binaries && pnpm run build",
     "build:release": "pnpm run build:clean",
-    "build:bin": "node scripts/generate-version.js && tsc && sh scripts/build-exe.sh all",
+    "build:bin": "node scripts/generate-version.js && tsc && rm -rf dist/setup/instructions && cp -r src/setup/instructions dist/setup/instructions && sh scripts/build-exe.sh all",
     "build:bin:clean": "sh ../../scripts/clean.sh && rm -rf binaries && pnpm run build:bin",
     "build:bin:release": "pnpm run build:bin:clean && pnpm run build:bin",
     "build:bin:darwin-x64": "sh scripts/build-exe.sh darwin-x64",