locadex 0.0.1 → 0.0.2-alpha.3

package/dist/utils/getPaths.js

@@ -1,7 +1,23 @@
+
+!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]="753d767d-b755-5567-ae1a-f45989169bc4")}catch(e){}}();
 import path, { dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
-var __dirname = dirname(fileURLToPath(import.meta.url));
+import fs from 'node:fs';
+const __dirname = dirname(fileURLToPath(import.meta.url));
 export function fromPackageRoot(relative) {
-    return path.resolve(__dirname, "../../", relative);
+    return path.resolve(__dirname, `../../`, relative);
 }
-//# sourceMappingURL=getPaths.js.map
+export function getLocadexVersion() {
+    const packageJsonPath = fromPackageRoot('package.json');
+    if (!fs.existsSync(packageJsonPath)) {
+        return 'unknown';
+    }
+    try {
+        return JSON.parse(fs.readFileSync(packageJsonPath, 'utf8')).version;
+    }
+    catch (error) {
+        return 'unknown';
+    }
+}
+//# sourceMappingURL=getPaths.js.map
+//# debugId=753d767d-b755-5567-ae1a-f45989169bc4

package/dist/utils/getPaths.js.map

@@ -1 +1 @@
-{"version":3,"file":"getPaths.js","sourceRoot":"","sources":["../../src/utils/getPaths.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,EAAE,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,IAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAE1D,MAAM,UAAU,eAAe,CAAC,QAAgB;IAC9C,OAAO,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;AACrD,CAAC"}
+{"version":3,"file":"getPaths.js","sources":["utils/getPaths.ts"],"sourceRoot":"/","sourcesContent":["import path, { dirname } from 'node:path';\nimport { fileURLToPath } from 'node:url';\nimport fs from 'node:fs';\n\nconst __dirname = dirname(fileURLToPath(import.meta.url));\n\nexport function fromPackageRoot(relative: string) {\n  return path.resolve(__dirname, `../../`, relative);\n}\n\nexport function getLocadexVersion(): string {\n  const packageJsonPath = fromPackageRoot('package.json');\n\n  if (!fs.existsSync(packageJsonPath)) {\n    return 'unknown';\n  }\n  try {\n    return JSON.parse(fs.readFileSync(packageJsonPath, 'utf8')).version;\n  } catch (error) {\n    return 'unknown';\n  }\n}\n"],"names":[],"mappings":";;AAAA,OAAO,IAAI,EAAE,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,MAAM,SAAS,CAAC;AAEzB,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAE1D,MAAM,UAAU,eAAe,CAAC,QAAgB;IAC9C,OAAO,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;AACrD,CAAC;AAED,MAAM,UAAU,iBAAiB;IAC/B,MAAM,eAAe,GAAG,eAAe,CAAC,cAAc,CAAC,CAAC;IAExD,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,eAAe,CAAC,EAAE,CAAC;QACpC,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,eAAe,EAAE,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC;IACtE,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC","debug_id":"753d767d-b755-5567-ae1a-f45989169bc4"}

package/dist/utils/mcpConfig.d.ts

@@ -0,0 +1,10 @@
+export declare const mcpConfig: {
+    mcpServers: {
+        locadex: {
+            command: string;
+            args: string[];
+            env: {};
+        };
+    };
+};
+//# sourceMappingURL=mcpConfig.d.ts.map

package/dist/utils/mcpConfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcpConfig.d.ts","sourceRoot":"/","sources":["utils/mcpConfig.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,SAAS;;;;;;;;CAQrB,CAAC"}

package/dist/utils/mcpConfig.js

@@ -0,0 +1,13 @@
+
+!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]="7f14296e-5624-5b6f-8a78-0532dfec7bd1")}catch(e){}}();
+export const mcpConfig = {
+    mcpServers: {
+        locadex: {
+            command: 'npx',
+            args: ['-y', 'locadex-mcp'],
+            env: {},
+        },
+    },
+};
+//# sourceMappingURL=mcpConfig.js.map
+//# debugId=7f14296e-5624-5b6f-8a78-0532dfec7bd1

