locadex 0.0.1 → 0.0.2-alpha.3

package/guides/next/basic/jsx.md

@@ -0,0 +1,259 @@
+# JSX Translation with `<T>` Component
+
+Use the `<T>` component to internationalize HTML and JSX content.
+
+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='toast, as in a pop-up notification'>
+  Click on the toast to dismiss it.
+</T>
+```
+
+Rule: Provide context for words with multiple meanings (e.g., "toast" = bread vs notification).
+
+# 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)
+
+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 Content
+
+```jsx
+// Before
+<p>Hello, world!</p>
+
+// After
+<T>
+  <p>Hello, world!</p>
+</T>
+```
+
+## Simple JSX Content
+
+```jsx
+// Before
+<Button>Click me!</Button>
+
+// After
+<T>
+  <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
+
+## 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
+
+CLI will error on raw dynamic content in `<T>`:
+
+```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
+
+## 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
+// WILL ERROR - Improper syntax
+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

package/guides/next/basic/locale-selector.md

@@ -0,0 +1,5 @@
+## Locale Selection
+
+- Add [`<LocaleSelector>`](/docs/next/api/components/localeSelector) component for language switching
+- The `<LocaleSelector>` component is a dropdown that allows the user to select the language of the application.
+- It is a client-side component, place it in the header of the application.

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

@@ -0,0 +1,164 @@
+# Server-Side Component Internationalization
+
+## 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)
+
+**Importing:** The `getGT()` and `getDict()` functions are exported from `gt-next/server`.
+
+```tsx
+import { getGT } from 'gt-next/server';
+```
+
+The `<T>` component is exported from `gt-next`.
+
+```tsx
+import { T } from 'gt-next';
+```
+
+## Critical Rule
+
+NEVER add React directives ("use client", "use server", etc.) when internationalizing components.
+
+## getGT() Function
+
+**Purpose**: Server-side string translation (preferred method)
+**Scope**: Server components only
+**Async requirement**: Must be awaited
+
+### Basic Pattern
+
+**Before internationalization:**
+
+```jsx
+export default function Example() {
+  const greeting = 'Hello, World!';
+  return <>{greeting}</>;
+}
+```
+
+**After internationalization:**
+
+```jsx
+import { getGT } from 'gt-next/server';
+export default async function Example() {
+  const t = await getGT();
+  const greeting = t('Hello, World!');
+  return <>{greeting}</>;
+}
+```
+
+### Reusable Content Pattern
+
+**Requirement**: When content is shared across multiple files or locations, create async functions to avoid code duplication.
+
+**Before internationalization:**
+
+```jsx
+// Example 1
+export const content = 'hi';
+
+// Example 2
+export const nestedContent = {
+  name: 'Brian',
+  title: 'Engineer',
+};
+```
+
+**After internationalization:**
+
+```jsx
+import { getGT } from 'gt-next/server';
+
+// Example 1
+export const useContent = async () => {
+  const t = await getGT();
+  return t('hi');
+};
+
+// Example 2
+export const useNestedContent = async () => {
+  const t = await getGT();
+  return {
+    name: 'Brian',
+    title: t('Engineer'),
+  };
+};
+```
+
+**Key principle**: Create async functions to provide access to the `getGT()` function for reusable content.
+**Reference**: See guides about variables outside of functions for additional examples.
+
+### Context Parameter
+
+**Purpose**: Provide context when content meaning is ambiguous
+**Syntax**: `t('string', { context: 'explanation' })`. Does not work with dictionary keys.
+
+**Example with ambiguous word:**
+
+```jsx
+import { getGT } from 'gt-next/server';
+export default async function NotificationComponent() {
+  const t = await getGT();
+  return t('Click on the toast to dismiss it.', {
+    context: 'toast, as in a pop-up notification',
+  });
+}
+```
+
+**Rule**: Always provide context for words with multiple meanings (e.g., "toast" = bread vs notification).
+
+## getDict() Function
+
+**Purpose**: Centralized data management via dictionary files
+**Priority**: Use `getGT()` when possible; `getDict()` only when centralization is required
+**Mechanism**: Accesses `dictionary.json` file with key-value mappings (supports nested keys)
+
+### Dictionary Pattern
+
+**Step 1**: Move string values to `dictionary.json`:
+
+```json
+{
+  "user": {
+    "profile": {
+      "name": "User Name",
+      "title": "Job Title"
+    }
+  }
+}
+```
+
+**Step 2**: Access via key in server component:
+
+```jsx
+import { getDict } from 'gt-next/server';
+export default async function MyComponent() {
+  const t = await getDict();
+  return t('user.profile.name');
+}
+```
+
+### Adding Context to Dictionary Keys
+
+**Purpose**: Provide context when dictionary entry meaning is ambiguous
+
+**Example with ambiguous key:**
+
+```json
+{
+  "button": {
+    "name": "Primary Button",
+    "description": [
+      "Click on the toast to dismiss it.",
+      { "context": "toast, as in a pop-up notification" }
+    ]
+  }
+}
+```
+
+**Rule**: Always provide context for dictionary entries with multiple meanings (e.g., "toast" = bread vs notification).

package/guides/next/basic/setup.md

@@ -0,0 +1,139 @@
+# Next.js App Router with gt-next Setup Guide
+
+## Required libraries
+
+Install the `gt-next` and `gtx-cli` libraries using the project's package manager:
+
+```bash
+npm i gt-next
+npm i --save-dev gtx-cli
+```
+
+## Required Configuration: `withGTConfig`
+
+**Purpose**: Initialize the gt-next SDK in Next.js applications.
+
+**Implementation**: Configure `withGTConfig` in your `next.config.[js|ts]` file as the default export wrapper:
+
+```tsx title="next.config.ts"
+import { withGTConfig } from 'gt-next/config';
+
+const nextConfig = {
+  // Your next.config.ts options
+};
+
+export default withGTConfig(nextConfig, {
+  // Additional GT configuration options
+});
+```
+
+**Reference**: [withGTConfig API Reference](/docs/next/api/config/withGTConfig)
+
+## Required Provider: `GTProvider`
+
+**Purpose**: Provides internationalization context to client-side components in Next.js applications.
+
+**Functionality**: Works in conjunction with `withGTConfig` to provide:
+
+- User locale management
+- Locale-specific translations
+- Context for `useGT` hook
+- Context for `useDict` hook
+
+**Setup Steps**:
+
+1. **Root Layout Integration**: Add `GTProvider` to your application's root layout, positioned as high as possible in the component tree, within `<html>` and `<body>` elements:
+
+```tsx copy title="src/layout.tsx"
+import { GTProvider } from 'gt-next';
+import { getLocale } from 'gt-next/server';
+
+export default async function RootLayout({ children }) {
+  return (
+    <html lang={await getLocale()}>
+      <body>
+        <GTProvider>{children}</GTProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+Make sure to include `lang={await getLocale()}` in the `<html>` props.
+
+**Note**: For applications with multiple root layouts, include `GTProvider` in each layout.
+
+2. **Configuration File**: Create a [`gt.config.json`](/docs/cli/reference/config) file in the project root for configuring both `gtx-cli` and `gt-next`:
+
+   ```json title="gt.config.json" copy
+   {
+     "defaultLocale": "en",
+     "locales": ["fr", "es"]
+   }
+   ```
+
+   **Customization**: Set `defaultLocale` and `locales` array to match project requirements. Reference [supported locales](/docs/platform/locale-strings) for valid values.
+
+   **Auto-Detection**: `withGTConfig` automatically detects and uses this configuration file.
+
+## Content Translation Methods
+
+Once setup is complete, implement internationalization using these translation approaches:
+
+### JSX Translation: `<T>` Component
+
+**Purpose**: Primary component for translating JSX content.
+
+**Basic Usage**: Wrap translatable JSX content:
+
+```tsx
+import { T } from 'gt-next';
+<T>
+  <div>Your content</div>
+</T>;
+```
+
+**Dynamic Content**: Use variable components for dynamic values:
+
+```tsx
+import { T, Var } from 'gt-next';
+
+<T>
+  <div>
+    Hello, <Var>{name}</Var>!
+  </div>
+</T>;
+```
+
+**Reference**: Call the tool for the guide on translating JSX content for more information.
+
+### String Translation: `useGT` Hook
+
+**Purpose**: React hook returning a translation function for string content.
+
+**Client-Side Usage**:
+
+```tsx
+'use client'; // must include use client when using useGT
+import { useGT } from 'gt-next/client';
+
+export default function MyComponent() {
+  const t = useGT();
+  return t('Hello, world!');
+}
+```
+
+**Context Restriction**: Client-side components only. Use async `getGT()` function for server-side components.
+
+**Reference**: Call the tool for the guide on client-side components or server-side components for more information.
+
+## Setup Summary
+
+**Core Components Configured**:
+
+- `withGTConfig`: SDK initialization in Next.js configuration
+- `GTProvider`: Context provider for internationalization
+- `gt.config.json`: Locale and translation configuration
+- Translation methods: `<T>` component for JSX, `useGT` hook & `getGT` for strings
+
+**Result**: Fully internationalized Next.js application with hot-reload translation support.

package/guides/next/basic/translating-html.md

@@ -0,0 +1,36 @@
+# Translating html guide
+
+Any time you need to translate HTML or JSX, you should always use the `<T>` component.
+
+**NOTE** other translation methods like `useGT()`, `getGT()`, `useDict()`, and `getDict()` should only be translating strings.
+
+Sample:
+
+```jsx
+export default function MyComponent() {
+  const name = "Brian";
+  return (
+    <p>
+      Hello, my name is {name}
+    <p>
+  );
+}
+```
+
+Internationalized:
+
+```jsx
+import { T, Var } from 'gt-next';
+export default function MyComponent() {
+  const name = "Brian";
+  return (
+    <T>
+      <p>
+        Hello, my name is <Var>{name}</Var>
+      <p>
+    </T>
+  );
+}
+```
+
+Notice how we wrap dynamic content in the `<Var>` tag.