locadex 0.0.2-alpha.3 → 0.0.2-alpha.5

package/guides/next/basic/branches.md

@@ -41,11 +41,13 @@ Branch components use condition-based prop patterns:
 </Plural>
 ```
 
-### Integration with `<T>` Components [#branch-in-t]
+### Integration with `<T>` Components
 
 Branch components require translation context for localized content. Use within `<T>` components for automatic translation:
 
 ```tsx
+import { T, Branch } from 'gt-next';
+
 <T>
   <Branch
     branch={status}
@@ -54,18 +56,20 @@ Branch components require translation context for localized content. Use within
   >
     Status unknown
   </Branch>
-</T>
+</T>;
 ```
 
 The `<T>` component provides translation context and localizes branch content.
 
-### Pluralization Behavior [#plural-logic]
+### Pluralization Behavior
 
 **Automatic Rule Selection:** `<Plural>` uses Unicode CLDR rules to determine correct plural form based on `n` value and current locale.
 
 **Customization:** Override default plural forms with specific CLDR categories:
 
 ```tsx
+import { Plural } from 'gt-next';
+
 <Plural
   n={count}
   zero={<>No items</>}
@@ -78,7 +82,7 @@ The `<T>` component provides translation context and localizes branch content.
   // OR simplified
   singular={<>One item</>}
   plural={<>Multiple items</>}
-/>
+/>;
 ```
 
 **Available Forms:** zero, one, two, few, many, other, dual (locale-dependent), plus simplified singular/plural.
@@ -87,7 +91,7 @@ The `<T>` component provides translation context and localizes branch content.
 
 ## Implementation Examples
 
-### `<Branch>` - Conditional Logic Replacement [#branch-conditionals]
+### `<Branch>` - Conditional Logic Replacement
 
 **Replacing Ternary Operators:** Convert inline conditional logic to declarative branch syntax.
 
@@ -102,15 +106,39 @@ The `<T>` component provides translation context and localizes branch content.
 For example, if isActive is a boolean, convert it to a string first.
 
 **Replacing Conditional Rendering:** Convert `&&` operator patterns to branch syntax.
+This is only applicable if the content is being used in a `<T>` component.
+
+**Invalid Syntax**:
 
 ```tsx
-// Instead of: {isActive && <p>Active</p>}
-<Branch branch={isActive} true={<p>Active</p>}>
-  <></>
-</Branch>
+<T>{isActive && <p>Active</p>}</T>
 ```
 
-### `<Plural>` - Number-Based Rendering [#plural-numbers]
+**Valid Syntax**:
+
+```tsx
+<T>
+  <Branch branch={isActive} true={<p>Active</p>}>
+    <></>
+  </Branch>
+</T>
+```
+
+**Alternative Valid Syntax**:
+
+```tsx
+{
+  isActive && (
+    <T>
+      <p>Active</p>
+    </T>
+  );
+}
+```
+
+In this case, the `<T>` component is not wrapping the conditional, so the branch component is not needed.
+
+### `<Plural>` - Number-Based Rendering
 
 **Basic Pluralization:** Replace manual plural logic with locale-aware components.
 
@@ -227,7 +255,7 @@ import { T, Plural, Num } from 'gt-next';
 
 ## Common Implementation Issues
 
-### Missing Branch Values [#missing-branch]
+### Missing Branch Values
 
 **Critical:** Unmatched branch values fall back to children content. Ensure branch prop values match defined keys.
 
@@ -243,7 +271,7 @@ import { T, Plural, Num } from 'gt-next';
 
 **Rule:** Always provide fallback children for robust error handling.
 
-### Missing Plural Forms [#plural-locale]
+### Missing Plural Forms
 
 **Critical:** Provide required plural forms for your default locale to ensure fallback content availability.
 

package/guides/next/basic/client-side-components.md

@@ -1,14 +1,20 @@
-# Client-Side Component Internationalization
+# Client-Side Component Internationalization Guide
+
+RULES:
+
+- NEVER INTERNATIONALIZE ERROR STRINGS OR OTHER FUNCTIONAL STRINGS
+- Always use `<T>` for HTML/JSX content
+- Always add `'use client'` when working with `useGT()` and `useDict()`
 
 ## Available Methods
 
 Three methods exist for internationalizing client-side components:
 
-- `<T>` component (syntax identical to server-side) (STRONGLY PREFERRED)
-- `useGT()` hook (client-side specific) (string only)
-- `useDict()` hook (client-side specific) (string only)
+- `<T>` component (syntax identical to server-side) (For HTML/JSX content)
+- `useGT()` hook (client-side specific) (For string content)
+- `useDict()` hook (client-side specific) (For string content)
 
-**Importing:** The `useGT()` and `useDict()` hooks are exported from `gt-next/client`.
+**Imports:** The `useGT()` and `useDict()` hooks are exported from `gt-next/client`.
 
 ```tsx
 import { useGT } from 'gt-next/client';