package/dist/utils/mcpConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcpConfig.js","sources":["utils/mcpConfig.ts"],"sourceRoot":"/","sourcesContent":["export const mcpConfig = {\n  mcpServers: {\n    locadex: {\n      command: 'npx',\n      args: ['-y', 'locadex-mcp'],\n      env: {},\n    },\n  },\n};\n"],"names":[],"mappings":";;AAAA,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB,UAAU,EAAE;QACV,OAAO,EAAE;YACP,OAAO,EAAE,KAAK;YACd,IAAI,EAAE,CAAC,IAAI,EAAE,aAAa,CAAC;YAC3B,GAAG,EAAE,EAAE;SACR;KACF;CACF,CAAC","debug_id":"7f14296e-5624-5b6f-8a78-0532dfec7bd1"}

package/dist/utils/shared.d.ts

@@ -0,0 +1,2 @@
+export declare const EXCLUDED_DIRS: string[];
+//# sourceMappingURL=shared.d.ts.map

package/dist/utils/shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.d.ts","sourceRoot":"/","sources":["utils/shared.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,aAAa,UAUzB,CAAC"}

package/dist/utils/shared.js

@@ -0,0 +1,15 @@
+
+!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]="86a6bbba-8470-5393-a187-f9281d22e29b")}catch(e){}}();
+export const EXCLUDED_DIRS = [
+    './node_modules',
+    './.git',
+    './.locadex',
+    './.next',
+    './dist',
+    './build',
+    './out',
+    './public',
+    './static',
+];
+//# sourceMappingURL=shared.js.map
+//# debugId=86a6bbba-8470-5393-a187-f9281d22e29b

package/dist/utils/shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.js","sources":["utils/shared.ts"],"sourceRoot":"/","sourcesContent":["export const EXCLUDED_DIRS = [\n  './node_modules',\n  './.git',\n  './.locadex',\n  './.next',\n  './dist',\n  './build',\n  './out',\n  './public',\n  './static',\n];\n"],"names":[],"mappings":";;AAAA,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,gBAAgB;IAChB,QAAQ;IACR,YAAY;IACZ,SAAS;IACT,QAAQ;IACR,SAAS;IACT,OAAO;IACP,UAAU;IACV,UAAU;CACX,CAAC","debug_id":"86a6bbba-8470-5393-a187-f9281d22e29b"}

package/dist/utils/validateConfig.d.ts

@@ -0,0 +1,2 @@
+export declare function validateInitialConfig(): void;
+//# sourceMappingURL=validateConfig.d.ts.map

package/dist/utils/validateConfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validateConfig.d.ts","sourceRoot":"/","sources":["utils/validateConfig.ts"],"names":[],"mappings":"AAEA,wBAAgB,qBAAqB,SAQpC"}

package/dist/utils/validateConfig.js

@@ -0,0 +1,12 @@
+
+!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]="58e02bc2-5220-52f6-873e-12b0d3b04571")}catch(e){}}();
+import { logger } from '../logging/logger.js';
+export function validateInitialConfig() {
+    // Validate ANTHROPIC_API_KEY
+    if (!process.env.ANTHROPIC_API_KEY) {
+        logger.error('ANTHROPIC_API_KEY is not set! Please set it as an environment variable or in a .env | .env.local file.');
+        process.exit(1);
+    }
+}
+//# sourceMappingURL=validateConfig.js.map
+//# debugId=58e02bc2-5220-52f6-873e-12b0d3b04571

