locadex 0.1.2 → 0.1.4

package/guides/next/basic/strings.md

@@ -1,17 +1,18 @@
-# How to internationalize strings with `gt-next`
+# Guide: How to internationalize strings with `gt-next`
 
 Use `useGT()` and `getGT()` to internationalize strings.
 
 **RULES:**
 
-- For JSX and HTML content, ALWAYS use the `<T>` component over `useGT()` and `getGT()`.
-- If you see strings present in HTML that you think need pluralization, do not use strings. Instead use the `<T>` component and the `<Plural>` component. Read the "basic_next-branches" for instructions.
-- NEVER internationalize functional strings (error strings, logical strings, etc.) that could jeporadize the functionality of the application.
+- For JSX and HTML content, ALWAYS use the `<T>` component instead of `useGT()` and `getGT()`.
+- If you see strings present in HTML that you think need pluralization, do not use strings. Instead use the `<T>` component and the `<Plural>` component. See the `mcp__locadex__next_basic_branches` guide for instructions.
+- NEVER internationalize **functional strings** (error strings, logical strings, etc.) that could jeopardize the functionality of the application.
+- **IMPORTANT:** Functional strings can also include strings returned from server actions and API endpoints.
 
-**Import:** The `useGT()` and `getGT()` functions are exported from `gt-next/client` and `gt-next/server` respectively.
+**Import:** The `useGT()` and `getGT()` functions are exported from `gt-next` and `gt-next/server` respectively.
 
 ```tsx
-import { useGT } from 'gt-next/client';
+import { useGT } from 'gt-next';
 import { getGT } from 'gt-next/server';
 ```
 
@@ -24,6 +25,12 @@ The usage of the callback is the same for both `useGT()` and `getGT()`.
 
 `getGT()` is asynchronous and returns a promise that resolves to the translation function callback.
 
+**IMPORTANT:**
+
+- You should use `useGT()` as much as possible. The ONLY time you should use `getGT()` is when the function scope is async.
+
+### Example of `useGT()`
+
 Before:
 
 ```jsx
@@ -36,8 +43,7 @@ function Greeting() {
 After:
 
 ```jsx