@@ -20,9 +26,12 @@ The `<T>` component is exported from `gt-next`.
 import { T } from 'gt-next';
 ```
 
-## Critical Rule
+## RULES
 
-NEVER add React directives ("use client", "use server", etc.) when internationalizing components.
+- If a component is explicitly marked as async, this guide does NOT apply.
+  - You should refer to the server-side guide instead.
+- If you decided to use `useGT()` or `useDict()`, the file MUST have the "use client" directive at the top of the file.
+  - If it does not, you must add it.
 
 ## useGT() Hook
 
@@ -43,6 +52,7 @@ export default function Example() {
 **After internationalization:**
 
 ```jsx
+'use client'; // Must always add this directive when adding the useGT hook
 import { useGT } from 'gt-next/client';
 export default function Example() {
   const t = useGT();
@@ -53,7 +63,7 @@ export default function Example() {
 
 ### Important: T Component as Props
 
-**NEVER pass `<T>` components as props to non-gt-next components** - this will cause rendering errors.
+**NEVER pass `<T>` components as props to non gt-next components** - this will cause rendering errors.
 
 **Before internationalization:**
 
@@ -64,7 +74,7 @@ import { Dialog } from '@/primitives/Dialog';
 export default function Example() {
   return (
     <Dialog
-      title={<T>Delete document</T>}  // This will break!
+      title={<T>Delete document</T>} // This will break!
     />
   );
 }
@@ -73,6 +83,7 @@ export default function Example() {
 **After internationalization:**
 
 ```jsx
+'use client'; // Must always add this directive when adding the useGT hook
 import { useGT } from 'gt-next/client';
 import { Dialog } from '@/primitives/Dialog';
 
@@ -80,15 +91,15 @@ export default function Example() {
   const t = useGT();
   return (
     <Dialog
-      title={t('Delete document')}  // Use string for props
+      title={t('Delete document')} // Use string for props
     >
-      <T>This content works fine</T>  {/* T component in JSX content is OK */}
+      <T>This content works fine</T> {/* T component in JSX content is OK */}
     </Dialog>
   );
 }
 ```
 
-**Rule**: Use `useGT()` for component props, `<T>` only for JSX content.
+**Rule**: Use `useGT()` for strings, `<T>` only for JSX content.
 
 ### Reusable Content Pattern
 
@@ -103,7 +114,7 @@ export const content = 'hi';
 // Example 2
 export const nestedContent = {
   name: 'Brian',
-  title: 'Engineer',
+  description: 'Brian is an engineer',
 };
 ```
 
@@ -123,7 +134,7 @@ export const useNestedContent = () => {
   const t = useGT();
   return {
     name: 'Brian',
-    title: t('Engineer'),
+    description: t('Brian is an engineer'),
   };
 };
 ```
@@ -166,12 +177,9 @@ export default function NotificationComponent() {
 
 ```json
 {
-  "content": "hi",
-  "user": {
-    "profile": {
-      "name": "User Name",
-      "title": "Job Title"
-    }
+  "home": {
+    "name": "Home",
+    "description": "Home is a place where you live"
   }
 }
 ```
@@ -185,9 +193,8 @@ export default function MyComponent() {
   const t = useDict();
   return (
     <>
-      <div>{t('content')}</div>
-      <div>{t('user.profile.name')}</div>
-      <div>{t('user.profile.title')}</div>
+      <div>{t('home.name')}</div>
+      <div>{t('home.description')}</div>
     </>
   );
 }

package/guides/next/basic/jsx.md

@@ -2,6 +2,12 @@
 
 Use the `<T>` component to internationalize HTML and JSX content.
 
+**Import:** The `<T>` component is exported from `gt-next`.
+
+```tsx
+import { T } from 'gt-next';
+```
+
 Before:
 
 ```jsx
@@ -34,7 +40,10 @@ Add `context` prop when content meaning is ambiguous:
 </T>
 ```
 
-Rule: Provide context for words with multiple meanings (e.g., "toast" = bread vs notification).
+RULES:
+
+- Provide context for words with multiple meanings (e.g., "toast" = bread vs notification).
+- Provide context when the additional context can help the translator understand the meaning of the content.
 
 # Usage Rules
 
@@ -139,7 +148,7 @@ Solution: Wrap dynamic content in variable components or branching components, t
 </T>
 ```
 
-Note: `<T>` handles any nested content within the same component.
+NOTE: `<T>` handles any nested content within the same component.
 
 # Common Pitfalls
 

package/guides/next/basic/server-side-components.md

@@ -1,14 +1,14 @@
-# Server-Side Component Internationalization
+# Server-Side Component Internationalization Guide
 
 ## Available Methods
 
 Three methods exist for internationalizing server-side components:
 
-- `<T>` component (syntax identical to client-side) (STRONGLY PREFERRED)
-- `getGT()` function (server-side specific) (string only)
-- `getDict()` function (server-side specific) (string only)
+- `<T>` component (syntax identical to client-side) (For HTML/JSX content)
+- `getGT()` function (server-side specific) (For string content)
+- `getDict()` function (server-side specific) (For string content)
 
-**Importing:** The `getGT()` and `getDict()` functions are exported from `gt-next/server`.
+**Imports:** The `getGT()` and `getDict()` functions are exported from `gt-next/server`.
 
 ```tsx
 import { getGT } from 'gt-next/server';
@@ -20,9 +20,12 @@ The `<T>` component is exported from `gt-next`.
 import { T } from 'gt-next';
 ```
 
-## Critical Rule
+## RULES
 
-NEVER add React directives ("use client", "use server", etc.) when internationalizing components.
+- NEVER add "use server" to server-side components.
+- This guide only applies to async server-side components.
+  - If a component is not explicitly marked as async, this guide does NOT apply.
+  - You should refer to the client-side guide instead.
 
 ## getGT() Function
 
@@ -65,7 +68,7 @@ export const content = 'hi';
 // Example 2
 export const nestedContent = {
   name: 'Brian',
-  title: 'Engineer',
+  description: 'Brian is an engineer',
 };
 ```
 
@@ -85,7 +88,7 @@ export const useNestedContent = async () => {
   const t = await getGT();
   return {
     name: 'Brian',
-    title: t('Engineer'),
+    description: t('Brian is an engineer'),
   };
 };
 ```
@@ -124,11 +127,9 @@ export default async function NotificationComponent() {
 
 ```json
 {
-  "user": {
-    "profile": {
-      "name": "User Name",
-      "title": "Job Title"
-    }
+  "home": {
+    "name": "Home",
+    "description": "Home is a place where you live"
   }
 }
 ```
@@ -139,7 +140,7 @@ export default async function NotificationComponent() {
 import { getDict } from 'gt-next/server';
 export default async function MyComponent() {
   const t = await getDict();
-  return t('user.profile.name');
+  return t('home.description');
 }
 ```
 

package/guides/next/basic/strings.md

@@ -0,0 +1,144 @@
+# How to internationalize strings with `gt-next`
+
+Use `useGT()` and `getGT()` to internationalize strings.
+
+**RULES:**
+
+- For JSX and HTML content, ALWAYS use the `<T>` component over `useGT()` and `getGT()`.
+- If you see strings present in HTML that you think need pluralization, do not use strings. Instead use the `<T>` component and the `<Plural>` component. Read the "basic_next-branches" for instructions.
+- NEVER internationalize functional strings (error strings, logical strings, etc.) that could jeporadize the functionality of the application.
+
+**Import:** The `useGT()` and `getGT()` functions are exported from `gt-next/client` and `gt-next/server` respectively.
+
+```tsx
+import { useGT } from 'gt-next/client';
+import { getGT } from 'gt-next/server';
+```
+
+## Usage
+
+Both `useGT()` and `getGT()` return a translation function callback.
+Pass the string to the callback function to get the translated string.
+
+The usage of the callback is the same for both `useGT()` and `getGT()`.
+
+`getGT()` is asynchronous and returns a promise that resolves to the translation function callback.
+
+Before:
+
+```jsx
+function Greeting() {
+  const greeting = 'Hello, world!';
+  return greeting;
+}
+```
+
+After:
+
+```jsx
+'use client';
+import { useGT } from 'gt-next/client';
+
+function Greeting() {
+  const t = useGT();
+  const greeting = t('Hello, world!');
+  return greeting;
+}
+```
+
+### Server Side
+
+Before:
+
+```tsx
+export async function Greeting() {
+  const greeting = t('Hello, world!');
+  return greeting;
+}
+```
+
+After:
+
+```tsx
+import { getGT } from 'gt-next/server';
+
+export async function Greeting() {
+  const t = await getGT();
+  const greeting = t('Hello, world!');
+  return greeting;
+}
+```
+
+# Context Prop
+
+Add `context` when content meaning is ambiguous:
+
+```jsx
+'use client';
+import { useGT } from 'gt-next/client';
+
+function Greeting() {
+  const t = useGT();
+  const toast = t('Click on the toast to dismiss it.', {
+    context: 'toast, as in a pop-up notification',
+  });
+  return toast;
+}
+```
+
+RULES:
+
+- Provide context for words with multiple meanings (e.g., "toast" = bread vs notification).
+- Provide context when the additional context can help the translator understand the meaning of the content.
+
+# Usage Rules
+
+**USE `useGT()` and `getGT()` for:**
+
+- Static strings
+- Dynamic strings if escaped with `{}` syntax
+
+# Valid Usage Examples
+
+In the following examples, `t` is the translation function callback.
+
+```tsx
+const greeting = t('Hello, world!');
+```
+
+```tsx
+const greeting = t('Hello, {name}!', { variables: { name: 'John' } });
+```
+
+```tsx
+const message = t('You have {dollars} dollars!', {
+  variables: { dollars: 123 },
+  variableOptions: { dollars: { style: 'currency', currency: 'USD' } },
+});
+```
+
+`variables` is an object that maps variable names to their values.
+
+`variableOptions` is an object that maps variable names to their options.
+
+The options are the same as the options for the Intl.NumberFormat and Intl.DateTimeFormat APIs.
+
+# Invalid Usage Examples
+
+Never use the `${}` syntax for dynamic strings inside the translation callback.
+
+```tsx
+const invalidUsage = t(`Hello, ${name}!`);
+```
+
+Never use double curly braces `{{}}` to indicate variables
+
+```tsx
+const invalidUsage = t(`Hello, {{name}}!`);
+```
+
+Always add the `variable` key in the options field of `t()` when specifying variables. The following is invalid:
+
+```tsx
+const invalidUsage = t(`Hello, {name}!`, { name: 'Brian' });
+```

package/guides/next/basic/variables.md

@@ -15,16 +15,6 @@ import { Var, Num, Currency, DateTime } from 'gt-next';
 - `<Currency>`: Formats currency with symbols and localization
 - `<DateTime>`: Formats dates/times with locale conventions
 
-**Processing Model:**
-
-- JSX content → General Translation API for translation
-- Variable components → Local formatting only (never sent to API)
-- `<Num>`, `<Currency>`, `<DateTime>` → Use JS Intl API for locale formatting
-
-**Important:** Content wrapped in variable components is never sent to the General Translation API, ensuring data privacy and security.
-
-See the section on [Data Privacy](#privacy) for more information.
-
 ---
 
 ## Usage Patterns
@@ -34,13 +24,15 @@ See the section on [Data Privacy](#privacy) for more information.
 All variable components use identical wrapping syntax:
 
 ```tsx
-<Var>{user.name}</Var>
-<Num>{user.age}</Num>
-<Currency>{user.balance}</Currency>
-<DateTime>{user.birthday}</DateTime>
+import { Var, Num, Currency, DateTime } from 'gt-next';
+
+<Var>{user.name}</Var>;
+<Num>{user.age}</Num>;
+<Currency>{user.balance}</Currency>;
+<DateTime>{user.birthday}</DateTime>;
 ```
 
-### Integration with `<T>` Components [#variable-in-t]
+### Integration with `<T>` Components
 
 Variable components require locale context for formatting. Use within `<T>` components for automatic locale handling:
 
@@ -52,7 +44,7 @@ Variable components require locale context for formatting. Use within `<T>` comp
 
 The `<T>` component provides locale context and translates surrounding text while preserving variable formatting.
 
-### Localization Behavior [#localization]
+### Localization Behavior
 
 **Automatic Formatting:**
 
@@ -62,29 +54,13 @@ The `<T>` component provides locale context and translates surrounding text whil
 
 **Customization:** Override default locale and formatting via component props.
 
-### Data Privacy [#privacy]
-
-**Security Model:** Variable components process content locally and never send data to General Translation APIs.
+## Use Cases by Component
 
-**Use Cases by Component:**
-
-- `<Var>`: Unformatted private data (user names, account numbers)
+- `<Var>`: Unformatted private data (user names, account numbers), or conditional content that should be excluded from translation
 - `<Num>`: Private numbers needing locale formatting (quantities, ages, distances)
 - `<Currency>`: Private currency values (transactions, balances)
 - `<DateTime>`: Private dates/times (timestamps, creation dates)
 
-**Warning - API Data Transmission Rules:**
-- [Branching Components](/docs/next/guides/branches) and [`<T>` components](/docs/next/guides/jsx) → Sent to API
-- `<T>` nested inside `<Var>` → Sent to API
-
-```tsx
-<T>
-  <Var>
-    <T>Hello, World!</T> // → API Goodbye, World! // → Local only
-  </Var>
-</T>
-```
-
 ---
 
 ## Implementation Examples

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "locadex",
-  "version": "0.0.2-alpha.3",
+  "version": "0.0.2-alpha.5",
   "description": "An AI agent for internationalization",
   "main": "dist/index.js",
   "type": "module",
   "bin": {
     "locadex": "dist/cli.js",
-    "locadex-mcp": "dist/mcp.js"
+    "locadex-mcp": "dist/mcp.js",
+    "locadex-mcp-sse": "dist/mcp-sse.js"
   },
   "files": [
     "dist",
@@ -16,7 +17,7 @@
     "guides"
   ],
   "dependencies": {
-    "@anthropic-ai/claude-code": "^1.0.14",
+    "@anthropic-ai/claude-code": "^1.0.16",
     "@anthropic-ai/sdk": "^0.52.0",
     "@clack/prompts": "^1.0.0-alpha.1",
     "@modelcontextprotocol/sdk": "^1.12.0",
@@ -58,7 +59,7 @@
     "release:latest": "npm run build:release && npm publish --access public --tag latest",
     "test": "vitest run",
     "test:watch": "vitest",
-    "sentry:sourcemaps": "sentry-cli sourcemaps inject --org general-translation --project locadex ./dist && sentry-cli sourcemaps upload --org general-translation --project locadex ./dist"
+    "sentry:sourcemaps": "sentry-cli sourcemaps inject --org general-translation --project locadex ./dist && sentry-cli sourcemaps upload --org general-translation --project locadex ./dist --release=${npm_package_version}"
   },
   "repository": {
     "type": "git",

package/dist/logging/constructInfo.d.ts

@@ -1,3 +0,0 @@
-import { ClaudeSDKMessage } from '../types/claude-sdk.js';
-export declare function constructResultInfo(result: ClaudeSDKMessage): string;
-//# sourceMappingURL=constructInfo.d.ts.map

package/dist/logging/constructInfo.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"constructInfo.d.ts","sourceRoot":"/","sources":["logging/constructInfo.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE1D,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,gBAAgB,UAc3D"}

package/dist/logging/constructInfo.js

@@ -1,15 +0,0 @@
-
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="82a0b27e-2354-5b05-88ad-9a8482391e79")}catch(e){}}();
-export function constructResultInfo(result) {
-    if (result.type === 'result') {
-        if (result.subtype === 'success') {
-            return `Done!\nCost: $${Number(result.cost_usd).toFixed(2)}\nDuration: ${Number(result.duration_ms) / 1000}s`;
-        }
-        else {
-            return `Error: ${result.subtype}\nCost: $${result.cost_usd}\nDuration: ${Number(result.duration_ms) / 1000}s`;
-        }
-    }
-    return '';
-}
-//# sourceMappingURL=constructInfo.js.map
-//# debugId=82a0b27e-2354-5b05-88ad-9a8482391e79

package/dist/logging/constructInfo.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"constructInfo.js","sources":["logging/constructInfo.ts"],"sourceRoot":"/","sourcesContent":["import { ClaudeSDKMessage } from '../types/claude-sdk.js';\n\nexport function constructResultInfo(result: ClaudeSDKMessage) {\n  if (result.type === 'result') {\n    if (result.subtype === 'success') {\n      return `Done!\\nCost: $${Number(result.cost_usd).toFixed(2)}\\nDuration: ${\n        Number(result.duration_ms) / 1000\n      }s`;\n    } else {\n      return `Error: ${result.subtype}\\nCost: $${result.cost_usd}\\nDuration: ${\n        Number(result.duration_ms) / 1000\n      }s`;\n    }\n  }\n\n  return '';\n}\n"],"names":[],"mappings":";;AAEA,MAAM,UAAU,mBAAmB,CAAC,MAAwB;IAC1D,IAAI,MAAM,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC7B,IAAI,MAAM,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;YACjC,OAAO,iBAAiB,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,eACxD,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,GAAG,IAC/B,GAAG,CAAC;QACN,CAAC;aAAM,CAAC;YACN,OAAO,UAAU,MAAM,CAAC,OAAO,YAAY,MAAM,CAAC,QAAQ,eACxD,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,GAAG,IAC/B,GAAG,CAAC;QACN,CAAC;IACH,CAAC;IAED,OAAO,EAAE,CAAC;AACZ,CAAC","debug_id":"82a0b27e-2354-5b05-88ad-9a8482391e79"}

package/dist/mcp/tools/fileManager.d.ts

@@ -1,6 +0,0 @@
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-export declare const fileManagerTools: {
-    [id: string]: string;
-};
-export declare function addFileManagerTools(server: McpServer, stateFilePath: string): void;
-//# sourceMappingURL=fileManager.d.ts.map

package/dist/mcp/tools/fileManager.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"fileManager.d.ts","sourceRoot":"/","sources":["mcp/tools/fileManager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAIpE,eAAO,MAAM,gBAAgB,EAAE;IAAE,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAAA;CAYpD,CAAC;AAqCF,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,QA6O3E"}