package/dist/utils/validateConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validateConfig.js","sources":["utils/validateConfig.ts"],"sourceRoot":"/","sourcesContent":["import { logger } from '../logging/logger.js';\n\nexport function validateInitialConfig() {\n  // Validate ANTHROPIC_API_KEY\n  if (!process.env.ANTHROPIC_API_KEY) {\n    logger.error(\n      'ANTHROPIC_API_KEY is not set! Please set it as an environment variable or in a .env | .env.local file.'\n    );\n    process.exit(1);\n  }\n}\n"],"names":[],"mappings":";;AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAE9C,MAAM,UAAU,qBAAqB;IACnC,6BAA6B;IAC7B,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,iBAAiB,EAAE,CAAC;QACnC,MAAM,CAAC,KAAK,CACV,wGAAwG,CACzG,CAAC;QACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC","debug_id":"58e02bc2-5220-52f6-873e-12b0d3b04571"}

package/guides/next/advanced/complicated-mapping-expressions.md

@@ -0,0 +1,200 @@
+# Internationalization Patterns for Dynamic Content
+
+**Objective**: Implement internationalization for mapping expressions using `<T>`, `useGT()`/`getGT()`, and `useDict()`/`getDict()`.
+
+## Core Principles
+
+### `<T>` Component Usage
+
+**Rule**: `<T>` components translate static JSX content only. Dynamic content requires alternative approaches.
+
+**Valid pattern**:
+```jsx
+<T>
+  <div> Here's some translated text </div>
+  Here is some more translated text!
+</T>
+```
+
+**Invalid pattern** - `<T>` cannot process dynamic mapping:
+```jsx
+const MyComponent = () => {
+  const someList = [
+    <div>Hello Archie</div>,
+    <div>Hello Ernest</div>,
+    <div>Hello Brian</div>,
+  ];
+  return <T>{someList.map((item) => item)}</T>; // INVALID
+};
+```
+
+**Solution**: Apply `<T>` to individual static items, not the mapping operation:
+```jsx
+const MyComponent = () => {
+  const someList = [
+    <T><div>Hello Archie</div></T>,
+    <T><div>Hello Ernest</div></T>,
+    <T><div>Hello Brian</div></T>,
+  ];
+  return <>{someList.map((item) => item)}</>;
+};
+```
+
+**Key requirement**: Each `<T>` component must have direct access to static text content.
+
+### String Translation Methods
+
+#### `useGT()` and `getGT()` Pattern
+
+**Implementation**: Translate individual strings within data structures before mapping:
+
+```jsx
+import { useGT } from "gt-next/client";
+import { getGT } from "gt-next/server";
+
+const MyComponent = () => {
+  // Client-side: const t = useGT();
+  // Server-side: const t = await getGT();
+  const t = useGT(); // or await getGT()
+  
+  const someList = [
+    t('Hello Archie'),
+    t('Hello Ernest'),
+    t('Hello Brian'),
+  ];
+  return <>{someList.map((item) => item)}</>;
+};
+```
+
+#### `useDict()` and `getDict()` Pattern
+
+**Note**: Dictionary approach separates content from implementation context. Use sparingly - only when content reuse across components justifies the separation.
+
+**Dictionary structure**:
+```json
+{
+  "Greetings": {
+    "Archie": "Archie",
+    "Ernest": "Ernest", 
+    "Brian": "Brian"
+  }
+}
+```
+
+**Implementation**:
+```jsx
+import { useDict } from "gt-next/client";
+import { getDict } from "gt-next/server";
+
+const MyComponent = () => {
+  // Client-side: const t = useDict();
+  // Server-side: const t = await getDict();
+  const t = useDict(); // or await getDict()
+  
+  const someList = [
+    t('Greetings.Archie'),
+    t('Greetings.Ernest'),
+    t('Greetings.Brian'),
+  ];
+  return <>{someList.map((item) => item)}</>;
+};
+```
+
+## Complex Nested Object Translation
+
+### Challenge: Multi-level Data Structures
+
+**Scenario**: Nested objects with translatable content at multiple levels require systematic translation approach.
+
+**Non-internationalized example**:
+```jsx
+const MyComponent = () => {
+  const users = {
+    archie: {
+      name: 'Archie',
+      role: 'Developer',
+      skills: ['JavaScript', 'React', 'TypeScript'],
+    },
+    ernest: {
+      name: 'Ernest', 
+      role: 'Designer',
+      skills: ['UI/UX', 'Figma', 'Illustration'],
+    },
+    brian: {
+      name: 'Brian',
+      role: 'Product Manager', 
+      skills: ['Strategy', 'Planning', 'Communication'],
+    },
+  };
+
+  return (
+    <div>
+      {Object.entries(users).map(([key, user]) => (
+        <div key={key}>
+          <h2>{user.name}</h2>
+          <p>Role: {user.role}</p>
+          <ul>
+            {user.skills.map((skill, index) => (
+              <li key={index}>{skill}</li>
+            ))}
+          </ul>
+        </div>
+      ))}
+    </div>
+  );
+};
+```
+
+### Solution: Comprehensive Translation Strategy
+
+**Requirements**:
+- Translate role labels and skill names
+- Handle string interpolation for template text
+- Provide contextual information for ambiguous terms
+
+**Implementation**:
+```jsx
+import { useGT } from 'gt-next/client';
+
+const MyComponent = () => {
+  const t = useGT();
+  const users = {
+    archie: {
+      name: 'Archie',
+      role: t('Developer', { context: 'As in a software developer' }),
+      skills: [t('JavaScript'), t('React'), t('TypeScript')],
+    },
+    ernest: {
+      name: 'Ernest',
+      role: t('Designer', { context: 'As in a UI/UX designer' }),
+      skills: [t('UI/UX'), t('Figma'), t('Illustration')],
+    },
+    brian: {
+      name: 'Brian',
+      role: t('Product Manager'),
+      skills: [t('Strategy'), t('Planning'), t('Communication')],
+    },
+  };
+  
+  return (
+    <div>
+      {Object.entries(users).map(([key, user]) => (
+        <div key={key}>
+          <h2>{user.name}</h2>
+          <p>{t('Role: {role}', { variables: { role: user.role } })}</p>
+          <ul>
+            {user.skills.map((skill, index) => (
+              <li key={index}>{skill}</li>
+            ))}
+          </ul>
+        </div>
+      ))}
+    </div>
+  );
+};
+```
+
+**Key techniques**:
+1. **Context provision**: `{ context: 'As in a software developer' }` for disambiguation
+2. **Variable interpolation**: `t('Role: {role}', { variables: { role: user.role } })`
+3. **Systematic translation**: Apply `t()` to all user-facing strings within data structure

package/guides/next/advanced/interpolated-strings.md

@@ -0,0 +1,162 @@
+# String Interpolation Internationalization Patterns
+
+**Objective**: Transform template literal strings with dynamic variables into translatable strings using `useGT()`/`getGT()` and `useDict()`/`getDict()`.
+
+## Core Pattern: Variable Injection
+
+### `useGT()`/`getGT()` Method
+
+**Transform**: Template literals → Translatable strings with variable placeholders
+
+**Non-internationalized pattern**:
+
+```jsx
+const MyComponent = ({ name, count }) => {
+  return <div>{`Welcome ${name}, you have ${count} items`}</div>;
+};
+```
+
+**Internationalized implementation**:
+
+**Option A** the `<T>` component (preferred for JSX/HTML):
+
+```jsx
+import { T } from 'gt-next';
+
+const MyComponent = ({ name, count }) => {
+  return (
+    <div>
+      <T>
+        Welcome <Var>{name}</Var>, you have <Var>{count}</Var> items
+      </T>
+    </div>
+  );
+};
+```
+
+**Option B** the `useGT()` hook:
+
+```jsx
+'use client';
+import { useGT } from 'gt-next/client';
+
+const MyComponent = ({ name, count }) => {
+  const t = useGT(); // Client-side
+  // const t = await getGT(); // Server-side
+  return (
+    <div>
+      {t('Welcome {name}, you have {count} items', {
+        variables: { name, count },
+      })}
+    </div>
+  );
+};
+```
+
+**Key requirements**:
+
+- Replace `${variable}` syntax with `{variable}` placeholders
+- Pass dynamic values via `variables` object
+- Variable names must match placeholder names exactly
+
+### `useDict()`/`getDict()` Method
+
+**Option C**: Template literals → Dictionary keys with variable placeholders
+
+**Non-internationalized pattern**:
+
+```jsx
+const MyComponent = ({ username, role }) => {
+  return <div>{`User ${username} has the role of ${role}`}</div>;
+};
+```
+
+**Dictionary structure**:
+
+```json
+{
+  "Users": {
+    "Profile": "User {username} has the role of {role}"
+  }
+}
+```
+
+**Implementation**:
+
+```jsx
+'use client';
+import { useDict } from 'gt-next/client';
+const MyComponent = ({ username, role }) => {
+  const t = useDict(); // Client-side
+  // const t = await getDict(); // Server-side
+  return (
+    <div>
+      {t('Users.Profile', {
+        variables: { username, role },
+      })}
+    </div>
+  );
+};
+```
+
+## Advanced Patterns
+
+### Multi-Variable Interpolation
+
+**Scenario**: Multiple dynamic values in a single translatable string
+
+**Implementation**:
+
+```jsx
+'use client';
+import { useGT } from 'gt-next/client';
+const MyComponent = ({ firstName, lastName, age, city }) => {
+  const t = useGT(); // Client-side
+  // const t = await getGT(); // Server-side
+  return (
+    <div>
+      {t('{firstName} {lastName} is {age} years old and lives in {city}', {
+        variables: { firstName, lastName, age, city },
+      })}
+    </div>
+  );
+};
+```
+
+**Requirements**: All placeholder names must have corresponding entries in `variables` object.
+
+### Object Property Extraction
+
+**Scenario**: Extract values from nested objects for interpolation
+
+**Dictionary definition**:
+
+```json
+{
+  "Users": {
+    "Details": "{name} works as a {role} in the {department} department"
+  }
+}
+```
+
+**Implementation**:
+
+```jsx
+const MyComponent = ({ user }) => {
+  const t = useDict(); // Client-side
+  // const t = await getDict(); // Server-side
+  return (
+    <div>
+      {t('Users.Details', {
+        variables: {
+          name: user.name,
+          role: user.role,
+          department: user.department,
+        },
+      })}
+    </div>
+  );
+};
+```
+
+**Pattern**: Explicitly map object properties to named variables for clear placeholder relationships.

package/guides/next/advanced/migrating.md

@@ -0,0 +1,86 @@
+# Migration Patterns for Existing i18n Projects
+
+**Objective**: Transform existing i18n implementations to `gt-next` using systematic migration strategies.
+
+## Core Migration Principles
+
+### Library Replacement Requirements
+
+- Replace existing i18n library hooks/functions with `gt-next` equivalents
+- Transform string keys to inline content or maintain dictionary structure
+- Preserve existing translation content during transition
+
+## Prerequisites
+
+The project should be setup with `gt-next`. See the guide on setting up gt-next in a Next.js project.
+
+## Migration Strategy Implementation
+
+**Objective**: Full transformation from existing i18n library to `gt-next` with string key elimination.
+
+**Hook replacement pattern**:
+
+- Replace old i18n library hooks/functions with `gt-next` equivalents
+- Transform string keys → inline content
+
+**Implementation transformation**:
+
+**Legacy pattern**:
+
+```json
+{
+  "hello": {
+    "description": "Hello, world!"
+  }
+}
+```
+
+```tsx
+export default function MyComponent() {
+  const { t } = useTranslation();
+  return <div>{t('hello.description')}</div>;
+}
+```
+
+**Migrated implementations**:
+
+**Option A - Component-based** (preferred):
+
+```tsx
+export default function MyComponent() {
+  return (
+    <T>
+      <div>Hello, world!</div>
+    </T>
+  );
+}
+```
+
+**Option B - Hook-based**:
+
+```tsx
+'use client'; // Always add 'use client' when working with the useGT() hook
+import { useGT } from 'gt-next/client';
+export default function MyComponent() {
+  const t = useGT();
+  return <div>{t('Hello, world!')}</div>;
+}
+```
+
+**Requirements**: Systematic replacement of all legacy i18n library instances.
+
+## Migration Implementation Guidelines
+
+### Primary Pattern Preference
+
+**Rule**: Prioritize `useGT()` hook, `getGT()` function, and `<T>` component usage whenever possible.
+
+**Benefits**:
+
+- Enhanced content editability
+- Improved code readability
+- Contextual content management
+
+### Dictionary Hook Usage
+
+**Rule**: Only apply `useDict()` and `getDict()` during migration when necessary.