locadex 0.0.2-alpha.1 → 0.0.2-alpha.4

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.

package/guides/next/advanced/ternary-operators.md

@@ -0,0 +1,217 @@
+# Conditional Content Internationalization Patterns
+
+**Objective**: Transform ternary operators and conditional rendering into translatable patterns using `<T>`, `<Branch>`, `<Plural>`, `<Var>`, `useGT()`/`getGT()`, and `useDict()`/`getDict()`.
+
+## Core Constraint: Dynamic Content in `<T>` Components
+
+### `<Branch>` Component Pattern
+
+**Rules**:
+
+- `<T>` components cannot contain dynamic expressions. Use `<Branch>` for conditional JSX within `<T>`.
+- When working with `useGT()` always add a `"use client"` directive.
+
+**Non-internationalized conditional**:
+
+```jsx
+const MyComponent = ({ isLoggedIn }) => {
+  return (
+    <>
+      {isLoggedIn ? (
+        <div>Welcome back!</div>
+      ) : (
+        <div>Please log in to continue</div>
+      )}
+    </>
+  );
+};
+```
+
+**Invalid approach** - Dynamic ternary inside `<T>`:
+
+```jsx
+const MyComponent = ({ isLoggedIn }) => {
+  return (
+    <T>
+      {isLoggedIn ? (
+        <div>Welcome back!</div>
+      ) : (
+        <div>Please log in to continue</div>
+      )}
+    </T>
+  );
+};
+```
+
+**Correct implementation** - `<Branch>` component:
+
+```jsx
+const MyComponent = ({ isLoggedIn }) => {
+  return (
+    <T>
+      <Branch
+        branch={isLoggedIn.toString()}
+        true={<div>Welcome back!</div>}
+        false={<div>Please log in to continue</div>}
+      />
+    </T>
+  );
+};
+```
+
+**Requirements**:
+
+- Convert boolean to string: `isLoggedIn.toString()`
+- Define static JSX for `true` and `false` props
+- Wrap entire structure in `<T>` component
+
+**Recommendation**:
+
+- Whenever possible, use `<T>` component with Branches for internationalizing ternaries.
+- All ternaries used in JSX components can be converted to use Branches.
+- Use Variable components to wrap dynamic content.
+
+### String-Based Conditional Translation
+
+**Pattern**: Apply translation functions to each branch of ternary operators
+
+**Non-internationalized ternary**:
+
+```jsx
+const getCountMessage = ({ count }) => {
+  return count === 1 ? 'You have 1 item' : `You have ${count} items`;
+};
+```
+
+**Internationalized implementation**:
+
+```jsx
+'use client'; // TIP: always add the 'use client' directive when importing useGT()
+import { useGT } from 'gt-next/client';
+const getCountMessage = ({ count }) => {
+  const t = useGT();
+  return count === 1
+    ? t('You have 1 item')
+    : t('You have {count} items', { variables: { count } });
+};
+```
+
+**Key technique**: Apply `t()` function to each branch separately, using variable interpolation where needed.
+
+## Advanced Conditional Patterns
+
+### Multi-Level Nested Conditions
+
+**Pattern**: Chain ternary operators with translation applied to each outcome
+
+**Technique**:
+
+- For JSX: Use a `<Branch>` or `<Plural>` component.
+- For Strings: Each condition level receives separate translation call.
+
+### Numerical Condition Branching
+
+**Pattern**: Handle zero, singular, and plural cases with appropriate translations
+
+#### JSX Approach
+
+Original
+
+```jsx
+const getItemsFoundMessage = ({ items }) => {
+  return (
+    <>
+      {items.color === 'red' ? (
+        <>An amazing color was found</>
+      ) : items.shape === 'square' ? (
+        <>A disgusting color but an amazing shape was found</>
+      ) : (
+        <>A disgusting color and disgusting shape was found</>
+      )}
+    </>
+  );
+};
+```
+
+Internationalized
+
+```jsx
+import { T, Branch } from 'gt-next';
+const getItemsFoundMessage = ({ items }) => {
+  return (
+    <T>
+      <Branch branch={items.color} red={<>An amazing color was found</>}>
+        {/* Children are the catch all for the branch component */}
+        <Branch
+          branch={items.shape}
+          square={<>A disgusting color but an amazing shape was found</>}
+        >
+          A disgusting color and disgusting shape was found
+        </Branch>
+      </Branch>
+    </T>
+  );
+};
+```
+
+#### String Approach
+
+Original
+
+```jsx
+const getItemsFoundMessage = ({ items }) => {
+  return items.color === 'red'
+    ? 'An amazing color was found'
+    : items.shape === 'square'
+      ? 'A disgusting color but an amazing shape was found'
+      : 'A disgusting color and disgusting shape was found';
+};
+```
+
+Internationalized
+
+```jsx
+'use client';
+import { useGT } from 'gt-next/client';
+
+const getItemsFoundMessage = ({ items }) => {
+  const t = useGT();
+  return items.color === 'red'
+    ? t('An amazing color was found')
+    : items.shape === 'square'
+      ? t('A disgusting color but an amazing shape was found')
+      : t('A disgusting color and disgusting shape was found');
+};
+```
+
+**Key requirements**:
+
+- Handle zero state explicitly
+- Use singular form for count === 1
+- Apply variable interpolation for plural cases
+
+### Complex JSX Conditional Rendering
+
+**Pattern**: Wrap each conditional JSX branch in separate `<T>` components
+
+```jsx
+const MyComponent = ({ error, loading }) => {
+  return (
+    <div>
+      {loading ? (
+        <T>
+          <div>Loading...</div>
+        </T>
+      ) : error ? (
+        <T>
+          <div>An error occurred</div>
+        </T>
+      ) : (
+        <T>
+          <div>Content loaded successfully</div>
+        </T>
+      )}
+    </div>
+  );
+};
+```