locadex 0.1.17 → 1.0.0

package/guides/next/basic/branches.md

@@ -1,327 +0,0 @@
-# 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.
-
-**Import:** Branch components are exported from `gt-next`.
-
-```tsx
-import { Branch, Plural } from 'gt-next';
-```
-
-**Key Behavior:**
-
-- `<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.
-
-**Integration with Variables:** Branch components are often combined with variable components like `<Num>` for locale-aware dynamic content.
-
----
-
-## Usage Patterns
-
-### Basic Syntax
-
-Branch components use condition-based prop patterns:
-
-```tsx
-<Branch branch={condition} key1={content1} key2={content2}>
-  Fallback content
-</Branch>
-
-<Plural n={number} one={singular} other={plural}>
-  Fallback content
-</Plural>
-```
-
-### Integration with `<T>` Components
-
-Branch components require translation context for localized content. Use within `<T>` components to automatically translate content.
-
-```tsx
-import { T, Branch } from 'gt-next';
-
-<T>
-  <Branch
-    branch={status}
-    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 {/* This content is translated by the <T> component */}
-  </Branch>
-</T>;
-```
-
-The `<T>` component provides translation context and localizes branch content.
-
-### 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';
-
-// 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.
-
----
-
-## Implementation Examples
-
-### `<Branch>` - Conditional Logic Replacement
-
-**Replacing Ternary Operators:** Convert inline conditional logic to declarative branch syntax.
-
-```tsx
-// Original:
-{
-  isActive ? <p>Active</p> : <p>Inactive</p>;
-}
-
-// After:
-<Branch branch={isActive} true={<p>Active</p>} false={<p>Inactive</p>}>
-  Status unknown
-</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 should only be done if the content is being used in a `<T>` component.
-
-**Invalid Syntax**:
-
-```tsx
-<T>{isActive ? <p>Active</p> : <p>Inactive</p>}</T>
-```
-
-**Valid Syntax**:
-
-```tsx
-<T>
-  <Branch branch={isActive} true={<p>Active</p>} false={<p>Inactive</p>}>
-    <></>
-  </Branch>
-</T>
-```
-
-**Alternative Valid Syntax**:
-
-```tsx
-{
-  isActive ? (
-    <T>
-      <p>Active</p>
-    </T>
-  ) : (
-    <T>
-      <p>Inactive</p>
-    </T>
-  );
-}
-```
-
-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
-// 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.
-
-**With Variable Integration:** Combine with `<Num>` for formatted numbers.
-
-```tsx
-<T>
-  <Plural
-    n={count}
-    one={
-      <>
-        You have <Num>{count}</Num> unread message.
-      </>
-    }
-    other={
-      <>
-        You have <Num>{count}</Num> unread messages.
-      </>
-    }
-  />
-</T>
-```
-
-**Translation Context:** Use within `<T>` for translated content, standalone for raw rendering.
-
----
-
-## Complete Implementation Examples
-
-### `<Branch>` - Multi-State Logic
-
-**Status Management:** Handle multiple conditional states with fallback.
-
-```tsx
-import { T, Branch, Var } from 'gt-next';
-const status: string = 'active';
-<T>
-  <Branch
-    branch={status}
-    active={
-      <p>
-        User <Var>{name}</Var> is active.
-      </p>
-    }
-    inactive={
-      <p>
-        User <Var>{name}</Var> is inactive.
-      </p>
-    }
-  >
-    Status unknown.
-  </Branch>
-</T>;
-```
-
-**Behavior:**
-
-- `status === "active"` → renders active content
-- `status === "inactive"` → renders inactive content
-- Other values → renders fallback content
-- Content within `<T>` is automatically translated
-
-**Subscription Tiers:** Standalone usage without translation.
-
-```tsx
-<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
-
-**Message Count:** Number-dependent content with locale formatting.
-
-```tsx
-import { T, Plural, Num } from 'gt-next';
-
-<T>
-  <Plural
-    n={unreadCount}
-    one={
-      <>
-        You have <Num>{unreadCount}</Num> unread message.
-      </>
-    }
-    other={
-      <>
-        You have <Num>{unreadCount}</Num> unread messages.
-      </>
-    }
-  />
-</T>;
-```
-
-**Behavior:**
-
-- `n === 1` (locale-specific) → renders singular form
-- Other values → renders plural form
-- `<Num>` provides locale-aware number formatting
-
----
-
-## Common Implementation Issues
-
-### Missing Branch Values
-
-**Critical:** Unmatched branch values fall back to children content. Ensure branch prop values match defined keys.
-
-```tsx
-<Branch
-  branch={status} // If status is "pending" but no pending={} prop exists
-  active={<p>Active</p>}
-  inactive={<p>Inactive</p>}
->
-  Status unknown. // ← This renders for unmatched values
-</Branch>
-```
-
-**Rule:** Always provide fallback children for robust error handling.
-
-### Missing Plural Forms
-
-**Critical:** Provide required plural forms for your default locale to ensure fallback content availability.
-
-**Minimum English Requirements:**
-
-```tsx
-<Plural
-  n={count}
-  one={<>One message</>}    // Required for English
-  other={<>Multiple messages</>}  // Required fallback
-/>
-
-// OR simplified form
-<Plural
-  n={count}
-  singular={<>One message</>}
-  plural={<>Multiple messages</>}
-/>
-```
-
-**Optimization:** Use `one`/`other` for CLDR compliance or `singular`/`plural` for simplicity.
-
----
-
-## Key Principles
-
-- **Conditional Logic:** Branch components replace ternary operators and conditional rendering with declarative syntax
-- **Locale Awareness:** `<Plural>` automatically handles pluralization rules across different languages
-- **Fallback Handling:** Always provide children content for unmatched conditions
-- **Translation Integration:** Use within `<T>` for translated content, standalone for raw rendering
-
-## API References
-
-- [`<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,270 +0,0 @@
-# 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
-import { T } from 'gt-next';
-```
-
-Before:
-
-```jsx
-function Greeting() {
-  return <p>Hello, world!</p>;
-}
-```
-
-After:
-
-```jsx
-import { T } from 'gt-next';
-
-function Greeting() {
-  return (
-    <T>
-      <p>Hello, world!</p>
-    </T>
-  );
-}
-```
-
-## Context Prop
-
-Add `context` prop when content meaning is ambiguous:
-
-```jsx
-<T context='Crop, as in cropping an image'>Crop</T>
-```
-
-RULES:
-
-- 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
-
-**USE `<T>` for:**
-
-- Static HTML or JSX content
-- Dynamic content wrapped in Variable Components or Branching Components
-
-**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)
-
-```jsx
-<T>
-  <p>Your username is {username}</p>
-</T>
-```
-
-```jsx
-<T>
-  <p>Current date: {new Date().toLocaleDateString()}</p>
-</T>
-```
-
-```jsx
-<T>
-  <p>Logical Expressions: {username === 'admin' ? 'Yes' : 'No'}</p>
-</T>
-```
-
-```jsx
-<T>
-  <p>Conditional Rendering: {isAdmin ? 'Yes' : 'No'}</p>
-</T>
-```
-
-**Solution: Wrap dynamic content in variable components or branching components, then use with `<T>`.**
-
-## Valid Usage Examples
-
-### HTML and JSX Content
-
-```jsx
-// Before
-<p>Hello, world!</p>
-<Button>Click me!</Button>
-
-// After
-<T>
-  <p>Hello, world!</p>
-</T>
-<T>
-  <Button>Click me!</Button>
-</T>
-
-// Or, you can wrap both components with `<T>`
-<T>
-  <p>Hello, world!</p>
-  <Button>Click me!</Button>
-</T>
-```
-
-### Complex JSX Content
-
-```jsx
-// Before
-<Tooltip>
-  <TooltipTrigger>
-    <div className='flex items-center gap-2 rounded-full bg-destructive px-3 py-1.5 text-sm text-destructive-foreground'>
-      <AlertCircle className='h-4 w-4' />
-      <span>Free Usage</span>
-    </div>
-  </TooltipTrigger>
-  <TooltipContent>
-    <p>
-      You are nearing your free monthly limit. Please upgrade your plan to avoid
-      any disruptions to your service.
-    </p>
-  </TooltipContent>
-</Tooltip>
-
-// After
-<T>
-  <Tooltip>
-    <TooltipTrigger>
-      <div className='flex items-center gap-2 rounded-full bg-destructive px-3 py-1.5 text-sm text-destructive-foreground'>
-        <AlertCircle className='h-4 w-4' />
-        <span>Free Usage</span>
-      </div>
-    </TooltipTrigger>
-    <TooltipContent>
-      <p>
-        You are nearing your free monthly limit. Please upgrade your plan to
-        avoid any disruptions to your service.
-      </p>
-    </TooltipContent>
-  </Tooltip>
-</T>
-```
-
-**NOTE: `<T>` handles any nested content within the same component.**
-
-## Common Pitfalls and Solutions
-
-### Direct Descendants Only
-
-Rule: `<T>` only translates content directly between its tags. Content inside nested components is not translated.
-
-```jsx
-// INCORRECT - UntranslatedContent not translated
-function UntranslatedContent() {
-  return <p>This content is not translated</p>;
-}
-
-export default function DisplayGreetings() {
-  return (
-    <T>
-      <h1>Hello, this text will be translated</h1>
-      <UntranslatedContent />
-    </T>
-  );
-}
-```
-
-Only content literally between `<T>` tags is translated. The `<h1>` is translated, but `<UntranslatedContent>` is not.
-
-**Solution:**
-
-```jsx
-// CORRECT - Each component wraps its own content
-function TranslatedContent() {
-  return (
-    <T>
-      <p>
-        This content <b>IS</b> translated
-      </p>
-    </T>
-  );
-}
-
-export default function DisplayGreetings() {
-  return (
-    <>
-      <T>
-        <h1>Hello, this text will be translated</h1>
-      </T>
-      <TranslatedContent />
-    </>
-  );
-}
-```
-
-### Nested `<T>` Components
-
-Rule: Never nest `<T>` components. This causes unexpected behavior and performance issues.
-
-```jsx
-// INCORRECT - Nested T components
-function SomeComponent() {
-  return <T>Hello, friend!</T>;
-}
-
-export default function NestedTranslation() {
-  return (
-    <T>
-      <T>Hello, world!</T> {/* Don't nest */}
-      <SomeComponent /> {/* This also nests */}
-    </T>
-  );
-}
-```
-
-Solution: Remove the outer `<T>` component.
-
-### Raw Dynamic Content Error
-
-Raw dynamic content in `<T>` will cause an error.
-
-```jsx
-// WILL ERROR - Raw dynamic content
-const username = 'John Doe';
-<T>
-  <p>Your username is {username}</p>
-</T>;
-```
-
-**Solutions:**
-
-1. Wrap dynamic content in Variable Components or Branching Components, then use with `<T>`
-2. Use `<Tx>` component for on-demand translation (**use only when necessary, and on server components**)
-
-### Implementing Variable contents incorrectly
-
-The following syntax is wrong and was likely confused with the `useGT()` hook.
-
-```jsx
-// WILL ERROR - Improper syntax
-const username = 'John Doe';
-<T variables={{ username }}>Hello, {username}</T>;
-```
-
-The correct implementation is as follows:
-
-```jsx
-const username = 'John Doe';
-<T>
-  Hello, <Var>{username}</Var>
-</T>;
-```
-
-## Summary
-
-- Use `<T>` to internationalize static JSX content
-- Use `<T>` with dynamic content only when wrapped in Variable/Branching Components
-- Never use `<T>` for raw dynamic content (unwrapped variables, expressions, conditionals)
-- Never nest `<T>` components
-- Only content directly between `<T>` tags is translated