locadex 0.1.2 → 0.1.4

package/guides/next/advanced/{complicated-mapping-expressions.md → mapping-expressions.md}

@@ -1,14 +1,13 @@
-# Internationalization Patterns for Dynamic Content
+# Guide: Internationalization Patterns for Mapped Content
 
-**Objective**: Implement internationalization for mapping expressions using `<T>`, `useGT()`/`getGT()`, and `useDict()`/`getDict()`.
+**Objective**: Implement internationalization for mapping expressions using `<T>`, `useGT()`, and `useTranslations()`.
 
-## Core Principles
-
-### `<T>` Component Usage
+## `<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>
@@ -17,24 +16,32 @@
 ```
 
 **Invalid pattern** - `<T>` cannot process dynamic mapping:
+
 ```jsx
 const MyComponent = () => {
   const someList = [
-    <div>Hello Archie</div>,
-    <div>Hello Ernest</div>,
-    <div>Hello Brian</div>,
+    <div>Hello, World!</div>,
+    <div>Welcome to the website!</div>,
+    <div>Goodbye!</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>,
+    <T>
+      <div>Hello, World!</div>
+    </T>,
+    <T>
+      <div>Welcome to the website!</div>
+    </T>,
+    <T>
+      <div>Goodbye!</div>
+    </T>,
   ];
   return <>{someList.map((item) => item)}</>;
 };