-'use client';
-import { useGT } from 'gt-next/client';
+import { useGT } from 'gt-next';
 
 function Greeting() {
   const t = useGT();
@@ -46,7 +52,9 @@ function Greeting() {
 }
 ```
 
-### Server Side
+### Example of `getGT()`
+
+**Important:** Only use `getGT()` in async functions. It must be awaited.
 
 Before:
 
@@ -69,36 +77,33 @@ export async function Greeting() {
 }
 ```
 
-# Context Prop
+## Context Prop
 
 Add `context` when content meaning is ambiguous:
 
 ```jsx
-'use client';
-import { useGT } from 'gt-next/client';
+import { useGT } from 'gt-next';
 
 function Greeting() {
   const t = useGT();
-  const toast = t('Click on the toast to dismiss it.', {
-    context: 'toast, as in a pop-up notification',
+  const crop = t('Crop', {
+    context: 'Crop, as in cropping an image',
   });
-  return toast;
+  return crop;
 }
 ```
 
-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.
+**Rules:**
 
-# Usage 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.
 
-**USE `useGT()` and `getGT()` for:**
+## Translation callback function usage rules
 
-- Static strings
-- Dynamic strings if escaped with `{}` syntax
+- Static strings can always be wrapped in the translation callback function.
+- Dynamic strings must be escaped with `{}` syntax (e.g., `t('Hello, {name}!', { variables: { name: 'John' } })`)
 
-# Valid Usage Examples
+### Valid Usage Examples
 
 In the following examples, `t` is the translation function callback.
 
@@ -123,7 +128,7 @@ const message = t('You have {dollars} dollars!', {
 
 The options are the same as the options for the Intl.NumberFormat and Intl.DateTimeFormat APIs.
 
-# Invalid Usage Examples
+### Invalid Usage Examples
 
 Never use the `${}` syntax for dynamic strings inside the translation callback.
 
@@ -142,3 +147,16 @@ Always add the `variable` key in the options field of `t()` when specifying vari
 ```tsx
 const invalidUsage = t(`Hello, {name}!`, { name: 'Brian' });
 ```
+
+**Correct Usage:**
+
+```tsx
+const correctUsage = t(`Hello, {name}!`, { variables: { name: 'Brian' } });
+```
+
+## Summary
+
+- Use `useGT()` as much as possible. The ONLY time you should use `getGT()` is when the function scope is async.
+- Add `context` when content meaning is ambiguous.
+- Use the translation callback function to wrap static strings.
+- Use the translation callback function with dynamic strings if properly escaped with `{}` syntax.

package/guides/next/basic/variables.md

@@ -1,7 +1,10 @@
-## Variable Components Overview
+# Guide: Variable Components Overview
 
 Variable components wrap dynamic content like user names, numerical values, dates, and currencies. They format and render dynamic values according to the user's locale without requiring external translations.
 
+Variable components can be used as children of `<T>` components or as standalone components.
+When used as children of `<T>` components, the variable components are correctly formatted according to the user's locale.
+
 **Import:** The variable components are exported from `gt-next`.
 
 ```tsx
@@ -67,7 +70,7 @@ The `<T>` component provides locale context and translates surrounding text whil
 
 ### `<Var>` - Dynamic Content Isolation
 
-**Basic Usage:** Always use with `<T>` for locale context.
+**Basic Usage:** Always use with `<T>` to isolate dynamic content from translation processing.
 
 ```jsx
 <T>
@@ -102,6 +105,8 @@ The `<T>` component provides locale context and translates surrounding text whil
 <Num>{quantity}</Num>
 ```
 
+**Rule:** Wrap all dynamic numbers in `<Num>` when using `<T>` components.
+
 ### `<Currency>` - Currency Formatting
 
 **Within `<T>`:** Requires `currency` prop for proper formatting.
@@ -118,6 +123,8 @@ The `<T>` component provides locale context and translates surrounding text whil
 <Currency currency={'USD'}>{total}</Currency>
 ```
 
+**Rule:** Wrap all dynamic currency values in `<Currency>` when using `<T>` components.
+
 ### `<DateTime>` - Date/Time Formatting
 
 **Within `<T>`:** Automatic locale-aware date formatting.
@@ -134,28 +141,21 @@ The `<T>` component provides locale context and translates surrounding text whil
 <DateTime>{date}</DateTime>
 ```
 
+**Rule:** Wrap all dynamic date/time values in `<DateTime>` when using `<T>` components.
+
 ---
 
 ## Common Implementation Issues
 
-### Missing Required Props [#localization-options]
+### Missing Required Props
 
 **Critical:** `<Currency>` requires `currency` prop for proper symbol and formatting.
 
 **Optimization:** All formatting components accept optional props for custom locale behavior.
 
----
-
-## Key Principles
-
-- **Data Isolation:** Variable components isolate dynamic content from translation processing
-- **Privacy:** No data transmission to General Translation APIs
-- **Flexibility:** Use as child of `<T>` or standalone component
-
 ## API References
 
 - [`<Var>`](/docs/next/api/components/var) - Dynamic content wrapper
 - [`<Num>`](/docs/next/api/components/num) - Number formatting options
 - [`<Currency>`](/docs/next/api/components/currency) - Currency formatting options
 - [`<DateTime>`](/docs/next/api/components/datetime) - Date/time formatting options
-- [Branching Components](/docs/next/guides/branches) - Conditional logic patterns

package/guides/next/important/functions.md

@@ -13,25 +13,27 @@
 import {
   GTProvider,
   T,
-  Tx,
   Var,
   Num,
   Currency,
   DateTime,
   Branch,
   Plural,
+  useGT,
+  useTranslations,
+  LocaleSelector,
 } from 'gt-next';
 
+import { useLocale } from 'gt-next/client';
+
 import {
-  useGT,
-  useLocale,
-  useLocales,
-  useSetLocale,
-  useDefaultLocale,
-  useDict,
-  LocaleSelector,
-  useLocaleSelector,
-} from 'gt-next/client';
+  Tx, // Tx is different from tx
+  tx,
+  getGT,
+  getLocale,
+  getTranslations,
+} from 'gt-next/server';
 
-import { withGTConfig } from 'gt-next/config';
+// Typing
+import { InlineTranslationOptions } from 'gt-next/types';
 ```

package/guides/next/{advanced → migration}/migrating.md

@@ -59,8 +59,7 @@ export default function MyComponent() {
 **Option B - Hook-based**:
 
 ```tsx
-'use client'; // Always add 'use client' when working with the useGT() hook
-import { useGT } from 'gt-next/client';
+import { useGT } from 'gt-next';
 export default function MyComponent() {
   const t = useGT();
   return <div>{t('Hello, world!')}</div>;
@@ -73,7 +72,7 @@ export default function MyComponent() {
 
 ### Primary Pattern Preference
 
-**Rule**: Prioritize `useGT()` hook, `getGT()` function, and `<T>` component usage whenever possible.
+**Rule**: Prioritize `useGT()` hook and `<T>` component usage whenever possible.
 
 **Benefits**:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "locadex",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "An AI agent for internationalization",
   "main": "dist/index.js",
   "type": "module",