@@ -42,71 +49,71 @@ const MyComponent = () => {
 
 **Key requirement**: Each `<T>` component must have direct access to static text content.
 
-### String Translation Methods
-
-#### `useGT()` and `getGT()` Pattern
+## `useGT()` Pattern
 
 **Implementation**: Translate individual strings within data structures before mapping:
 
 ```jsx
-import { useGT } from "gt-next/client";
-import { getGT } from "gt-next/server";
-
+import { useGT } from 'gt-next';
 const MyComponent = () => {
-  // Client-side: const t = useGT();
-  // Server-side: const t = await getGT();
-  const t = useGT(); // or await getGT()
-  
+  const t = useGT();
   const someList = [
-    t('Hello Archie'),
-    t('Hello Ernest'),
-    t('Hello Brian'),
+    t('Hello, World!'),
+    t('Welcome to the website!'),
+    t('Goodbye!'),
   ];
   return <>{someList.map((item) => item)}</>;
 };
 ```
 
-#### `useDict()` and `getDict()` Pattern
+**Note:** When a function or component is marked as `async`, you should use the `getGT()` hook to get the translation callback function. `getGT()` must be awaited. Other than this, the usage of `getGT()` and `useGT()` is the same.
 
-**Note**: Dictionary approach separates content from implementation context. Use sparingly - only when content reuse across components justifies the separation.
+**Key requirement**: Each string must be static.
+
+## `useTranslations()` Pattern
+
+### Notes
+
+- This is the classic dictionary approach. It separates content from implementation context.
+- **Use sparingly** - only use this approach when content reuse across components justifies the separation.
+- Additionally, this approach may be used to internationalize complex strings that are both logically functional and are also displayed in UI.
 
 **Dictionary structure**:
-```json
+
+```json title="dictionary.json"
 {
-  "Greetings": {
-    "Archie": "Archie",
-    "Ernest": "Ernest", 
-    "Brian": "Brian"
+  "greetings": {
+    "world": "Hello, World!",
+    "welcome": "Welcome to the website!",
+    "goodbye": "Goodbye!"
   }
 }
 ```
 
 **Implementation**:
-```jsx
-import { useDict } from "gt-next/client";
-import { getDict } from "gt-next/server";
 
+```jsx
+import { useTranslations } from 'gt-next';
 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)}</>;
+  const t = useTranslations();
+  const someListOfIds = ['world', 'welcome', 'goodbye'];
+  return <>{someListOfIds.map((id) => t(`greetings.${id}`))}</>;
 };
 ```
 
+### Notes
+
+- Strings, when used with `useTranslations()`, are always accessed dynamically as dictionary keys.
+- When a function or component is marked as `async`, you should use the `getTranslations()` hook to get the translation callback function. `getTranslations()` must be awaited. Other than this, the usage of `getTranslations()` and `useTranslations()` is the same.
+
 ## Complex Nested Object Translation
 
 ### Challenge: Multi-level Data Structures
 
-**Scenario**: Nested objects with translatable content at multiple levels require systematic translation approach.
+**Scenario**: This is an example scenario where nested objects with translatable content at multiple levels require a systematic translation approach.
 
 **Non-internationalized example**:
+
 ```jsx
 const MyComponent = () => {
   const users = {
@@ -116,17 +123,16 @@ const MyComponent = () => {
       skills: ['JavaScript', 'React', 'TypeScript'],
     },
     ernest: {
-      name: 'Ernest', 
+      name: 'Ernest',
       role: 'Designer',
       skills: ['UI/UX', 'Figma', 'Illustration'],
     },
     brian: {
       name: 'Brian',
-      role: 'Product Manager', 
+      role: 'Product Manager',
       skills: ['Strategy', 'Planning', 'Communication'],
     },
   };
-
   return (
     <div>
       {Object.entries(users).map(([key, user]) => (
@@ -148,14 +154,15 @@ const MyComponent = () => {
 ### 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';
 
+```jsx
+import { useGT } from 'gt-next';
 const MyComponent = () => {
   const t = useGT();
   const users = {
@@ -175,7 +182,6 @@ const MyComponent = () => {
       skills: [t('Strategy'), t('Planning'), t('Communication')],
     },
   };
-  
   return (
     <div>
       {Object.entries(users).map(([key, user]) => (
@@ -195,6 +201,7 @@ const MyComponent = () => {
 ```
 
 **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/basic/branches.md

@@ -1,4 +1,4 @@
-## Branch Components Overview
+# Guide: Branch Components Overview
 
 Branch components dynamically render different content based on conditional values or numeric quantities. They handle locale-aware conditional logic and pluralization rules.
 
@@ -10,14 +10,8 @@ import { Branch, Plural } from 'gt-next';
 
 **Key Behavior:**
 
-- `<Branch>`: Renders content based on conditional branch values
-- `<Plural>`: Handles pluralization with locale-specific rules
-
-**Processing Model:**
-
-- JSX content → General Translation API for translation
-- Branch logic → Local conditional rendering
-- `<Plural>` → Uses Unicode CLDR pluralization rules
+- `<Branch>`: Renders content based on conditional branch values.
+- `<Plural>`: Handles pluralization with locale-specific rules. Uses Unicode CLDR pluralization rules.
 
 **Important:** When used within `<T>` components, branch content is translated. When used standalone, content renders without translation.
 
@@ -43,7 +37,7 @@ Branch components use condition-based prop patterns:
 
 ### Integration with `<T>` Components
 
-Branch components require translation context for localized content. Use within `<T>` components for automatic translation:
+Branch components require translation context for localized content. Use within `<T>` components to automatically translate content.
 
 ```tsx
 import { T, Branch } from 'gt-next';
@@ -51,10 +45,10 @@ import { T, Branch } from 'gt-next';
 <T>
   <Branch
     branch={status}
-    active={<p>User is active</p>}
-    inactive={<p>User is inactive</p>}
+    active={<p>User is active</p>} // This content is translated by the <T> component
+    inactive={<p>User is inactive</p>} // This content is translated by the <T> component
   >
-    Status unknown
+    Status unknown {/* This content is translated by the <T> component */}
   </Branch>
 </T>;
 ```
@@ -70,19 +64,24 @@ The `<T>` component provides translation context and localizes branch content.
 ```tsx
 import { Plural } from 'gt-next';
 
-<Plural
-  n={count}
-  zero={<>No items</>}
-  one={<>One item</>}
-  two={<>Two items</>}
-  few={<>Few items</>}
-  many={<>Many items</>}
-  other={<>Other items</>}
-  dual={<>Dual items</>}
-  // OR simplified
-  singular={<>One item</>}
-  plural={<>Multiple items</>}
-/>;
+// All content inside the <Plural> component is translated by the <T> component
+<T>
+  He has
+  <Plural
+    n={count}
+    zero={<>No items</>}
+    one={<>One item</>}
+    two={<>Two items</>}
+    few={<>Few items</>}
+    many={<>Many items</>}
+    other={<>Other items</>}
+    dual={<>Dual items</>}
+    // OR simplified
+    singular={<>One item</>}
+    plural={<>Multiple items</>}
+  />
+  .
+</T>;
 ```
 
 **Available Forms:** zero, one, two, few, many, other, dual (locale-dependent), plus simplified singular/plural.
@@ -96,29 +95,34 @@ import { Plural } from 'gt-next';
 **Replacing Ternary Operators:** Convert inline conditional logic to declarative branch syntax.
 
 ```tsx
-// Instead of: {isActive ? <p>Active</p> : <p>Inactive</p>}
+// Original:
+{
+  isActive ? <p>Active</p> : <p>Inactive</p>;
+}
+
+// After:
 <Branch branch={isActive} true={<p>Active</p>} false={<p>Inactive</p>}>
   Status unknown
-</Branch>
+</Branch>;
 ```
 
 **Important**: the `branch` prop only accepts string values.
 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.
+**Replacing Conditional Rendering:** Convert `?` operator patterns to branch syntax.
+This should only be done if the content is being used in a `<T>` component.
 
 **Invalid Syntax**:
 
 ```tsx
-<T>{isActive && <p>Active</p>}</T>
+<T>{isActive ? <p>Active</p> : <p>Inactive</p>}</T>
 ```
 
 **Valid Syntax**:
 
 ```tsx
 <T>
-  <Branch branch={isActive} true={<p>Active</p>}>
+  <Branch branch={isActive} true={<p>Active</p>} false={<p>Inactive</p>}>
     <></>
   </Branch>
 </T>
@@ -128,26 +132,35 @@ This is only applicable if the content is being used in a `<T>` component.
 
 ```tsx
 {
-  isActive && (
+  isActive ? (
     <T>
       <p>Active</p>
     </T>
+  ) : (
+    <T>
+      <p>Inactive</p>
+    </T>
   );
 }
 ```
 
-In this case, the `<T>` component is not wrapping the conditional, so the branch component is not needed.
+In the previous example, 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.
 
 ```tsx
-// Instead of: {count === 1 ? <p>1 item</p> : <p>{count} items</p>}
-<Plural n={count} one={<p>1 item</p>} other={<p>{count} items</p>} />
+// Original:
+{
+  count === 1 ? <p>1 item</p> : <p>{count} items</p>;
+}
+
+// After:
+<Plural n={count} one={<p>1 item</p>} other={<p>{count} items</p>} />;
 ```
 
-Note: `n` only accepts numbers.
+**Note:** `n` only accepts numbers.
 
 **With Variable Integration:** Combine with `<Num>` for formatted numbers.
 
@@ -211,14 +224,16 @@ const status: string = 'active';
 **Subscription Tiers:** Standalone usage without translation.
 
 ```tsx
-<Branch
-  branch={plan}
-  free={<p>Free plan - upgrade to unlock features</p>}
-  premium={<p>Premium plan - full access</p>}
-  enterprise={<p>Enterprise plan - contact support</p>}
->
-  No subscription detected
-</Branch>
+<T>
+  <Branch
+    branch={plan}
+    free={<p>Free plan - upgrade to unlock features</p>}
+    premium={<p>Premium plan - full access</p>}
+    enterprise={<p>Enterprise plan - contact support</p>}
+  >
+    No subscription detected
+  </Branch>
+</T>
 ```
 
 ### `<Plural>` - Quantity-Based Content
@@ -308,3 +323,5 @@ import { T, Plural, Num } from 'gt-next';
 - [`<Branch>`](/docs/next/api/components/branch) - Conditional rendering options
 - [`<Plural>`](/docs/next/api/components/plural) - Pluralization configuration
 - [Variable Components](/docs/next/guides/variables) - Integration patterns
+
+For more information on Variable Components, see the `mcp__locadex__next_basic_variables` guide.

package/guides/next/basic/jsx.md

@@ -1,7 +1,12 @@
-# JSX Translation with `<T>` Component
+# Guide: JSX Translation with `<T>` Component
 
 Use the `<T>` component to internationalize HTML and JSX content.
 
+**Key Notes**:
+
+- `<T>` components can contain any valid JSX/HTML content, including other components, strings, and other JSX/HTML content.
+- `<T>` components can contain dynamic content, but it must be wrapped in Variable Components or Branching Components.
+
 **Import:** The `<T>` component is exported from `gt-next`.
 
 ```tsx
@@ -30,22 +35,20 @@ function Greeting() {
 }
 ```
 
-# Context Prop
+## Context Prop
 
 Add `context` prop when content meaning is ambiguous:
 
 ```jsx
-<T context='toast, as in a pop-up notification'>
-  Click on the toast to dismiss it.
-</T>
+<T context='Crop, as in cropping an image'>Crop</T>
 ```
 
 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.
+- Provide context for words with multiple meanings (e.g., "crop" = cropping an image vs the food crop).
+- Provide context when the additional context can provide more information to the translator about the surrounding content, that is not obvious from the content itself.
 
-# Usage Rules
+## Usage Rules
 
 **USE `<T>` for:**
 
@@ -54,9 +57,11 @@ RULES:
 
 **DO NOT USE `<T>` for:** Raw dynamic content (unwrapped variables, expressions, conditionals)
 
+### Notes on Variable Components
+
 Variable components are safe for `<T>` because content is wrapped and sanitized. Variable component content is never translated directly by `<T>`.
 
-## Invalid Usage Examples (Raw Dynamic Content)
+### Invalid Usage Examples (Raw Dynamic Content)
 
 ```jsx
 <T>
@@ -82,35 +87,33 @@ Variable components are safe for `<T>` because content is wrapped and sanitized.
 </T>
 ```
 
-Solution: Wrap dynamic content in variable components or branching components, then use with `<T>`.
+**Solution: Wrap dynamic content in variable components or branching components, then use with `<T>`.**
 
-# Valid Usage Examples
+## Valid Usage Examples
 
-## HTML Content
+### HTML and JSX Content
 
 ```jsx
 // Before
 <p>Hello, world!</p>
+<Button>Click me!</Button>
 
 // After
 <T>
   <p>Hello, world!</p>
 </T>
-```
-
-## Simple JSX Content
-
-```jsx
-// Before
-<Button>Click me!</Button>
+<T>
+  <Button>Click me!</Button>
+</T>
 
-// After
+// Or, you can wrap both components with `<T>`
 <T>
+  <p>Hello, world!</p>
   <Button>Click me!</Button>
 </T>
 ```
 
-## Complex JSX Content
+### Complex JSX Content
 
 ```jsx
 // Before
@@ -148,11 +151,11 @@ 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
+## Common Pitfalls and Solutions
 
-## Direct Descendants Only
+### Direct Descendants Only
 
 Rule: `<T>` only translates content directly between its tags. Content inside nested components is not translated.
 
@@ -174,7 +177,7 @@ export default function DisplayGreetings() {
 
 Only content literally between `<T>` tags is translated. The `<h1>` is translated, but `<UntranslatedContent>` is not.
 
-## Solution
+**Solution:**
 
 ```jsx
 // CORRECT - Each component wraps its own content
@@ -200,7 +203,7 @@ export default function DisplayGreetings() {
 }
 ```
 
-## Nested `<T>` Components
+### Nested `<T>` Components
 
 Rule: Never nest `<T>` components. This causes unexpected behavior and performance issues.
 
@@ -222,9 +225,9 @@ export default function NestedTranslation() {
 
 Solution: Remove the outer `<T>` component.
 
-## Raw Dynamic Content Error
+### Raw Dynamic Content Error
 
-CLI will error on raw dynamic content in `<T>`:
+Raw dynamic content in `<T>` will cause an error.
 
 ```jsx
 // WILL ERROR - Raw dynamic content
@@ -234,12 +237,12 @@ const username = 'John Doe';
 </T>;
 ```
 
-Solutions:
+**Solutions:**
 
 1. Wrap dynamic content in Variable Components or Branching Components, then use with `<T>`
-2. Use `<Tx>` component for on-demand translation
+2. Use `<Tx>` component for on-demand translation (**use only when necessary, and on server components**)
 
-## Implementing Variable contents incorrectly
+### Implementing Variable contents incorrectly
 
 The following syntax is wrong and was likely confused with the `useGT()` hook.
 
@@ -252,14 +255,13 @@ const username = 'John Doe';
 The correct implementation is as follows:
 
 ```jsx
-// WILL ERROR - Improper syntax
 const username = 'John Doe';
 <T>
   Hello, <Var>{username}</Var>
 </T>;
 ```
 
-# Summary
+## Summary
 
 - Use `<T>` to internationalize static JSX content
 - Use `<T>` with dynamic content only when wrapped in Variable/Branching Components