diff --git a/README.md b/README.md
index 44c5e5fe1..f10080b44 100644
--- a/README.md
+++ b/README.md
@@ -33,7 +33,7 @@ This open-source repo contains internationalization libraries for React framewor
 
 ## Add the `<T>` component and see translations as you code:
 
-![Demo](./apps/docs/public/live_translations.gif)
+![Demo](./apps/docs/public/demo.gif)
 
 ## Features
 
diff --git a/apps/docs/app/[locale]/docs/[[...slug]]/page.tsx b/apps/docs/app/[locale]/docs/[[...slug]]/page.tsx
index 5297cb937..ae185cf08 100644
--- a/apps/docs/app/[locale]/docs/[[...slug]]/page.tsx
+++ b/apps/docs/app/[locale]/docs/[[...slug]]/page.tsx
@@ -32,6 +32,9 @@ import SupportedLocales from '@/components/SupportedLocales';
 import { InlineTOC } from 'fumadocs-ui/components/inline-toc';
 import { Rate } from '@/components/rate';
 import { Metadata } from 'next';
+import { getLocale } from 'gt-next/server';
+import { Mermaid } from '@/components/mdx/mermaid';
+import Video from '@/components/Video';
 
 const customMdxComponents = {
   a: (props: React.ComponentProps<'a'>) => (
@@ -46,11 +49,15 @@ const customMdxComponents = {
   LogoCardContent,
   AllLogoCards,
   SupportedLocales,
+  Mermaid,
+  Video,
 };
 export default async function Page(props: {
   params: Promise<{ slug?: string[]; locale: string }>;
 }) {
-  const { slug, locale } = await props.params;
+  const { slug } = await props.params;
+  const locale = await getLocale();
+
   const page = source.getPage(slug, locale);
   if (!page) notFound();
 
diff --git a/apps/docs/app/[locale]/layout.tsx b/apps/docs/app/[locale]/layout.tsx
index 5de3e2dd0..bc0029edd 100644
--- a/apps/docs/app/[locale]/layout.tsx
+++ b/apps/docs/app/[locale]/layout.tsx
@@ -6,23 +6,26 @@ import { DocsLayout } from 'fumadocs-ui/layouts/notebook';
 import type { ReactNode } from 'react';
 import { baseOptions } from '@/app/[locale]/layout.config';
 import { source } from '@/lib/source';
-import { GTProvider } from 'gt-next';
+import { GTProvider, T } from 'gt-next';
 import { getLocaleProperties } from 'generaltranslation';
 import { SiGithub } from '@icons-pack/react-simple-icons';
 import { PostHogProvider } from '@/components/analytics/PostHogProvider';
 import AnalyticsBanner from '@/components/analytics/AnalyticsBanner';
 import SearchDialog from '@/components/SearchDialog';
 import PrefetchSearchIndex from '@/components/PrefetchSearchIndex';
+import { getGT, getLocale, getLocales } from 'gt-next/server';
 
 const inter = Inter({
   subsets: ['latin'],
 });
 
-export function generateMetadata(): Metadata {
+export async function generateMetadata(): Promise<Metadata> {
+  const gt = await getGT();
   return {
-    title: 'Docs — General Translation',
-    description:
-      'Documentation for the General Translation internationalization platform',
+    title: gt('Docs — General Translation'),
+    description: gt(
+      'Documentation for the General Translation internationalization platform'
+    ),
     icons: {
       icon: [
         {
@@ -38,15 +41,15 @@ export function generateMetadata(): Metadata {
       ],
     },
     keywords: [
-      'translation',
-      'localization',
-      'l10n',
-      'i18n',
-      'internationalization',
-      'automate',
-      'next.js',
-      'nextjs',
-      'react',
+      gt('translation'),
+      gt('localization'),
+      gt('internationalization'),
+      gt('l10n', { context: 'localization' }),
+      gt('i18n', { context: 'internationalization' }),
+      gt('automate'),
+      gt('next.js'),
+      gt('nextjs'),
+      gt('react'),
     ],
   };
 }
@@ -55,16 +58,10 @@ function capitalize(str: string) {
   return str.charAt(0).toUpperCase() + str.slice(1);
 }
 
-export default async function Layout({
-  children,
-  params,
-}: {
-  children: ReactNode;
-  params: Promise<{ locale: string }>;
-}) {
-  const { locale } = await params;
+export default async function Layout({ children }: { children: ReactNode }) {
+  const locale = await getLocale();
   const options = await baseOptions(locale);
-  const locales = ['en', 'zh', 'de', 'fr', 'es', 'ja'].map((locale) => ({
+  const locales = getLocales().map((locale) => ({
     name: capitalize(getLocaleProperties(locale, locale).languageName),
     locale: locale,
   }));
@@ -118,7 +115,7 @@ export default async function Layout({
                     },
                   },
                   banner: (
-                    <>
+                    <T>
                       <a
                         href="https://github.com/generaltranslation/gt"
                         target="_blank"
@@ -131,7 +128,7 @@ export default async function Layout({
                           </h3>
                         </div>
                       </a>
-                    </>
+                    </T>
                   ),
                 }}
                 tree={source.pageTree[locale]}
diff --git a/apps/docs/components/Video.tsx b/apps/docs/components/Video.tsx
index c71966fc3..f4f3d4eeb 100644
--- a/apps/docs/components/Video.tsx
+++ b/apps/docs/components/Video.tsx
@@ -1,5 +1,3 @@
-import { BASE_URL } from '@/lib/constants';
-
 export default function Video({ src }: { src: string }) {
-  return <video src={BASE_URL + src} loop controls className="rounded-lg" />;
+  return <video src={src} loop controls autoPlay className="rounded-lg" />;
 }
diff --git a/apps/docs/components/mdx/mermaid.tsx b/apps/docs/components/mdx/mermaid.tsx
new file mode 100644
index 000000000..cacfbfb1a
--- /dev/null
+++ b/apps/docs/components/mdx/mermaid.tsx
@@ -0,0 +1,60 @@
+'use client';
+
+import { use, useEffect, useId, useState } from 'react';
+import { useTheme } from 'next-themes';
+
+export function Mermaid({ chart }: { chart: string }) {
+  const [mounted, setMounted] = useState(false);
+
+  useEffect(() => {
+    setMounted(true);
+  }, []);
+
+  if (!mounted) return;
+  return <MermaidContent chart={chart} />;
+}
+
+const cache = new Map<string, Promise<unknown>>();
+
+function cachePromise<T>(
+  key: string,
+  setPromise: () => Promise<T>
+): Promise<T> {
+  const cached = cache.get(key);
+  if (cached) return cached as Promise<T>;
+
+  const promise = setPromise();
+  cache.set(key, promise);
+  return promise;
+}
+
+function MermaidContent({ chart }: { chart: string }) {
+  const id = useId();
+  const { resolvedTheme } = useTheme();
+  const { default: mermaid } = use(
+    cachePromise('mermaid', () => import('mermaid'))
+  );
+
+  mermaid.initialize({
+    startOnLoad: false,
+    securityLevel: 'loose',
+    fontFamily: 'inherit',
+    themeCSS: 'margin: 1.5rem auto 0;',
+    theme: resolvedTheme === 'dark' ? 'dark' : 'default',
+  });
+
+  const { svg, bindFunctions } = use(
+    cachePromise(`${chart}-${resolvedTheme}`, () => {
+      return mermaid.render(id, chart.replaceAll('\\n', '\n'));
+    })
+  );
+
+  return (
+    <div
+      ref={(container) => {
+        if (container) bindFunctions?.(container);
+      }}
+      dangerouslySetInnerHTML={{ __html: svg }}
+    />
+  );
+}
diff --git a/apps/docs/content/docs/en/cli/formats/i18next-quickstart.mdx b/apps/docs/content/docs/en/cli/formats/i18next-quickstart.mdx
index ad0a14ca1..e0c406d3c 100644
--- a/apps/docs/content/docs/en/cli/formats/i18next-quickstart.mdx
+++ b/apps/docs/content/docs/en/cli/formats/i18next-quickstart.mdx
@@ -49,7 +49,7 @@ Install the `gtx-cli` tool in your project.
 <Tabs items={['npm', 'yarn', 'bun', 'pnpm']}>
   <Tab value="npm">
   ```bash 
-  npm i --save-dev gtx-cli
+  npm i gtx-cli
   ``` 
   </Tab>
   <Tab value="yarn">
diff --git a/apps/docs/content/docs/en/cli/formats/json.mdx b/apps/docs/content/docs/en/cli/formats/json.mdx
index 9c5c2c7a7..b12423621 100644
--- a/apps/docs/content/docs/en/cli/formats/json.mdx
+++ b/apps/docs/content/docs/en/cli/formats/json.mdx
@@ -56,7 +56,7 @@ Install the `gtx-cli` tool in your project.
 <Tabs items={['npm', 'yarn', 'bun', 'pnpm']}>
   <Tab value="npm">
   ```bash 
-  npm i --save-dev gtx-cli
+  npm i gtx-cli
   ``` 
   </Tab>
   <Tab value="yarn">
diff --git a/apps/docs/content/docs/en/cli/formats/mdx.mdx b/apps/docs/content/docs/en/cli/formats/mdx.mdx
index 059a9866c..7258e2c12 100644
--- a/apps/docs/content/docs/en/cli/formats/mdx.mdx
+++ b/apps/docs/content/docs/en/cli/formats/mdx.mdx
@@ -49,7 +49,7 @@ Install the `gtx-cli` tool in your project.
 <Tabs items={['npm', 'yarn', 'bun', 'pnpm']}>
   <Tab value="npm">
   ```bash 
-  npm i --save-dev gtx-cli
+  npm i gtx-cli
   ``` 
   </Tab>
   <Tab value="yarn">
diff --git a/apps/docs/content/docs/en/cli/formats/next-intl-quickstart.mdx b/apps/docs/content/docs/en/cli/formats/next-intl-quickstart.mdx
index a1b6d0d65..c4113a3c6 100644
--- a/apps/docs/content/docs/en/cli/formats/next-intl-quickstart.mdx
+++ b/apps/docs/content/docs/en/cli/formats/next-intl-quickstart.mdx
@@ -48,7 +48,7 @@ Install the `gtx-cli` tool in your project.
 <Tabs items={['npm', 'yarn', 'bun', 'pnpm']}>
   <Tab value="npm">
   ```bash 
-  npm i --save-dev gtx-cli
+  npm i gtx-cli
   ``` 
   </Tab>
   <Tab value="yarn">
diff --git a/apps/docs/content/docs/en/cli/formats/ts.mdx b/apps/docs/content/docs/en/cli/formats/ts.mdx
index 87f1cd6b2..de388b33c 100644
--- a/apps/docs/content/docs/en/cli/formats/ts.mdx
+++ b/apps/docs/content/docs/en/cli/formats/ts.mdx
@@ -49,7 +49,7 @@ Install the `gtx-cli` tool in your project.
 <Tabs items={['npm', 'yarn', 'bun', 'pnpm']}>
   <Tab value="npm">
   ```bash 
-  npm i --save-dev gtx-cli
+  npm i gtx-cli
   ``` 
   </Tab>
   <Tab value="yarn">
diff --git a/apps/docs/content/docs/en/cli/reference/usage.mdx b/apps/docs/content/docs/en/cli/reference/usage.mdx
index 6362e437c..4f65efbcb 100644
--- a/apps/docs/content/docs/en/cli/reference/usage.mdx
+++ b/apps/docs/content/docs/en/cli/reference/usage.mdx
@@ -21,7 +21,7 @@ To install the CLI tool, run the following command:
 <Tabs items={['npm', 'yarn', 'bun', 'pnpm']}>
   <Tab value="npm">
   ```bash 
-  npm i --save-dev gtx-cli
+  npm i gtx-cli
   ``` 
   </Tab>
   <Tab value="yarn">
diff --git a/apps/docs/content/docs/en/core/class/constructor.mdx b/apps/docs/content/docs/en/core/class/constructor.mdx
new file mode 100644
index 000000000..6b726059c
--- /dev/null
+++ b/apps/docs/content/docs/en/core/class/constructor.mdx
@@ -0,0 +1,123 @@
+---
+title: GT Constructor
+description: API Reference for the GT class constructor
+---
+
+## Overview
+
+The `GT` constructor creates a new instance of the General Translation class, which provides access to all translation, formatting, and locale functionality.
+
+```typescript
+import { GT } from 'generaltranslation';
+
+const gt = new GT({
+  apiKey: 'your-api-key',
+  projectId: 'your-project-id',
+  sourceLocale: 'en',
+  targetLocale: 'es'
+});
+```
+
+The constructor will automatically check the environment for `GT_API_KEY` and `GT_PROJECT_ID` environment variables, so you can omit them from the constructor parameters.
+Additionally, it will validate all provided locale codes.
+
+---
+
+## Reference
+
+### Parameters
+
+<TypeTable
+  type={{
+    "params": {
+      type: 'GTConstructorParams',
+      optional: true,
+      default: '{}',
+    }
+  }}
+/>
+
+The `GTConstructorParams` object supports the following properties:
+
+| Property | Type | Optional | Description |
+|----------|------|----------|-------------|
+| `apiKey` | `string` | ✓ | Production API key for translation service |
+| `devApiKey` | `string` | ✓ | Development API key (takes precedence in development) |
+| `projectId` | `string` | ✓ | Unique project identifier |
+| `sourceLocale` | `string` | ✓ | Default source locale for translations |
+| `targetLocale` | `string` | ✓ | Default target locale for translations |
+| `locales` | `string[]` | ✓ | Array of supported locale codes |
+| `baseUrl` | `string` | ✓ | Custom API base URL (for enterprise deployments) |
+| `customMapping` | `CustomMapping` | ✓ | Custom locale code mappings and definitions |
+
+### Returns
+
+A new `GT` class instance with all translation and locale methods available.
+
+---
+
+
+## Examples
+
+### Basic Usage
+
+```typescript
+import { GT } from 'generaltranslation';
+
+// Minimal setup - uses environment variables
+const gt = new GT();
+```
+
+### With API Credentials
+
+```typescript
+const gt = new GT({
+  projectId: 'my-project-id',
+  apiKey: 'my-api-key',
+  targetLocale: 'fr'
+});
+```
+
+### With Custom Locale Mapping
+A custom mapping can be provided.
+This lets the user (1) use aliases for locale codes which, (2) can override the standard BCP 47 validation, and (3) override the standard BCP 47 locale information.
+
+For example, say you wanted to use `cn` as an alias for `zh`.
+Because the General Translation API does not support `cn`, you must specify a custom mapping.
+
+```typescript
+const gt = new GT({
+  projectId: 'my-project-id',
+  apiKey: 'my-api-key',
+  targetLocale: 'es',
+  customMapping: {
+    'cn': { code: 'zh' }
+  }
+});
+```
+
+You can do other things with custom mappings, such as add custom names, emojis, etc.
+
+```typescript
+const gt = new GT({
+  projectId: 'my-project-id',
+  apiKey: 'my-api-key',
+  targetLocale: 'es',
+  customMapping: { 'en-US': { name: 'Mandarin', emoji: '🇫🇷' } }
+});
+```
+
+---
+
+## Notes
+
+- All parameters are optional, but API operations will require `apiKey` and `projectId`
+- The constructor validates all locale codes immediately, throwing errors for invalid codes
+- Custom mappings take precedence over standard BCP 47 validation
+
+## Next Steps
+
+- Configure your instance with [`setConfig()`](/docs/core/class/setConfig)
+- Start translating with [`translate()`](/docs/core/class/methods/translation/translate)
+- Learn about [`GTConstructorParams` type](/docs/core/types/GTConstructorParams)
+- Explore locale utilities [`getLocaleName()`](/docs/core/class/methods/locales/getLocaleName)
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/core/class/meta.json b/apps/docs/content/docs/en/core/class/meta.json
new file mode 100644
index 000000000..31fc0f43a
--- /dev/null
+++ b/apps/docs/content/docs/en/core/class/meta.json
@@ -0,0 +1,8 @@
+{
+  "title": "GT Class",
+  "pages": [
+    "./constructor",
+    "./setConfig",
+    "./methods"
+  ]
+}
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/core/class/methods/formatting/formatDateTime.mdx b/apps/docs/content/docs/en/core/class/methods/formatting/formatDateTime.mdx
new file mode 100644
index 000000000..2f4996a62
--- /dev/null
+++ b/apps/docs/content/docs/en/core/class/methods/formatting/formatDateTime.mdx
@@ -0,0 +1,163 @@
+---
+title: formatDateTime()
+description: API Reference for the formatDateTime() method to format dates and times according to locale conventions
+---
+
+## Overview
+
+The `formatDateTime()` method formats dates and times according to locale-specific conventions using the Internationalization API.
+It handles date formats, time formats, calendars, and time zones automatically based on the target locale.
+
+```typescript
+const gt = new GT({ targetLocale: 'de-DE' });
+
+const formatted = gt.formatDateTime(new Date(), {
+  dateStyle: 'medium',
+  timeStyle: 'short'
+});
+// Returns: "25.09.2025, 18:06" (German date/time formatting)
+```
+
+## Reference
+
+### Parameters
+
+| Name | Type | Description |
+|------|------|-------------|
+| `date` | `Date` | The date object to format |
+| `options?` | `DateTimeFormatOptions` | Optional formatting configuration |
+
+### DateTimeFormatOptions
+
+Extends `Intl.DateTimeFormatOptions` with additional locale specification:
+
+| Name | Type | Description |
+|------|------|-------------|
+| `locales?` | `string \| string[]` | Override locales for formatting (defaults to instance locales) |
+| `localeMatcher?` | `'lookup' \| 'best fit'` | Locale matching algorithm (default: 'best fit') |
+| `dateStyle?` | `'full' \| 'long' \| 'medium' \| 'short'` | Overall date formatting style |
+| `timeStyle?` | `'full' \| 'long' \| 'medium' \| 'short'` | Overall time formatting style |
+| `weekday?` | `'long' \| 'short' \| 'narrow'` | Weekday representation |
+| `era?` | `'long' \| 'short' \| 'narrow'` | Era representation |
+| `year?` | `'numeric' \| '2-digit'` | Year representation |
+| `month?` | `'numeric' \| '2-digit' \| 'long' \| 'short' \| 'narrow'` | Month representation |
+| `day?` | `'numeric' \| '2-digit'` | Day representation |
+| `dayPeriod?` | `'narrow' \| 'short' \| 'long'` | Day period formatting (morning, afternoon, etc.) |
+| `hour?` | `'numeric' \| '2-digit'` | Hour representation |
+| `minute?` | `'numeric' \| '2-digit'` | Minute representation |
+| `second?` | `'numeric' \| '2-digit'` | Second representation |
+| `fractionalSecondDigits?` | `1 \| 2 \| 3` | Number of fractional second digits |
+| `timeZoneName?` | `'long' \| 'short' \| 'longOffset' \| 'shortOffset' \| 'longGeneric' \| 'shortGeneric'` | Time zone name format |
+| `timeZone?` | `string` | IANA time zone identifier |
+| `hour12?` | `boolean` | Whether to use 12-hour time format |
+| `hourCycle?` | `'h11' \| 'h12' \| 'h23' \| 'h24'` | Hour cycle preference |
+| `calendar?` | `string` | Calendar system to use |
+| `numberingSystem?` | `string` | Numbering system for digits |
+| `formatMatcher?` | `'basic' \| 'best fit'` | Format matching algorithm (default: 'best fit') |
+
+### Returns
+
+`string` - The formatted date and time according to locale conventions.
+
+---
+
+## Examples
+
+### Basic Date and Time Formatting
+
+```typescript copy
+import { GT } from 'generaltranslation';
+
+const gt = new GT({ targetLocale: 'en-US' });
+const date = new Date('2024-03-14T14:30:45Z');
+
+// Basic date formatting (uses default options)
+console.log(gt.formatDateTime(date));
+// Output: "3/14/2024"
+
+// German locale formatting
+console.log(gt.formatDateTime(date, { locales: 'de-DE' }));
+// Output: "14.3.2024"
+
+// Japanese locale formatting
+console.log(gt.formatDateTime(date, { locales: 'ja-JP' }));
+// Output: "2024/3/14"
+```
+
+### Date and Time Styles
+
+```typescript copy
+const date = new Date('2024-03-14T14:30:45Z');
+
+// Full date style
+console.log(gt.formatDateTime(date, { dateStyle: 'full' }));
+// Output: "Thursday, March 14, 2024"
+
+// Long date with short time
+console.log(gt.formatDateTime(date, {
+  dateStyle: 'long',
+  timeStyle: 'short'
+}));
+// Output: "March 14, 2024 at 7:30 AM"
+
+// Custom date components
+console.log(gt.formatDateTime(date, {
+  weekday: 'long',
+  year: 'numeric',
+  month: 'long',
+  day: 'numeric'
+}));
+// Output: "Thursday, March 14, 2024"
+```
+
+### Time Zone and Hour Format
+
+```typescript copy
+const date = new Date('2024-03-14T14:30:45Z');
+
+// Force 12-hour format
+console.log(gt.formatDateTime(date, {
+  hour: 'numeric',
+  minute: '2-digit',
+  hour12: true
+}));
+// Output: "7:30 AM"
+
+// Force 24-hour format
+console.log(gt.formatDateTime(date, {
+  hour: 'numeric',
+  minute: '2-digit',
+  hour12: false
+}));
+// Output: "07:30"
+
+// Specific time zone
+console.log(gt.formatDateTime(date, {
+  timeZone: 'America/New_York',
+  dateStyle: 'medium',
+  timeStyle: 'short'
+}));
+// Output: "Mar 14, 2024, 10:30 AM"
+```
+
+---
+
+## Notes
+
+* Date formatting follows locale-specific conventions automatically
+* The method uses browser-native `Intl.DateTimeFormat` for optimal performance and accuracy
+* Time zones are handled correctly when specified
+
+## Related Methods
+
+* Check out [`Intl.DateTimeFormat` documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat) for more options
+* See [`formatRelativeTime()`](/docs/core/class/methods/formatting/formatRelativeTime) for relative date formatting ("2 days ago")
+* See [`formatMessage()`](/docs/core/class/methods/formatting/formatMessage) for message formatting with date interpolation
+* See standalone [`formatDateTime()`](/docs/core/functions/formatting/formatDateTime) for use without GT instance
+* See [`getLocaleProperties()`](/docs/core/class/methods/locales/getLocaleProperties) for locale-specific calendar information
+
+## Next Steps
+
+* See [Formatting Guide](/docs/core/guides/formatting) for comprehensive date/time formatting strategies
+* See [Internationalization Guide](/docs/core/guides/i18n) for locale-aware date handling
+* See [Time Zone Guide](/docs/core/guides/timezones) for advanced time zone management
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/core/class/methods/formatting/formatMessage.mdx b/apps/docs/content/docs/en/core/class/methods/formatting/formatMessage.mdx
new file mode 100644
index 000000000..93dff228a
--- /dev/null
+++ b/apps/docs/content/docs/en/core/class/methods/formatting/formatMessage.mdx
@@ -0,0 +1,165 @@
+---
+title: formatMessage()
+description: API Reference for the GT formatMessage method
+---
+
+## Overview
+
+The `formatMessage()` method formats messages with variable substitution and locale-aware formatting.
+Built on top of Format.JS's [`intl-messageformat`](https://formatjs.github.io/docs/intl-messageformat/) library, it supports ICU message format patterns.
+
+This method is essential for variable interpolation and pluralization.
+It also supports number formatting and date formatting among other features.
+
+```typescript
+const gt = new GT({
+  sourceLocale: 'en',
+  targetLocale: 'fr'
+});
+
+const formatted = gt.formatMessage('Hello {name}, you have {count} messages', {
+  variables: { name: 'Alice', count: 5 }
+});
+// Returns: "Hello Alice, you have 5 messages"
+```
+
+---
+
+## Reference
+
+### Parameters
+
+<TypeTable
+  type={{
+    "message": {
+      type: 'string',
+      optional: false,
+    },
+    "options?": {
+      type: 'object',
+      optional: true,
+    }
+  }}
+/>
+
+### Options Object
+
+| Property | Type | Optional | Description |
+|----------|------|----------|-------------|
+| `locales` | `string \| string[]` | ✓ | Locale(s) to use for formatting (overrides instance defaults) |
+| `variables` | `FormatVariables` | ✓ | Object containing variables for message interpolation |
+
+### FormatVariables Type
+
+```typescript
+type FormatVariables = {
+  [key: string]: string | number | Date | boolean;
+};
+```
+
+### Returns
+
+`string` - The formatted message with variables substituted and locale-specific formatting applied.
+
+---
+
+## Behavior
+
+
+### Variable Substitution
+
+- Simple variables: `{variableName}` → replaced with string value
+- ICU patterns: `{count, plural, ...}` → processed with ICU formatting rules
+- Missing variables: will result in an error
+- Double curly braces: will escape the curly brace behavior and render as a single curly brace
+
+### Message Format Support
+
+- **Simple interpolation**: `{variable}`
+- **Number formatting**: `{price, number, ::currency/USD}`, `{discount, number, percent}`, `{num, number, integer}`
+- **Date formatting**: `{date, date, short}`, `{time, time, short}`
+- **Pluralization**: `{count, plural, =0 {none} =1 {one} other {many}}`
+- **Selection**: `{gender, select, male {he} female {she} other {they}}`
+- **Selectordinal**: `{place, selectordinal, =1 {#st} =2 {#nd} =3 {#rd} other {#th}}`
+
+---
+
+## Examples
+
+### Basic Variable Substitution
+
+```typescript
+const gt = new GT({ targetLocale: 'en' });
+
+const message = gt.formatMessage('Welcome {name}!', {
+  variables: { name: 'John' }
+});
+console.log(message); // "Welcome John!"
+```
+
+### Pluralization with ICU Format
+
+```typescript
+const message = gt.formatMessage(
+  'You have {count, plural, =0 {no items} =1 {one item} other {# items}} in your cart',
+  {
+    variables: { count: 3 }
+  }
+);
+console.log(message); // "You have 3 items in your cart"
+```
+
+### Number and Currency Formatting
+
+```typescript
+const gt = new GT({ targetLocale: 'en' });
+
+const message = gt.formatMessage(
+  'Your total is {price, number, ::currency/USD} with {discount, number, percent} off',
+  {
+    variables: { 
+      price: 99.99,
+      discount: 0.15 
+    }
+  }
+);
+console.log(message); // "Your total is $99.99 with 15% off"
+```
+
+### Complex Message Templates
+
+```typescript
+const orderStatusMessage = gt.formatMessage(`
+  Order #{orderId} status update:
+  - Items: {itemCount, plural, =0 {no items} =1 {one item} other {# items}}
+  - Total: {total, number, ::currency/USD}
+  - Status: {status, select, 
+      pending {Pending} 
+      shipped {Shipped} 
+      delivered {Delivered} 
+      other {Unknown}}
+  - Delivery: {deliveryDate, date, short}
+`, {
+  variables: {
+    orderId: 'ORD-12345',
+    itemCount: 3,
+    total: 149.97,
+    status: 'shipped',
+    deliveryDate: new Date('2024-03-20')
+  }
+});
+```
+
+---
+
+## Notes
+
+- The method processes ICU message format syntax for advanced formatting using [`Intl.MessageFormat`](https://formatjs.github.io/docs/intl-messageformat/) from Format.JS.
+- Missing variables will throw an error.
+- Locale-specific number, date, and currency formatting is applied automatically
+
+## Next Steps
+
+- Check out [`Intl.MessageFormat` documentation](https://formatjs.github.io/docs/intl-messageformat/) for more options
+- Format numbers with [formatNum()](/docs/core/class/methods/formatting/formatNum)
+- Format dates with [formatDateTime()](/docs/core/class/methods/formatting/formatDateTime)
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/core/class/methods/formatting/formatNum.mdx b/apps/docs/content/docs/en/core/class/methods/formatting/formatNum.mdx
new file mode 100644
index 000000000..2002722fb
--- /dev/null
+++ b/apps/docs/content/docs/en/core/class/methods/formatting/formatNum.mdx
@@ -0,0 +1,159 @@
+---
+title: formatNum()
+description: API Reference for the formatNum() method to format numbers according to locale conventions
+---
+
+## Overview
+
+The `formatNum()` method formats numbers according to locale-specific conventions using the Internationalization API.
+It handles decimal separators, thousands separators, and numbering systems automatically based on the target locale.
+
+```typescript
+const gt = new GT({ targetLocale: 'de' });
+
+const formatted = gt.formatNum(1234.56, {
+  style: 'decimal',
+  minimumFractionDigits: 2
+});
+// Returns: "1.234,56" (German number formatting)
+```
+
+
+## Reference
+
+### Parameters
+
+| Name | Type | Description |
+|------|------|-------------|
+| `number` | `number` | The number to format |
+| `options?` | `NumberFormatOptions` | Optional formatting configuration |
+
+### NumberFormatOptions
+
+Extends `Intl.NumberFormatOptions` with additional locale specification:
+
+| Name | Type | Description |
+|------|------|-------------|
+| `locales?` | `string \| string[]` | Override locales for formatting (defaults to instance locales) |
+| `style?` | `'decimal' \| 'currency' \| 'percent' \| 'unit'` | Number formatting style |
+| `currency?` | `string` | Currency code (required when style is 'currency') |
+| `currencyDisplay?` | `'symbol' \| 'narrowSymbol' \| 'code' \| 'name'` | How to display the currency |
+| `currencySign?` | `'standard' \| 'accounting'` | Currency sign to use |
+| `unit?` | `string` | Unit identifier (required when style is 'unit') |
+| `unitDisplay?` | `'short' \| 'narrow' \| 'long'` | How to display the unit |
+| `minimumIntegerDigits?` | `number` | Minimum number of integer digits (1-21) |
+| `minimumFractionDigits?` | `number` | Minimum number of fraction digits (0-20) |
+| `maximumFractionDigits?` | `number` | Maximum number of fraction digits (0-20) |
+| `minimumSignificantDigits?` | `number` | Minimum significant digits (1-21) |
+| `maximumSignificantDigits?` | `number` | Maximum significant digits (1-21) |
+| `useGrouping?` | `boolean \| 'always' \| 'auto' \| 'min2'` | Whether to use grouping separators |
+| `notation?` | `'standard' \| 'scientific' \| 'engineering' \| 'compact'` | Number notation format |
+| `compactDisplay?` | `'short' \| 'long'` | Compact notation display style |
+| `signDisplay?` | `'auto' \| 'never' \| 'always' \| 'exceptZero'` | When to display the sign |
+| `roundingMode?` | `'ceil' \| 'floor' \| 'expand' \| 'trunc' \| 'halfCeil' \| 'halfFloor' \| 'halfExpand' \| 'halfTrunc' \| 'halfEven'` | Rounding mode |
+| `roundingIncrement?` | `1 \| 2 \| 5 \| 10 \| 20 \| 25 \| 50 \| 100` | Rounding increment |
+| `trailingZeroDisplay?` | `'auto' \| 'stripIfInteger'` | Whether to display trailing zeros |
+
+### Returns
+
+`string` - The formatted number according to locale conventions.
+
+---
+
+## Examples
+
+### Basic Number Formatting
+
+```typescript copy
+import { GT } from 'generaltranslation';
+
+const gt = new GT({ targetLocale: 'en-US' });
+
+// Basic decimal formatting
+console.log(gt.formatNum(1234.567));
+// Output: "1,234.567"
+
+// German locale formatting
+console.log(gt.formatNum(1234.567, { locales: 'de-DE' }));
+// Output: "1.234,567"
+
+// French locale formatting  
+console.log(gt.formatNum(1234.567, { locales: 'fr-FR' }));
+// Output: "1 234,567"
+```
+
+### Currency Formatting
+
+```typescript copy
+// US Dollar formatting
+console.log(gt.formatNum(1234.56, {
+  style: 'currency',
+  currency: 'USD'
+}));
+// Output: "$1,234.56"
+
+// Euro formatting with German locale
+console.log(gt.formatNum(1234.56, {
+  style: 'currency',
+  currency: 'EUR',
+  locales: 'de-DE'
+}));
+// Output: "1.234,56 €"
+
+// Currency display options
+console.log(gt.formatNum(1234.56, {
+  style: 'currency',
+  currency: 'USD',
+  currencyDisplay: 'code'
+}));
+// Output: "USD 1,234.56"
+
+// Accounting format (parentheses for negative)
+console.log(gt.formatNum(-1234.56, {
+  style: 'currency',
+  currency: 'USD',
+  currencySign: 'accounting'
+}));
+// Output: "($1,234.56)"
+```
+
+### Percentage and Scientific Notation
+
+```typescript copy
+// Basic percentage
+console.log(gt.formatNum(0.1234, { style: 'percent' }));
+// Output: "12%"
+
+// Percentage with decimal places
+console.log(gt.formatNum(0.1234, {
+  style: 'percent',
+  minimumFractionDigits: 1,
+  maximumFractionDigits: 2
+}));
+// Output: "12.34%"
+
+// Compact notation
+console.log(gt.formatNum(1234567, { notation: 'compact' }));
+// Output: "1.2M"
+
+// Scientific notation
+console.log(gt.formatNum(1234567, { notation: 'scientific' }));
+// Output: "1.235E6"
+```
+
+---
+
+## Notes
+
+* Number formatting follows locale-specific conventions automatically
+* The method uses browser-native `Intl.NumberFormat` for optimal performance and accuracy
+* Currency formatting requires both `style: 'currency'` and a valid `currency` code
+* Unit formatting requires both `style: 'unit'` and a valid `unit` identifier
+
+## Next Steps
+
+* Check out [`Intl.NumberFormat` documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat) for more options
+* See [`formatCurrency()`](/docs/core/class/methods/formatting/formatCurrency) for specialized currency formatting
+* See [`formatMessage()`](/docs/core/class/methods/formatting/formatMessage) for message formatting with number interpolation
+* See standalone [`formatNum()`](/docs/core/functions/formatting/formatNum) for use without GT instance
+* See [`getLocaleProperties()`](/docs/core/class/methods/locales/getLocaleProperties) for locale-specific formatting information
diff --git a/apps/docs/content/docs/en/core/class/methods/formatting/meta.json b/apps/docs/content/docs/en/core/class/methods/formatting/meta.json
new file mode 100644
index 000000000..0ffd4b92f
--- /dev/null
+++ b/apps/docs/content/docs/en/core/class/methods/formatting/meta.json
@@ -0,0 +1,4 @@
+{
+  "title": "Formatting",
+  "pages": ["./formatDateTime", "./formatMessage", "./formatNum"]
+}
diff --git a/apps/docs/content/docs/en/core/class/methods/locales/determineLocale.mdx b/apps/docs/content/docs/en/core/class/methods/locales/determineLocale.mdx
new file mode 100644
index 000000000..730f02ecf
--- /dev/null
+++ b/apps/docs/content/docs/en/core/class/methods/locales/determineLocale.mdx
@@ -0,0 +1,92 @@
+---
+title: determineLocale()
+description: API Reference for the GT determineLocale method
+---
+
+## Overview
+
+The `determineLocale()` method determines the best matching locale from a list of approved locales based on user preferences.
+It implements locale negotiation to find the most suitable locale when exact matches aren't available.
+
+```typescript
+const gt = new GT({
+  sourceLocale: 'en-US',
+  locales: ['en-US', 'es-ES', 'fr-FR', 'de-DE']
+});
+
+// Exact match
+console.log(gt.determineLocale('en-US')); // 'en-US'
+
+// Language fallback
+console.log(gt.determineLocale('en-GB')); // 'en-US' (closest English variant)
+
+// Multiple preferences
+console.log(gt.determineLocale(['fr-CA', 'es-MX', 'en-US'])); // 'es-ES' (closest Spanish)
+
+// No match
+console.log(gt.determineLocale('it-IT')); // undefined
+```
+
+---
+
+## Reference
+
+### Parameters
+
+<TypeTable
+  type={{
+    "locales": {
+      type: 'string | string[]',
+      optional: false,
+    },
+    "approvedLocales?": {
+      type: 'string[]',
+      optional: true,
+      default: 'this.locales'
+    },
+    "customMapping?": {
+      type: 'CustomMapping',
+      optional: true,
+      default: 'this.customMapping'
+    }
+  }}
+/>
+
+### Returns
+
+`string | undefined` - Best matching locale or undefined if no match found
+
+---
+
+## Examples
+
+### User Locale Negotiation
+
+```typescript
+const gt = new GT({
+  sourceLocale: 'en-US',
+  locales: ['en-US', 'en-GB', 'es-ES', 'fr-FR']
+});
+
+// Simulate browser Accept-Language header
+const userPreferences = ['fr-CA', 'en-GB', 'en'];
+const bestMatch = gt.determineLocale(userPreferences);
+console.log(bestMatch); // 'fr-FR' based on preference order
+
+```
+
+---
+
+## Notes
+
+- Returns the first exact match from approved locales
+- Falls back to language matches when exact region isn't available  
+- Respects preference order in input array
+- Returns undefined when no suitable match is found
+- Essential for implementing locale negotiation in web applications
+
+## Next Steps
+
+- Check translation needs with [`requiresTranslation()`](/docs/core/class/methods/locales/requiresTranslation)
+- Compare languages with [`isSameLanguage()`](/docs/core/class/methods/locales/isSameLanguage)
+- Explore standalone [`determineLocale()`](/docs/core/functions/locales/determineLocale)
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/core/class/methods/locales/getLocaleDirection.mdx b/apps/docs/content/docs/en/core/class/methods/locales/getLocaleDirection.mdx
new file mode 100644
index 000000000..c22b5c152
--- /dev/null
+++ b/apps/docs/content/docs/en/core/class/methods/locales/getLocaleDirection.mdx
@@ -0,0 +1,87 @@
+---
+title: getLocaleDirection()
+description: API Reference for the GT getLocaleDirection method
+---
+
+## Overview
+
+The `getLocaleDirection()` method determines the text direction (left-to-right or right-to-left) for a locale using the `Intl.Locale` API.
+It returns either `'ltr'` for left-to-right languages or `'rtl'` for right-to-left languages.
+
+```typescript
+const gt = new GT({
+  sourceLocale: 'en',
+  targetLocale: 'ar'
+});
+
+const direction = gt.getLocaleDirection('ar');
+console.log(direction); // "rtl"
+
+const englishDirection = gt.getLocaleDirection('en-US');
+console.log(englishDirection); // "ltr"
+```
+
+---
+
+## Reference
+
+### Parameters
+
+<TypeTable
+  type={{
+    "locale?": {
+      type: 'string',
+      optional: true,
+      default: 'this.targetLocale',
+    }
+  }}
+/>
+
+### Parameters Description
+
+| Parameter | Description |
+|-----------|-------------|
+| `locale` | BCP-47 locale code to check text direction for. If not provided, uses the instance's `targetLocale` |
+
+### Returns
+
+`'ltr' | 'rtl'` - Text direction for the locale:
+- `'ltr'`: Left-to-right (most languages)
+- `'rtl'`: Right-to-left (Arabic, Hebrew, Persian, Urdu, etc.)
+
+### Throws
+
+- `Error` - If no locale is provided and the instance has no `targetLocale` configured
+
+---
+
+## Example
+
+```typescript
+const gt = new GT({
+  sourceLocale: 'en',
+  targetLocale: 'ar'
+});
+
+// Check different language directions
+console.log(gt.getLocaleDirection()); // "rtl" (uses targetLocale 'ar')
+console.log(gt.getLocaleDirection('en')); // "ltr"
+console.log(gt.getLocaleDirection('ar')); // "rtl"
+console.log(gt.getLocaleDirection('he')); // "rtl"
+console.log(gt.getLocaleDirection('fa')); // "rtl"
+console.log(gt.getLocaleDirection('fr')); // "ltr"
+```
+
+---
+
+## Notes
+
+- Returns `'ltr'` for all left-to-right languages (most languages worldwide)
+- Returns `'rtl'` for right-to-left languages (Arabic, Hebrew, Persian, etc.)
+
+## Next Steps
+
+- Get locale properties with [`getLocaleProperties()`](/docs/core/class/methods/locales/getLocaleProperties)
+- Validate locales with [`isValidLocale()`](/docs/core/class/methods/locales/isValidLocale)
+- Get locale emoji with [`getLocaleEmoji()`](/docs/core/class/methods/locales/getLocaleEmoji)
+- Explore standalone [`getLocaleDirection()`](/docs/core/functions/locales/getLocaleDirection)
diff --git a/apps/docs/content/docs/en/core/class/methods/locales/getLocaleEmoji.mdx b/apps/docs/content/docs/en/core/class/methods/locales/getLocaleEmoji.mdx
new file mode 100644
index 000000000..4f8909ffb
--- /dev/null
+++ b/apps/docs/content/docs/en/core/class/methods/locales/getLocaleEmoji.mdx
@@ -0,0 +1,98 @@
+---
+title: getLocaleEmoji()
+description: API Reference for the GT getLocaleEmoji method
+---
+
+## Overview
+
+The `getLocaleEmoji()` method retrieves an emoji flag or symbol for a locale code based on its region.
+It returns appropriate flag emojis for countries and territories, with fallbacks for languages without specific regions and custom emoji support through mappings.
+
+```typescript
+const gt = new GT({
+  sourceLocale: 'en',
+  targetLocale: 'fr-CA'
+});
+
+const emoji = gt.getLocaleEmoji('fr-CA');
+console.log(emoji); // "🇨🇦" (Canadian flag)
+
+const usEmoji = gt.getLocaleEmoji('en-US');
+console.log(usEmoji); // "🇺🇸" (US flag)
+
+const enEmoji = gt.getLocaleEmoji('en');
+console.log(enEmoji); // "🇺🇸" (US flag)
+```
+
+---
+
+## Reference
+
+### Parameters
+
+<TypeTable
+  type={{
+    "locale?": {
+      type: 'string',
+      optional: true,
+      default: 'this.targetLocale',
+    }
+  }}
+/>
+
+### Parameters Description
+
+| Parameter | Description |
+|-----------|-------------|
+| `locale` | BCP-47 locale code to get emoji for. If not provided, uses the instance's `targetLocale` |
+
+### Returns
+
+`string` - Emoji flag or symbol representing the locale:
+- Country/territory flag emoji for locales with regions (e.g., `🇺🇸`, `🇫🇷`, `🇯🇵`)
+- Language-specific emoji for some languages without regions
+- Default flag emoji (`🏳️`) for unrecognized locales
+
+### Throws
+
+- `Error` - If no locale is provided and the instance has no `targetLocale` configured
+
+---
+
+
+## Examples
+
+```typescript
+const gt = new GT({
+  sourceLocale: 'en',
+  targetLocale: 'es'
+});
+
+// Get emoji for target locale
+console.log(gt.getLocaleEmoji()); // "🇪🇸" (uses targetLocale 'es')
+
+// Get emojis for different locales
+console.log(gt.getLocaleEmoji('en-US')); // "🇺🇸"
+console.log(gt.getLocaleEmoji('fr-FR')); // "🇫🇷"
+console.log(gt.getLocaleEmoji('de-DE')); // "🇩🇪"
+console.log(gt.getLocaleEmoji('ja-JP')); // "🇯🇵"
+console.log(gt.getLocaleEmoji('zh-CN')); // "🇨🇳"
+```
+
+---
+
+## Notes
+
+- Returns flag emojis based on the locale's region code when available
+- Custom mapping emojis take priority over region-based selection
+- Uses Unicode regional indicator symbols for flag generation
+- Defaults to `🏳️` (white flag) for unrecognized or invalid locales
+- Compatible with all modern browsers and operating systems that support Unicode emojis
+
+## Next Steps
+
+- Get locale properties with [`getLocaleProperties()`](/docs/core/class/methods/locales/getLocaleProperties)
+- Get locale names with [`getLocaleName()`](/docs/core/class/methods/locales/getLocaleName)
+- Validate locales with [`isValidLocale()`](/docs/core/class/methods/locales/isValidLocale)
+- Learn about CustomMapping type](/docs/core/types/CustomMapping)
+- Explore standalone [`getLocaleEmoji()`](/docs/core/functions/locales/getLocaleEmoji)
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/core/class/methods/locales/getLocaleName.mdx b/apps/docs/content/docs/en/core/class/methods/locales/getLocaleName.mdx
new file mode 100644
index 000000000..3788266e3
--- /dev/null
+++ b/apps/docs/content/docs/en/core/class/methods/locales/getLocaleName.mdx
@@ -0,0 +1,98 @@
+---
+title: getLocaleName()
+description: API Reference for the GT getLocaleName method
+---
+
+## Overview
+
+The `getLocaleName()` method retrieves the display name of a locale code using the `Intl.DisplayNames` API.
+It returns a human-readable name for any valid BCP-47 locale code, localized according to the instance's source locale.
+
+```typescript
+const gt = new GT({
+  sourceLocale: 'en',
+  targetLocale: 'es'
+});
+
+const name = gt.getLocaleName('fr-CA');
+console.log(name); // "French (Canada)"
+```
+
+---
+
+## Reference
+
+### Parameters
+
+<TypeTable
+  type={{
+    "locale?": {
+      type: 'string',
+      optional: true,
+      default: 'this.targetLocale',
+    }
+  }}
+/>
+
+### Parameters Description
+
+| Parameter | Description |
+|-----------|-------------|
+| `locale` | BCP-47 locale code to get the display name for. If not provided, uses the instance's `targetLocale` |
+
+### Returns
+
+`string` - The localized display name of the locale.
+
+### Throws
+
+- `Error` - If no locale is provided and the instance has no `targetLocale` configured
+
+---
+
+## Behavior
+
+### Display Language
+
+The display name is localized according to:
+1. Instance's `sourceLocale` (if configured)
+2. Library default locale ('en')
+
+### Custom Mapping Integration
+
+- Custom locale mappings are checked first
+- If a custom name is defined, it takes precedence
+- Falls back to `Intl.DisplayNames` for standard BCP-47 codes
+
+---
+
+## Examples
+
+```typescript
+const gt = new GT({
+  sourceLocale: 'en',
+  targetLocale: 'fr'
+});
+
+// Get name for target locale
+console.log(gt.getLocaleName()); // "French (France)"
+
+// Get names for other locales
+console.log(gt.getLocaleName('es')); // "Spanish (Spain)"
+console.log(gt.getLocaleName('de')); // "German (Germany)"
+console.log(gt.getLocaleName('ja')); // "Japanese (Japan)"
+```
+
+---
+
+## Notes
+
+- The method uses the instance's `sourceLocale` to determine display language
+- Custom mapping names take precedence over standard Intl.DisplayNames
+
+## Next Steps
+
+- Get locale emoji with [`getLocaleEmoji()`](/docs/core/class/methods/locales/getLocaleEmoji)
+- Get comprehensive locale info with [`getLocaleProperties()`](/docs/core/class/methods/locales/getLocaleProperties)
+- Learn about CustomMapping type](/docs/core/types/CustomMapping)
+- Explore standalone [`getLocaleName()`](/docs/core/functions/locales/getLocaleName)
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/core/class/methods/locales/getLocaleProperties.mdx b/apps/docs/content/docs/en/core/class/methods/locales/getLocaleProperties.mdx
new file mode 100644
index 000000000..aa269a7f6
--- /dev/null
+++ b/apps/docs/content/docs/en/core/class/methods/locales/getLocaleProperties.mdx
@@ -0,0 +1,105 @@
+---
+title: getLocaleProperties()
+description: API Reference for the GT getLocaleProperties method
+---
+
+## Overview
+
+The `getLocaleProperties()` method retrieves comprehensive properties for a locale code, providing
+detailed information including display names, region codes, script information, and emoji flags.
+It returns a complete `LocaleProperties` object with all necessary data for building rich internationalized user interfaces.
+
+```typescript
+const gt = new GT({
+  sourceLocale: 'en',
+  targetLocale: 'es'
+});
+
+const props = gt.getLocaleProperties('fr-CA');
+console.log(props.name); // "French (Canada)"
+console.log(props.nativeName); // "français (Canada)"
+console.log(props.emoji); // "🇨🇦"
+```
+
+---
+
+## Reference
+
+### Parameters
+
+<TypeTable
+  type={{
+    "locale?": {
+      type: 'string',
+      optional: true,
+      default: 'this.targetLocale',
+    }
+  }}
+/>
+
+### Parameters Description
+
+| Parameter | Description |
+|-----------|-------------|
+| `locale` | BCP-47 locale code to get properties for. If not provided, uses the instance's `targetLocale` |
+
+### Returns
+
+`LocaleProperties` - A comprehensive object containing all locale information:
+
+- `code`: Standardized locale code
+- `name`: Display name in source locale
+- `nativeName`: Display name in the locale itself
+- `languageCode`, `languageName`, `nativeLanguageName`: Language information
+- `regionCode`, `regionName`, `nativeRegionName`: Region information  
+- `scriptCode`, `scriptName`, `nativeScriptName`: Script information
+- `maximizedCode`, `minimizedCode`: Canonical forms
+- `nameWithRegionCode`, `nativeNameWithRegionCode`: Combined display formats
+- `emoji`: Flag or representative emoji
+
+### Throws
+
+- `Error` - If no locale is provided and the instance has no `targetLocale` configured
+
+---
+
+## Examples
+
+### Basic Usage
+
+```typescript
+const gt = new GT({
+  sourceLocale: 'en',
+  targetLocale: 'fr'
+});
+
+// Get properties for target locale
+const props = gt.getLocaleProperties();
+console.log(props.name); // "French (France)"
+console.log(props.nativeName); // "français (France)"
+console.log(props.languageCode); // "fr"
+console.log(props.regionCode); // "FR"
+console.log(props.emoji); // "🇫🇷"
+
+// Get properties for other locales
+const germanProps = gt.getLocaleProperties('de-AT');
+console.log(germanProps.name); // "Austrian German"
+console.log(germanProps.nativeName); // "Österreichisches Deutsch"
+console.log(germanProps.regionName); // "Austria"
+console.log(germanProps.nativeRegionName); // "Österreich"
+```
+
+---
+
+## Notes
+
+- All display names respect the instance's `sourceLocale` setting
+- Custom mapping properties take precedence over standard Intl APIs
+
+## Next Steps
+
+- Explore [`LocaleProperties`](/docs/core/types/LocaleProperties) interface
+- Get simple locale names with [`getLocaleName()`](/docs/core/class/methods/locales/getLocaleName)
+- Get locale emoji with [`getLocaleEmoji()`](/docs/core/class/methods/locales/getLocaleEmoji)
+- Learn about [`CustomMapping`](/docs/core/types/CustomMapping) type
+- Explore standalone [`getLocaleProperties()`](/docs/core/functions/locales/getLocaleProperties)
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/core/class/methods/locales/getRegionProperties.mdx b/apps/docs/content/docs/en/core/class/methods/locales/getRegionProperties.mdx
new file mode 100644
index 000000000..c1209ee95
--- /dev/null
+++ b/apps/docs/content/docs/en/core/class/methods/locales/getRegionProperties.mdx
@@ -0,0 +1,100 @@
+---
+title: getRegionProperties()
+description: API Reference for the GT getRegionProperties method
+---
+
+## Overview
+
+The `getRegionProperties()` method retrieves detailed information about a region code, including its localized name and associated emoji flag.
+It provides a convenient way to get region-specific display information for building internationalized user interfaces.
+
+```typescript
+const gt = new GT({
+  sourceLocale: 'en-US',
+  targetLocale: 'fr-FR'
+});
+
+// Get region properties
+const usProps = gt.getRegionProperties('US');
+console.log(usProps);
+// { code: 'US', name: 'United States', emoji: '🇺🇸' }
+
+const frProps = gt.getRegionProperties('FR');
+console.log(frProps);
+// { code: 'FR', name: 'France', emoji: '🇫🇷' }
+
+// Auto-detect from current locale
+const currentRegion = gt.getRegionProperties(); // Uses targetLocale's region
+console.log(currentRegion);
+// { code: 'FR', name: 'France', emoji: '🇫🇷' }
+```
+
+---
+
+## Reference
+
+### Parameters
+
+<TypeTable
+  type={{
+    "region?": {
+      type: 'string',
+      optional: true,
+      default: 'this.getLocaleProperties().regionCode'
+    },
+    "customMapping?": {
+      type: 'CustomRegionMapping',
+      optional: true,
+      default: 'this.customRegionMapping'
+    }
+  }}
+/>
+
+### Parameters Description
+
+| Parameter | Description |
+|-----------|--------------|
+| `region` | ISO 3166-1 alpha-2 or UN M.49 region code. If not provided, uses the region from the instance's target locale |
+| `customMapping` | Optional custom region mapping to override default region names and emojis |
+
+### Returns
+
+`{ code: string; name: string; emoji: string }` - Object containing:
+- `code`: The input region code
+- `name`: Localized region name in the target locale language
+- `emoji`: Associated emoji flag or symbol
+
+---
+
+## Examples
+
+### Basic Region Information
+
+```typescript
+const gt = new GT({
+  sourceLocale: 'en-US',
+  targetLocale: 'en-US'
+});
+
+// Common region codes
+console.log(gt.getRegionProperties('US')); // { code: 'US', name: 'United States', emoji: '🇺🇸' }
+console.log(gt.getRegionProperties('GB')); // { code: 'GB', name: 'United Kingdom', emoji: '🇬🇧' }
+console.log(gt.getRegionProperties('DE')); // { code: 'DE', name: 'Germany', emoji: '🇩🇪' }
+console.log(gt.getRegionProperties('JP')); // { code: 'JP', name: 'Japan', emoji: '🇯🇵' }
+```
+
+---
+
+## Notes
+
+- Uses `Intl.DisplayNames` API for localized region names
+- Supports both ISO 3166-1 alpha-2 and UN M.49 region codes
+- Custom mappings override default names and emojis
+- Automatically detects region from target locale if no parameter provided
+- Falls back to region code as name if display name resolution fails
+
+## Next Steps
+
+- Get full locale properties with [`getLocaleProperties()`](/docs/core/class/methods/locales/getLocaleProperties)
+- Get locale emoji with [`getLocaleEmoji()`](/docs/core/class/methods/locales/getLocaleEmoji)
+- Explore standalone [`getRegionProperties()`](/docs/core/functions/locales/getRegionProperties)
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/core/class/methods/locales/isSameDialect.mdx b/apps/docs/content/docs/en/core/class/methods/locales/isSameDialect.mdx
new file mode 100644
index 000000000..8f568637e
--- /dev/null
+++ b/apps/docs/content/docs/en/core/class/methods/locales/isSameDialect.mdx
@@ -0,0 +1,110 @@
+---
+title: isSameDialect()
+description: API Reference for the GT isSameDialect method
+---
+
+## Overview
+
+The `isSameDialect()` method checks if multiple BCP-47 locale codes represent the same dialect.
+It compares the language and region components of locale codes to determine if they represent the same linguistic variety.
+
+---
+
+## Reference
+
+### Parameters
+
+<TypeTable
+  type={{
+    "...locales": {
+      type: '(string | string[])[]',
+      optional: false,
+    }
+  }}
+/>
+
+### Parameters Description
+
+| Parameter | Description |
+|-----------|-------------|
+| `...locales` | Variable number of locale codes (strings) or arrays of locale codes to compare. All provided locales must represent the same dialect |
+
+### Returns
+
+`boolean` - `true` if all provided locale codes represent the same dialect, `false` otherwise
+
+### Throws
+
+No exceptions are thrown. Invalid locale codes are handled gracefully and return `false`.
+
+---
+
+## Behavior
+
+### Dialect Comparison Logic
+
+The method uses the following logic to determine dialect equality:
+1. **Normalize locales** - Standardizes all input locale codes
+2. **Compare language codes** - All locales must have the same base language
+3. **Handle region hierarchy** - A base language matches its regional variants
+4. **Exact dialect matching** - Regional variants must match exactly
+
+### Hierarchy Rules
+
+- Base language (`'en'`) matches any regional variant (`'en-US'`, `'en-GB'`)
+- Regional variants match only exactly (`'en-US'` ≠ `'en-GB'`)
+- Script variants are considered in the comparison when present
+- Different languages never match (`'en'` ≠ `'es'`)
+
+### Input Flexibility
+
+The method accepts:
+- Multiple string parameters: `isSameDialect('en-US', 'en-GB')`
+- Arrays of strings: `isSameDialect(['en-US', 'en-GB'])`
+- Mixed format: `isSameDialect('en-US', ['en-GB', 'en-CA'])`
+- Single locale: `isSameDialect('en-US')` (always returns `true`)
+
+---
+
+## Examples
+
+### Basic Dialect Comparison
+
+```typescript
+const gt = new GT({
+  sourceLocale: 'en-US',
+  targetLocale: 'es-ES'
+});
+
+// Same exact dialects
+console.log(gt.isSameDialect('en-US', 'en-US')); // true
+console.log(gt.isSameDialect('zh-CN', 'zh-CN')); // true
+
+// Different dialects of same language
+console.log(gt.isSameDialect('en-US', 'en-GB')); // false
+console.log(gt.isSameDialect('es-ES', 'es-MX')); // false
+console.log(gt.isSameDialect('pt-PT', 'pt-BR')); // false
+
+// Base language with regional variants
+console.log(gt.isSameDialect('en', 'en-US')); // true
+console.log(gt.isSameDialect('es', 'es-ES')); // true
+console.log(gt.isSameDialect('zh', 'zh-CN')); // true
+
+// Different languages
+console.log(gt.isSameDialect('en-US', 'es-ES')); // false
+console.log(gt.isSameDialect('fr-FR', 'de-DE')); // false
+```
+
+---
+
+## Notes
+
+- Uses standardized locale codes for accurate comparison
+- Accepts flexible input formats (strings, arrays, mixed)
+
+## Next Steps
+
+- Compare languages with [`isSameLanguage()`](/docs/core/class/methods/locales/isSameLanguage)
+- Check locale hierarchy with [`isSupersetLocale()`](/docs/core/class/methods/locales/isSupersetLocale)
+- Validate locales with [`isValidLocale()`](/docs/core/class/methods/locales/isValidLocale)
+- Explore standalone [`isSameDialect()`](/docs/core/functions/locales/isSameDialect)
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/core/class/methods/locales/isSameLanguage.mdx b/apps/docs/content/docs/en/core/class/methods/locales/isSameLanguage.mdx
new file mode 100644
index 000000000..741e1780b
--- /dev/null
+++ b/apps/docs/content/docs/en/core/class/methods/locales/isSameLanguage.mdx
@@ -0,0 +1,67 @@
+---
+title: isSameLanguage()
+description: API Reference for the GT isSameLanguage method
+---
+
+## Overview
+
+The `isSameLanguage()` method checks if multiple BCP-47 locale codes represent the same base language, ignoring regional and script differences.
+This is useful for determining language compatibility and grouping content by language family.
+
+---
+
+## Reference
+
+### Parameters
+
+<TypeTable
+  type={{
+    "...locales": {
+      type: '(string | string[])[]',
+      optional: false,
+    }
+  }}
+/>
+
+### Returns
+
+`boolean` - `true` if all locale codes represent the same base language
+
+---
+
+## Examples
+
+```typescript
+const gt = new GT({
+  sourceLocale: 'en-US',
+  targetLocale: 'es-ES'
+});
+
+
+// Same language, different regions
+console.log(gt.isSameLanguage('en-US', 'en-GB')); // true
+console.log(gt.isSameLanguage('es-ES', 'es-MX')); // true
+console.log(gt.isSameLanguage('zh-CN', 'zh-TW')); // true
+
+// Different languages
+console.log(gt.isSameLanguage('en-US', 'es-ES')); // false
+console.log(gt.isSameLanguage('fr-FR', 'de-DE')); // false
+
+// Base language with variants
+console.log(gt.isSameLanguage('en', 'en-US', 'en-GB')); // true
+```
+
+---
+
+## Notes
+
+- Compares only the base language code (before first hyphen)
+- Ignores regional, script, and variant differences
+- Essential for language-based content organization
+- Works with variable number of locale parameters
+
+## Next Steps
+
+- **[Compare dialects with isSameDialect()](/docs/core/class/methods/locales/isSameDialect)**
+- **[Check locale hierarchy with isSupersetLocale()](/docs/core/class/methods/locales/isSupersetLocale)**
+- **[Explore standalone isSameLanguage()](/docs/core/functions/locales/isSameLanguage)**
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/core/class/methods/locales/isSupersetLocale.mdx b/apps/docs/content/docs/en/core/class/methods/locales/isSupersetLocale.mdx
new file mode 100644
index 000000000..f433e0276
--- /dev/null
+++ b/apps/docs/content/docs/en/core/class/methods/locales/isSupersetLocale.mdx
@@ -0,0 +1,70 @@
+---
+title: isSupersetLocale()
+description: API Reference for the GT isSupersetLocale method
+---
+
+## Overview
+
+The `isSupersetLocale()` method checks if one locale is a superset of another locale in the BCP-47 hierarchy.
+A superset locale is more general and can serve as a fallback for more specific locales.
+
+---
+
+## Reference
+
+### Parameters
+
+<TypeTable
+  type={{
+    "superLocale": {
+      type: 'string',
+      optional: false,
+    },
+    "subLocale": {
+      type: 'string',
+      optional: false,
+    }
+  }}
+/>
+
+### Returns
+
+`boolean` - `true` if superLocale is a superset of subLocale
+
+---
+
+## Examples
+
+```typescript
+const gt = new GT();
+
+// Base language is superset of regional variant
+console.log(gt.isSupersetLocale('en', 'en-US')); // true
+console.log(gt.isSupersetLocale('es', 'es-ES')); // true
+console.log(gt.isSupersetLocale('zh', 'zh-CN')); // true
+
+// Regional variant is NOT superset of base language
+console.log(gt.isSupersetLocale('en-US', 'en')); // false
+console.log(gt.isSupersetLocale('es-ES', 'es')); // false
+
+// Same locales
+console.log(gt.isSupersetLocale('en-US', 'en-US')); // true
+
+// Different languages
+console.log(gt.isSupersetLocale('en', 'es-ES')); // false
+```
+
+---
+
+## Notes
+
+- Uses BCP-47 locale hierarchy for comparison
+- A locale is always a superset of itself
+- Base languages are supersets of their regional variants
+- Returns false for completely different languages
+
+## Next Steps
+
+- Compare same languages with [`isSameLanguage()`](/docs/core/class/methods/locales/isSameLanguage)
+- Compare dialects with [`isSameDialect()`](/docs/core/class/methods/locales/isSameDialect)
+- Explore standalone [`isSupersetLocale()`](/docs/core/functions/locales/isSupersetLocale)
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/core/class/methods/locales/isValidLocale.mdx b/apps/docs/content/docs/en/core/class/methods/locales/isValidLocale.mdx
new file mode 100644
index 000000000..09a83c373
--- /dev/null
+++ b/apps/docs/content/docs/en/core/class/methods/locales/isValidLocale.mdx
@@ -0,0 +1,78 @@
+---
+title: isValidLocale()
+description: API Reference for the GT isValidLocale method
+---
+
+## Overview
+
+The `isValidLocale()` method validates whether a locale code is properly formatted and recognized as a valid BCP-47 locale.
+It checks locale structure, language recognition, and regional/script validity using the `Intl` APIs with support for custom locale mappings.
+
+---
+
+## Reference
+
+### Parameters
+
+<TypeTable
+  type={{
+    "locale?": {
+      type: 'string',
+      optional: true,
+      default: 'this.targetLocale',
+    },
+    "customMapping?": {
+      type: 'CustomMapping',
+      optional: true,
+      default: 'this.customMapping',
+    }
+  }}
+/>
+
+### Parameters Description
+
+| Parameter | Description |
+|-----------|-------------|
+| `locale` | BCP-47 locale code to validate. If not provided, uses the instance's `targetLocale` |
+| `customMapping` | Optional custom mapping to check for additional valid locales. If not provided, uses the instance's `customMapping` |
+
+### Returns
+
+`boolean` - `true` if the locale is valid, `false` otherwise
+
+### Throws
+
+- `Error` - If no locale is provided and the instance has no `targetLocale` configured
+
+---
+
+## Examples
+
+```typescript
+const gt = new GT({
+  sourceLocale: 'en',
+  targetLocale: 'es'
+});
+
+const isValid = gt.isValidLocale('en-US');
+console.log(isValid); // true
+
+const isInvalid = gt.isValidLocale('invalid-locale');
+console.log(isInvalid); // false
+```
+---
+
+## Notes
+
+- Performs comprehensive BCP-47 locale validation using browser Intl APIs
+- Custom mapping locales always validate as true (bypass standard validation)
+- Supports private-use language codes (qaa-qtz)
+- Returns `false` for malformed or unrecognized locale codes
+
+## Next Steps
+
+- **[Get locale properties with getLocaleProperties()](/docs/core/class/methods/locales/getLocaleProperties)**
+- **[Determine best locale with determineLocale()](/docs/core/class/methods/locales/determineLocale)**
+- **[Get locale names with getLocaleName()](/docs/core/class/methods/locales/getLocaleName)**
+- **[Learn about CustomMapping type](/docs/core/types/CustomMapping)**
+- **[Explore standalone isValidLocale()](/docs/core/functions/locales/isValidLocale)**
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/core/class/methods/locales/meta.json b/apps/docs/content/docs/en/core/class/methods/locales/meta.json
new file mode 100644
index 000000000..d9b18082a
--- /dev/null
+++ b/apps/docs/content/docs/en/core/class/methods/locales/meta.json
@@ -0,0 +1,19 @@
+{
+  "title": "Locales",
+  "pages": [
+    "./determineLocale",
+    "./getLocaleDirection",
+    "./getLocaleEmoji",
+    "./getLocaleName",
+    "./getLocaleProperties",
+    "./getRegionProperties",
+    "./isSameDialect",
+    "./isSameLanguage",
+    "./isSupersetLocale",
+    "./isValidLocale",
+    "./requiresTranslation",
+    "./resolveAliasLocale",
+    "./resolveCanonicalLocale",
+    "./standardizeLocale"
+  ]
+}
diff --git a/apps/docs/content/docs/en/core/class/methods/locales/requiresTranslation.mdx b/apps/docs/content/docs/en/core/class/methods/locales/requiresTranslation.mdx
new file mode 100644
index 000000000..fc0f4cfea
--- /dev/null
+++ b/apps/docs/content/docs/en/core/class/methods/locales/requiresTranslation.mdx
@@ -0,0 +1,99 @@
+---
+title: requiresTranslation()
+description: API Reference for the GT requiresTranslation method
+---
+
+## Overview
+
+The `requiresTranslation()` method determines whether translation is needed based on source and target locales.
+It checks if the source content needs to be translated by comparing locale codes and considering approved locale list.
+
+---
+
+## Reference
+
+### Parameters
+
+<TypeTable
+  type={{
+    "sourceLocale?": {
+      type: 'string',
+      optional: true,
+      default: 'this.sourceLocale'
+    },
+    "targetLocale?": {
+      type: 'string', 
+      optional: true,
+      default: 'this.targetLocale'
+    },
+    "approvedLocales?": {
+      type: 'string[]',
+      optional: true,
+      default: 'this.locales'
+    },
+    "customMapping?": {
+      type: 'CustomMapping',
+      optional: true,
+      default: 'this.customMapping'
+    }
+  }}
+/>
+
+### Parameters Description
+
+| Parameter | Description |
+|-----------|-------------|
+| `sourceLocale` | The source locale code. If not provided, uses the instance's `sourceLocale` |
+| `targetLocale` | The target locale code. If not provided, uses the instance's `targetLocale` |
+| `approvedLocales` | Array of approved target locales. If not provided, uses the instance's `locales` array |
+| `customMapping` | Optional custom mapping for locale resolution |
+
+### Returns
+
+`boolean` - `true` if translation is required, `false` otherwise
+
+### Throws
+
+- `Error` - If no source locale is provided and the instance has no `sourceLocale` configured
+- `Error` - If no target locale is provided and the instance has no `targetLocale` configured
+
+---
+
+## Examples
+
+```typescript
+const gt = new GT({
+  sourceLocale: 'en-US',
+  targetLocale: 'es-ES',
+  locales: ['en-US', 'es-ES', 'fr-FR', 'de-DE']
+});
+
+// Different languages require translation
+console.log(gt.requiresTranslation('en-US', 'es-ES')); // true
+console.log(gt.requiresTranslation('en-US', 'fr-FR')); // true
+
+// Same languages don't require translation
+console.log(gt.requiresTranslation('en-US', 'en-US')); // false
+console.log(gt.requiresTranslation('es-ES', 'es-ES')); // false
+
+// Different dialects of same language don't require translation
+console.log(gt.requiresTranslation('en-US', 'en-GB')); // false
+console.log(gt.requiresTranslation('es-ES', 'es-MX')); // false
+
+// Target not in approved locales
+console.log(gt.requiresTranslation('en-US', 'it-IT')); // false (it-IT not in approved locales)
+```
+---
+
+## Notes
+
+- Considers locale language families, not just exact matches
+- Respects approved locale lists
+- Returns `false` when target locale is not in approved locales (if provided)
+
+## Next Steps
+
+- Check locale relationships with [`isSameLanguage()`](/docs/core/class/methods/locales/isSameLanguage)
+- Determine best locale with [`determineLocale()`](/docs/core/class/methods/locales/determineLocale)
+- Validate locales with [`isValidLocale()`](/docs/core/class/methods/locales/isValidLocale)
+- Explore standalone [`requiresTranslation()`](/docs/core/functions/locales/requiresTranslation)
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/core/class/methods/locales/resolveAliasLocale.mdx b/apps/docs/content/docs/en/core/class/methods/locales/resolveAliasLocale.mdx
new file mode 100644
index 000000000..3e5581fdf
--- /dev/null
+++ b/apps/docs/content/docs/en/core/class/methods/locales/resolveAliasLocale.mdx
@@ -0,0 +1,79 @@
+---
+title: resolveAliasLocale()
+description: API Reference for the GT resolveAliasLocale method
+---
+
+## Overview
+
+The `resolveAliasLocale()` method resolves a canonical locale code back to its original alias locale code when custom mapping is configured.
+This is the inverse operation of `resolveCanonicalLocale()`.
+
+---
+
+## Reference
+
+### Parameters
+
+<TypeTable
+  type={{
+    "locale": {
+      type: 'string',
+      optional: false,
+    },
+    "customMapping?": {
+      type: 'CustomMapping',
+      optional: true,
+      default: 'this.customMapping'
+    }
+  }}
+/>
+
+### Parameters Description
+
+| Parameter | Description |
+|-----------|-------------|
+| `locale` | The canonical locale code to resolve back to its alias |
+| `customMapping` | Optional custom mapping to use instead of the instance's mapping |
+
+### Returns
+
+`string` - The alias locale code if a mapping exists, otherwise the original locale code
+
+### Throws
+
+- `Error` - If no locale is provided and no target locale is configured
+
+---
+
+
+## Examples
+
+```typescript
+const gt = new GT({
+  sourceLocale: 'en',
+  customMapping: {
+    'cn': { code: 'zh', name: 'Mandarin' },
+  }
+});
+
+// Resolve canonical locale back to alias
+const alias = gt.resolveAliasLocale('zh');
+console.log(alias); // "cn"
+
+// Non-mapped locale returns the original
+const unchanged = gt.resolveAliasLocale('es');
+console.log(unchanged); // "es"
+```
+---
+
+## Notes
+
+- Returns the original alias locale code when a custom mapping exists
+- Returns the input locale unchanged if no mapping is found
+
+## Next Steps
+
+- Resolve canonical locales with [`resolveCanonicalLocale()`](/docs/core/class/methods/locales/resolveCanonicalLocale)
+- Validate locales with [`isValidLocale()`](/docs/core/class/methods/locales/isValidLocale)
+- Get locale properties with [`getLocaleProperties()`](/docs/core/class/methods/locales/getLocaleProperties)
+- Explore standalone [`resolveAliasLocale()`](/docs/core/functions/locales/resolveAliasLocale)
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/core/class/methods/locales/resolveCanonicalLocale.mdx b/apps/docs/content/docs/en/core/class/methods/locales/resolveCanonicalLocale.mdx
new file mode 100644
index 000000000..ec2436120
--- /dev/null
+++ b/apps/docs/content/docs/en/core/class/methods/locales/resolveCanonicalLocale.mdx
@@ -0,0 +1,81 @@
+---
+title: resolveCanonicalLocale()
+description: API Reference for the GT resolveCanonicalLocale method
+---
+
+## Overview
+
+Used in the context of aliasing locales (e.g. `cn` -> `zh`), the `resolveCanonicalLocale()` method converts alias locale codes to their canonical BCP-47 locale codes when custom mapping is configured.
+
+---
+
+## Reference
+
+### Parameters
+
+<TypeTable
+  type={{
+    "locale?": {
+      type: 'string',
+      optional: true,
+      default: 'this.targetLocale'
+    },
+    "customMapping?": {
+      type: 'CustomMapping',
+      optional: true,
+      default: 'this.customMapping'
+    }
+  }}
+/>
+
+### Parameters Description
+
+| Parameter | Description |
+|-----------|-------------|
+| `locale` | The alias locale code to resolve to canonical form. If not provided, uses the instance's `targetLocale` |
+| `customMapping` | Optional custom mapping to use instead of the instance's mapping |
+
+### Returns
+
+`string` - The canonical BCP-47 locale code if a mapping exists, otherwise the original locale code
+
+### Throws
+
+- `Error` - If no locale is provided and the instance has no `targetLocale` configured
+
+---
+
+## Examples
+
+```typescript
+const gt = new GT({
+  sourceLocale: 'en',
+  customMapping: {
+    'cn': { code: 'zh', name: 'Mandarin' },
+  }
+});
+
+// Convert alias to canonical locale
+const canonical = gt.resolveCanonicalLocale('cn');
+console.log(canonical); // "zh"
+
+// Regular BCP-47 codes pass through unchanged
+const unchanged = gt.resolveCanonicalLocale('fr-FR');
+console.log(unchanged); // "fr-FR"
+```
+
+---
+
+## Notes
+
+- Converts alias locale codes to canonical BCP-47 locale codes
+- Returns original locale if no custom mapping exists
+- Works with the `customMapping` configuration from the GT constructor
+- No validation is performed on the input or output locale codes
+
+## Next Steps
+
+- Resolve back to aliases with [`resolveAliasLocale()`](/docs/core/class/methods/locales/resolveAliasLocale)
+- Validate locales with [`isValidLocale()`](/docs/core/class/methods/locales/isValidLocale)
+- Standardize locale format with [`standardizeLocale()`](/docs/core/class/methods/locales/standardizeLocale)
+- Get locale properties with [`getLocaleProperties()`](/docs/core/class/methods/locales/getLocaleProperties)
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/core/class/methods/locales/standardizeLocale.mdx b/apps/docs/content/docs/en/core/class/methods/locales/standardizeLocale.mdx
new file mode 100644
index 000000000..666c9c91d
--- /dev/null
+++ b/apps/docs/content/docs/en/core/class/methods/locales/standardizeLocale.mdx
@@ -0,0 +1,87 @@
+---
+title: standardizeLocale()
+description: API Reference for the GT standardizeLocale method
+---
+
+## Overview
+
+The `standardizeLocale()` method standardizes a BCP-47 locale code to ensure correct formatting and casing.
+It converts locale codes to their proper canonical format, making them suitable for use with internationalization APIs and ensuring consistency across your application.
+
+---
+
+## Reference
+
+### Parameters
+
+<TypeTable
+  type={{
+    "locale?": {
+      type: 'string',
+      optional: true,
+      default: 'this.targetLocale'
+    }
+  }}
+/>
+
+### Parameters Description
+
+| Parameter | Description |
+|-----------|-------------|
+| `locale` | The BCP-47 locale code to standardize. If not provided, uses the instance's `targetLocale` |
+
+### Returns
+
+`string` - The standardized BCP-47 locale code, or empty string if the input is invalid
+
+### Throws
+
+- `Error` - If no locale is provided and the instance has no `targetLocale` configured
+
+---
+
+## Behavior
+
+Common format corrections applied:
+- `en_US` → `en-US` (underscore to hyphen)
+- `zh_cn` → `zh-CN` (underscore to hyphen, casing)
+- `EN-gb` → `en-GB` (language lowercase, region uppercase)
+- `Fr-ca` → `fr-CA` (proper casing throughout)
+- `ja_jp` → `ja-JP` (underscore and casing)
+
+---
+
+## Examples
+
+```typescript
+const gt = new GT({
+  sourceLocale: 'en',
+  targetLocale: 'es-ES'
+});
+
+// Standardize various locale formats
+console.log(gt.standardizeLocale('en_us')); // "en-US"
+console.log(gt.standardizeLocale('zh_cn')); // "zh-CN"
+console.log(gt.standardizeLocale('EN-gb')); // "en-GB"
+console.log(gt.standardizeLocale('fr-ca')); // "fr-CA"
+
+// Already standardized locales pass through unchanged
+console.log(gt.standardizeLocale('es-ES')); // "es-ES"
+console.log(gt.standardizeLocale('ja-JP')); // "ja-JP"
+```
+
+---
+
+## Notes
+
+- Converts underscores to hyphens and normalizes casing
+- Returns empty string for invalid locale codes
+- Language codes become lowercase, region codes become uppercase
+- Preserves locale extensions and variants when present
+
+## Next Steps
+
+- Validate standardized locales with [`isValidLocale()`](/docs/core/class/methods/locales/isValidLocale)
+- Resolve canonical locales with [`resolveCanonicalLocale()`](/docs/core/class/methods/locales/resolveCanonicalLocale)
+- Get locale properties with [`getLocaleProperties()`](/docs/core/class/methods/locales/getLocaleProperties)
+- Explore standalone [`standardizeLocale()`](/docs/core/functions/locales/standardizeLocale)
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/core/class/methods/meta.json b/apps/docs/content/docs/en/core/class/methods/meta.json
new file mode 100644
index 000000000..31807dcfa
--- /dev/null
+++ b/apps/docs/content/docs/en/core/class/methods/meta.json
@@ -0,0 +1,8 @@
+{
+  "title": "Methods",
+  "pages": [
+    "./translation",
+    "./formatting",
+    "./locales"
+  ]
+}
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/core/class/methods/translation/checkFileTranslations.mdx b/apps/docs/content/docs/en/core/class/methods/translation/checkFileTranslations.mdx
new file mode 100644
index 000000000..889a416e8
--- /dev/null
+++ b/apps/docs/content/docs/en/core/class/methods/translation/checkFileTranslations.mdx
@@ -0,0 +1,145 @@
+---
+title: checkFileTranslations()
+description: API Reference for the checkFileTranslations() method to check translation status without downloading files
+---
+
+## Overview
+
+The `checkFileTranslations()` method checks the translation status of files without downloading their content.
+This is useful for monitoring translation progress, checking completion status, and determining which translations are available.
+
+```typescript
+const gt = new GT({ projectId: 'your-project-id', apiKey: 'your-api-key' });
+
+const status = await gt.checkFileTranslations([
+  {
+    versionId: 'version-123',
+    fileName: 'app.json',
+    locale: 'es'
+  }
+]);
+```
+
+## Reference
+
+### Parameters
+
+| Name | Type | Description |
+|------|------|-------------|
+| `data` | `FileTranslationQuery[]` | Array of file translation queries to check |
+| `options?` | `CheckFileTranslationsOptions` | Optional configuration for the request |
+
+#### FileTranslationQuery
+
+| Name | Type | Description |
+|------|------|-------------|
+| `versionId` | `string` | Version ID of the file to check |
+| `fileName?` | `string` | File name identifier (required if `fileId` not provided) |
+| `fileId?` | `string` | File ID identifier (required if `fileName` not provided) |
+| `locale` | `string` | Target locale to check translation status for |
+
+#### CheckFileTranslationsOptions
+
+| Name | Type | Description |
+|------|------|-------------|
+| `timeout?` | `number` | Request timeout in milliseconds |
+
+### Returns
+
+`Promise<CheckFileTranslationsResult>` - Contains translation status information.
+
+```typescript
+type CheckFileTranslationsResult = {
+  translations: CompletedFileTranslationData[];
+}
+```
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `translations` | `CompletedFileTranslationData[]` | Array of translation status data |
+
+#### CompletedFileTranslationData Structure
+
+```typescript
+type CompletedFileTranslationData = {
+  id: string;
+  fileId: string;
+  versionId: string;
+  fileName: string;
+  locale: string;
+  status: 'completed' | 'pending' | 'failed';
+  completedAt: string | null;
+  approvedAt: string | null;
+  publishedAt: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+```
+
+---
+
+## Examples
+
+### Basic Usage
+
+Check translation status for specific files and locales:
+
+```typescript title="index.ts" copy
+// (1) Create a GT instance
+const targetLocales = ['es', 'fr', 'de'];
+const gt = new GT({
+  projectId: 'your-project-id',
+  apiKey: 'your-api-key',
+});
+
+// (2) Upload the file
+const fileUpload = {
+  content: fileContents,
+  fileName: filePath,
+  fileFormat: 'JSON',
+  locale: 'en',
+};
+const files = [ { source: fileUpload } ];
+const { uploadedFiles } = await gt.uploadSourceFiles(
+  files,
+  { sourceLocale: 'en' }
+);
+
+// (3) Enqueue the file translation job
+const enqueueResult = await gt.enqueueFiles(
+  uploadedFiles,
+  {
+  sourceLocale: 'en',
+  targetLocales: targetLocales,
+});
+
+// (4) Wait for all translations to be completed
+let translationIds = [];
+const statusQuery = Object.values(enqueueResult.data).flatMap(({fileName, versionId}) => {
+  return targetLocales.map((locale) => ({locale, fileName, versionId}));
+});
+while (true) {
+  const status = await gt.checkFileTranslations(statusQuery);
+  if (status.translations.length === statusQuery.length) {
+    translationIds = status.translations.map(translation => translation.id);
+    break;
+  }
+  await new Promise(resolve => setTimeout(resolve, 1000));
+}
+```
+
+---
+
+## Notes
+
+* Translation status includes `pending`, `completed`, and `failed` states
+* Completed translations may still require approval before being published
+* Use this method for efficient status checking when monitoring multiple translation jobs
+
+## Next Steps
+
+* Check out the [Quickstart](/docs/core/quickstart#translate-your-first-file) for a complete example of how to use this method
+* See [`downloadTranslatedFile()`](/docs/core/class/methods/translation/downloadTranslatedFile) to download completed translations
+* See [`enqueueFiles()`](/docs/core/class/methods/translation/enqueueFiles) to create translation jobs
+* See [`querySourceFile()`](/docs/core/class/methods/translation/querySourceFile) to get source file and translation information
+* See [`CompletedFileTranslationData`](/docs/core/types/CompletedFileTranslationData) for detailed status data structure
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/core/class/methods/translation/checkSetupStatus.mdx b/apps/docs/content/docs/en/core/class/methods/translation/checkSetupStatus.mdx
new file mode 100644
index 000000000..f7a651446
--- /dev/null
+++ b/apps/docs/content/docs/en/core/class/methods/translation/checkSetupStatus.mdx
@@ -0,0 +1,126 @@
+---
+title: checkSetupStatus()
+description: API Reference for the checkSetupStatus() method to monitor project setup job progress
+---
+
+## Overview
+
+The `checkSetupStatus()` method checks the current status of a project setup job using its unique identifier.
+This method is used to monitor the progress of asynchronous setup operations initiated by [`setupProject()`](/docs/core/class/methods/translation/setupProject).
+Set up handles tasks like corpus analysis, context generation, glossary generation, etc.
+
+Set up automatically runs when elements of context are missing.
+This typically means that when you run translate for the first time, you will see a setup job running.
+
+```typescript
+const gt = new GT({ projectId: 'your-project-id', apiKey: 'your-api-key' });
+
+const status = await gt.checkSetupStatus('setup-job-123');
+console.log(`Setup status: ${status.status}`);
+```
+
+<Callout>
+  To check the status of a setup job, you must first called both [`uploadSourceFiles()`](/docs/core/class/methods/translation/uploadSourceFiles) and [`setupProject()`](/docs/core/class/methods/translation/setupProject).
+</Callout>
+
+## Reference
+
+### Parameters
+
+| Name | Type | Description |
+|------|------|-------------|
+| `jobId` | `string` | The unique identifier of the setup job to check |
+| `timeoutMs?` | `number` | Optional timeout in milliseconds for the API request |
+
+### Returns
+
+`Promise<CheckSetupStatusResult>` - Contains the current job status and related information.
+
+```typescript
+type CheckSetupStatusResult = {
+  jobId: string;
+  status: SetupJobStatus;
+  error?: { message: string };
+}
+```
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `jobId` | `string` | The setup job identifier that was checked |
+| `status` | `SetupJobStatus` | Current status of the setup job |
+| `error?` | `{ message: string }` | Error information if status is `'failed'` |
+
+#### SetupJobStatus
+
+```typescript
+type SetupJobStatus = 'queued' | 'processing' | 'completed' | 'failed';
+```
+
+- `'queued'` - Job is waiting to be processed
+- `'processing'` - Job is currently being executed
+- `'completed'` - Job finished successfully
+- `'failed'` - Job encountered an error and failed
+
+---
+
+## Example
+
+### Basic Status Checking
+
+```typescript copy
+import { GT } from 'generaltranslation';
+
+const gt = new GT({
+  projectId: 'your-project-id',
+  apiKey: 'your-api-key'
+});
+
+
+const fileRefs = [
+  {
+    fileId: 'file-123',
+    versionId: 'version-456',
+    fileName: 'app.json',
+    fileFormat: 'JSON'
+  },
+  {
+    fileId: 'file-789',
+    versionId: 'version-012',
+    fileName: 'content.md',
+    fileFormat: 'MD'
+  }
+];
+
+const setupResult = await gt.setupProject(fileRefs);
+
+async function checkJobStatus(jobId: string) {
+  const status = await gt.checkSetupStatus(jobId);
+  
+  console.log(`Job ${jobId}:`);
+  console.log(`  Status: ${status.status}`);
+  
+  if (status.error) {
+    console.log(`  Error: ${status.error.message}`);
+  }
+  
+  return status;
+}
+
+const jobStatus = await checkJobStatus(setupResult.setupJobId);
+```
+
+---
+
+## Notes
+
+* Set up automatically runs when elements of context are missing.
+* Set up is responsible for corpus analysis, context generation, glossary generation, etc.
+* Job IDs are returned by [`setupProject()`](/docs/core/class/methods/translation/setupProject) and should be stored for status checking
+
+## Next Steps
+
+* See [`setupProject()`](/docs/core/class/methods/translation/setupProject) to initiate setup jobs
+* See [`shouldSetupProject()`](/docs/core/class/methods/translation/shouldSetupProject) to check if setup is required
+* See [`enqueueFiles()`](/docs/core/class/methods/translation/enqueueFiles) to proceed after setup completion
+* See [`getProjectData()`](/docs/core/class/methods/translation/getProjectData) for project information
+* See [`CheckSetupStatusResult`](/docs/core/types/CheckSetupStatusResult) for detailed result type information
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/core/class/methods/translation/downloadFileBatch.mdx b/apps/docs/content/docs/en/core/class/methods/translation/downloadFileBatch.mdx
new file mode 100644
index 000000000..3b5f63af9
--- /dev/null
+++ b/apps/docs/content/docs/en/core/class/methods/translation/downloadFileBatch.mdx
@@ -0,0 +1,140 @@
+---
+title: downloadFileBatch()
+description: API Reference for the downloadFileBatch() method to download multiple translation files in a single request
+---
+
+## Overview
+
+The `downloadFileBatch()` method downloads multiple translation files in a single batch request.
+
+```typescript
+const gt = new GT({ projectId: 'your-project-id', apiKey: 'your-api-key' });
+
+const result = await gt.downloadFileBatch([
+  'translation-id-1', 
+  'translation-id-2', 
+  'translation-id-3'
+]);
+```
+
+<Callout>
+**Batch Efficiency:**
+This method is optimized for downloading multiple files in a single API call, reducing network overhead and improving performance compared to multiple individual `downloadTranslatedFile()` calls.
+</Callout>
+
+## Reference
+
+### Parameters
+
+| Name | Type | Description |
+|------|------|-------------|
+| `fileIds` | `string[]` | Array of translation file IDs to download |
+| `options?` | `DownloadFileBatchOptions` | Optional configuration for the download request |
+
+#### DownloadFileBatchOptions
+
+| Name | Type | Description |
+|------|------|-------------|
+| `timeout?` | `number` | Request timeout in milliseconds |
+
+### Returns
+
+`Promise<DownloadFileBatchResult>` - Contains the downloaded files and metadata.
+
+```typescript
+type DownloadFileBatchResult = {
+  files: File[];
+  count: number;
+}
+```
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `files` | `File[]` | Array of downloaded file objects |
+| `count` | `number` | Number of files successfully downloaded |
+
+#### File Structure
+
+```typescript
+type File = {
+  id: string;
+  fileName: string;
+  data: string;
+  metadata: any;
+}
+```
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `id` | `string` | Translation file ID |
+| `fileName` | `string` | Original file name |
+| `data` | `string` | File content as UTF-8 string (decoded from Base64) |
+| `metadata` | `any` | Additional file metadata |
+
+---
+
+## Examples
+
+
+```typescript title="index.ts" copy
+// (1) Create a GT instance
+const targetLocales = ['es', 'fr', 'de'];
+const gt = new GT({
+  projectId: 'your-project-id',
+  apiKey: 'your-api-key',
+});
+
+// (2) Upload the file
+const fileUpload = {
+  content: fileContents,
+  fileName: filePath,
+  fileFormat: 'JSON',
+  locale: 'en',
+};
+const files = [ { source: fileUpload } ];
+const { uploadedFiles } = await gt.uploadSourceFiles(
+  files,
+  { sourceLocale: 'en' }
+);
+
+// (3) Enqueue the file translation job
+const enqueueResult = await gt.enqueueFiles(
+  uploadedFiles,
+  {
+  sourceLocale: 'en',
+  targetLocales: targetLocales,
+});
+
+// (4) Wait for all translations to be completed
+let translationIds = [];
+const statusQuery = Object.values(enqueueResult.data).flatMap(({fileName, versionId}) => {
+  return targetLocales.map((locale) => ({locale, fileName, versionId}));
+});
+while (true) {
+  const status = await gt.checkFileTranslations(statusQuery);
+  if (status.translations.length === statusQuery.length) {
+    translationIds = status.translations.map(translation => translation.id);
+    break;
+  }
+  await new Promise(resolve => setTimeout(resolve, 1000));
+}
+
+// (5) Download the file
+const result = await gt.downloadFileBatch(translationIds);
+```
+
+---
+
+## Notes
+
+* File IDs must be valid translation IDs - use [`checkFileTranslations()`](/docs/core/class/methods/translation/checkFileTranslations) to verify completion first
+* Files are returned in the same order as the requested IDs when possible
+* Failed individual file downloads within the batch don't cause the entire batch to fail
+
+## Next Steps
+
+* See [`downloadTranslatedFile()`](/docs/core/class/methods/translation/downloadTranslatedFile) for single file downloads
+* See [`checkFileTranslations()`](/docs/core/class/methods/translation/checkFileTranslations) to verify files are ready for download
+* See [`enqueueFiles()`](/docs/core/class/methods/translation/enqueueFiles) to start translation jobs
+* See [`fetchTranslations()`](/docs/core/class/methods/translation/fetchTranslations) to get translation metadata
+* See [`DownloadFileBatchResult`](/docs/core/types/DownloadFileBatchResult) for detailed result structure
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/core/class/methods/translation/downloadTranslatedFile.mdx b/apps/docs/content/docs/en/core/class/methods/translation/downloadTranslatedFile.mdx
new file mode 100644
index 000000000..94cd9bbd5
--- /dev/null
+++ b/apps/docs/content/docs/en/core/class/methods/translation/downloadTranslatedFile.mdx
@@ -0,0 +1,125 @@
+---
+title: downloadTranslatedFile()
+description: API Reference for the downloadTranslatedFile() method to download completed translation files
+---
+
+## Overview
+
+The `downloadTranslatedFile()` method downloads the content of a single translated file as a UTF-8 string.
+This method is used to retrieve completed translations after they have been processed by the General Translation platform.
+
+```typescript
+const gt = new GT({ projectId: 'your-project-id', apiKey: 'your-api-key' });
+
+const content = await gt.downloadTranslatedFile({
+  fileId: 'file-123',
+  locale: 'es',
+  versionId: 'version-456'
+});
+```
+
+<Callout>
+  **Translation Status:**
+  This method only works with completed translations.
+  Use [`checkFileTranslations()`](/docs/core/class/methods/translation/checkFileTranslations) first to verify that translations are completed before attempting to download.
+</Callout>
+
+## Reference
+
+### Parameters
+
+| Name | Type | Description |
+|------|------|-------------|
+| `file` | `FileInfo` | File information object specifying which file to download |
+| `options?` | `DownloadFileOptions` | Optional configuration for the download request |
+
+#### FileInfo Structure
+
+| Name | Type | Description |
+|------|------|-------------|
+| `fileId` | `string` | Unique identifier of the file to download |
+| `locale` | `string` | Target locale of the translation to download |
+| `versionId?` | `string` | Optional version ID for the file |
+
+#### DownloadFileOptions
+
+| Name | Type | Description |
+|------|------|-------------|
+| `timeout?` | `number` | Request timeout in milliseconds |
+
+### Returns
+
+`Promise<string>` - The translated file content as a UTF-8 string.
+
+The returned string contains the translated file content in the same format as the original source file, with all translatable text converted to the target locale.
+
+---
+
+## Example
+
+```typescript title="index.ts" copy
+// (1) Create a GT instance
+const targetLocales = ['es', 'fr', 'de'];
+const gt = new GT({
+  projectId: 'your-project-id',
+  apiKey: 'your-api-key',
+});
+
+// (2) Upload the file
+const fileUpload = {
+  content: fileContents,
+  fileName: filePath,
+  fileFormat: 'JSON',
+  locale: 'en',
+};
+const files = [ { source: fileUpload } ];
+const { uploadedFiles } = await gt.uploadSourceFiles(
+  files,
+  { sourceLocale: 'en' }
+);
+
+// (3) Enqueue the file translation job
+const enqueueResult = await gt.enqueueFiles(
+  uploadedFiles,
+  {
+  sourceLocale: 'en',
+  targetLocales: targetLocales,
+});
+
+// (4) Wait for all translations to be completed
+let translationIds = [];
+const statusQuery = Object.values(enqueueResult.data).flatMap(({fileName, versionId}) => {
+  return targetLocales.map((locale) => ({locale, fileName, versionId}));
+});
+while (true) {
+  const status = await gt.checkFileTranslations(statusQuery);
+  if (status.translations.length === statusQuery.length) {
+    translationIds = status.translations.map(translation => translation.id);
+    break;
+  }
+  await new Promise(resolve => setTimeout(resolve, 1000));
+}
+
+// (5) Download the file
+const result = await Promise.all(
+  translationIds.map(id => gt.downloadTranslatedFile(id))
+);
+
+```
+
+
+---
+
+## Notes
+
+* Retrieves downloaded file as a UTF-8 string
+* The file must have a completed translation for the specified locale
+* Will fail if file is not found
+
+## Next Steps
+
+* See [`checkFileTranslations()`](/docs/core/class/methods/translation/checkFileTranslations) to verify translation status before downloading
+* See [`downloadFileBatch()`](/docs/core/class/methods/translation/downloadFileBatch) to download multiple files efficiently
+* See [`uploadSourceFiles()`](/docs/core/class/methods/translation/uploadSourceFiles) for the file upload process
+* See [`enqueueFiles()`](/docs/core/class/methods/translation/enqueueFiles) to start translation jobs
+* See [`FileUploadRef`](/docs/core/types/FileUploadRef) for file reference structure details
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/core/class/methods/translation/enqueueFiles.mdx b/apps/docs/content/docs/en/core/class/methods/translation/enqueueFiles.mdx
new file mode 100644
index 000000000..2fc89e625
--- /dev/null
+++ b/apps/docs/content/docs/en/core/class/methods/translation/enqueueFiles.mdx
@@ -0,0 +1,128 @@
+---
+title: enqueueFiles()
+description: API Reference for the enqueueFiles() method to enqueue file translation jobs
+---
+
+## Overview
+
+The `enqueueFiles()` method enqueues translation jobs for previously uploaded files in the General Translation API.
+This method takes file references and creates translation jobs for the specified target locales.
+
+```typescript
+const gt = new GT({ projectId: 'your-project-id', apiKey: 'your-api-key' });
+
+const result = await gt.enqueueFiles(fileRefs, {
+  sourceLocale: 'en',
+  targetLocales: ['es', 'fr', 'de']
+});
+```
+
+<Callout type="info">
+  You can only enqueue files for translation after they have been uploaded.
+</Callout>
+
+## Reference
+
+### Parameters
+
+| Name | Type | Description |
+|------|------|-------------|
+| `files` | `FileUploadRef[]` | Array of file references from previously uploaded files |
+| `options` | `EnqueueOptions` | Configuration options for the translation job |
+
+#### EnqueueOptions
+
+| Name | Type | Description |
+|------|------|-------------|
+| `sourceLocale?` | `string` | Source locale for translation (defaults to instance sourceLocale) |
+| `targetLocales?` | `string[]` | Array of target locales for translation (defaults to instance targetLocale) |
+| `publish?` | `boolean` | Whether to automatically publish translations when complete |
+| `requireApproval?` | `boolean` | Whether translations require approval before publishing |
+| `modelProvider?` | `string` | Specific AI model provider to use for translation |
+| `force?` | `boolean` | Force retranslation even if translations already exist |
+| `timeout?` | `number` | Request timeout in milliseconds |
+
+### Returns
+
+`Promise<EnqueueFilesResult>` - Contains job information and processing details.
+
+```typescript
+type EnqueueFilesResult = {
+  translations: CompletedFileTranslationData[];
+  data: Record<string, { fileName: string; versionId: string }>;
+  locales: string[];
+  message: string;
+}
+```
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `translations` | `CompletedFileTranslationData[]` | Array of translation job data |
+| `data` | `Record<string, { fileName: string; versionId: string }>` | Map of file identifiers to file metadata |
+| `locales` | `string[]` | List of target locales for the translation jobs |
+| `message` | `string` | Status message from the API |
+
+---
+
+## Example
+
+```typescript title="index.ts" copy
+// (1) Create a GT instance
+const targetLocales = ['es', 'fr', 'de'];
+const gt = new GT({
+  projectId: 'your-project-id',
+  apiKey: 'your-api-key',
+});
+
+// (2) Upload the file
+const fileUpload = {
+  content: fileContents,
+  fileName: filePath,
+  fileFormat: 'JSON',
+  locale: 'en',
+};
+const files = [ { source: fileUpload } ];
+const { uploadedFiles } = await gt.uploadSourceFiles(
+  files,
+  { sourceLocale: 'en' }
+);
+
+// (3) Enqueue the file translation job
+const enqueueResult = await gt.enqueueFiles(
+  uploadedFiles,
+  {
+  sourceLocale: 'en',
+  targetLocales: targetLocales,
+});
+
+// (4) Wait for all translations to be completed
+let translationIds = [];
+const statusQuery = Object.values(enqueueResult.data).flatMap(({fileName, versionId}) => {
+  return targetLocales.map((locale) => ({locale, fileName, versionId}));
+});
+while (true) {
+  const status = await gt.checkFileTranslations(statusQuery);
+  if (status.translations.length === statusQuery.length) {
+    translationIds = status.translations.map(translation => translation.id);
+    break;
+  }
+  await new Promise(resolve => setTimeout(resolve, 1000));
+}
+
+// (5) Download the file
+const result = await gt.downloadFileBatch(translationIds);
+```
+
+---
+
+## Notes
+
+* File content must be uploaded first using [`uploadSourceFiles()`](/docs/core/class/methods/translation/uploadSourceFiles)
+* Translation jobs are asynchronous - use [`checkFileTranslations()`](/docs/core/class/methods/translation/checkFileTranslations) to monitor progress
+
+## Next Steps
+
+* See [`uploadSourceFiles()`](/docs/core/class/methods/translation/uploadSourceFiles) to upload files before enqueueing
+* See [`checkFileTranslations()`](/docs/core/class/methods/translation/checkFileTranslations) to monitor translation progress
+* See [`downloadTranslatedFile()`](/docs/core/class/methods/translation/downloadTranslatedFile) to retrieve completed translations
+* See [`FileUploadRef`](/docs/core/types/FileUploadRef) for file reference structure details
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/core/class/methods/translation/getProjectData.mdx b/apps/docs/content/docs/en/core/class/methods/translation/getProjectData.mdx
new file mode 100644
index 000000000..8c96fd586
--- /dev/null
+++ b/apps/docs/content/docs/en/core/class/methods/translation/getProjectData.mdx
@@ -0,0 +1,109 @@
+---
+title: getProjectData()
+description: API Reference for the getProjectData() method to retrieve project information and configuration
+---
+
+## Overview
+
+The `getProjectData()` method retrieves comprehensive information about a translation project including its name, organization, default locale, and currently configured target locales.
+This method is useful for understanding project configuration and validating project settings.
+
+```typescript
+const gt = new GT({ projectId: 'your-project-id', apiKey: 'your-api-key' });
+
+const projectData = await gt.getProjectData('project-123');
+console.log(`Project: ${projectData.name}`);
+console.log(`Default locale: ${projectData.defaultLocale}`);
+console.log(`Target locales: ${projectData.currentLocales.join(', ')}`);
+```
+
+
+## Reference
+
+### Parameters
+
+| Name | Type | Description |
+|------|------|-------------|
+| `projectId` | `string` | The unique identifier of the project to retrieve |
+| `options?` | `{ timeout?: number }` | Optional configuration for the request |
+
+#### Options
+
+| Name | Type | Description |
+|------|------|-------------|
+| `timeout?` | `number` | Request timeout in milliseconds |
+
+### Returns
+
+`Promise<ProjectData>` - Contains project information and configuration.
+
+```typescript
+type ProjectData = {
+  id: string;
+  name: string;
+  orgId: string;
+  defaultLocale: string;
+  currentLocales: string[];
+}
+```
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `id` | `string` | Unique project identifier |
+| `name` | `string` | Human-readable project name |
+| `orgId` | `string` | Organization identifier that owns the project |
+| `defaultLocale` | `string` | Default source locale for the project |
+| `currentLocales` | `string[]` | Array of target locales currently configured |
+
+---
+
+## Examples
+
+### Basic Usagex
+
+```typescript title="index.ts" copy
+import { GT } from 'generaltranslation';
+
+const gt = new GT({
+  projectId: 'your-project-id',
+  apiKey: 'your-api-key'
+});
+
+async function getProjectInfo(projectId: string) {
+  try {
+    const project = await gt.getProjectData(projectId);
+    
+    console.log('=== Project Information ===');
+    console.log(`ID: ${project.id}`);
+    console.log(`Name: ${project.name}`);
+    console.log(`Organization: ${project.orgId}`);
+    console.log(`Default Locale: ${project.defaultLocale}`);
+    console.log(`Target Locales: ${project.currentLocales.join(', ')}`);
+    
+    return project;
+  } catch (error) {
+    console.error(`Failed to retrieve project ${projectId}:`, error);
+    throw error;
+  }
+}
+
+const projectInfo = await getProjectInfo('my-project-123');
+```
+
+---
+
+## Notes
+
+* The method provides read-only access to project information - use the dashboard to modify project settings
+* This method requires a valid project ID - the project must be accessible with the provided API key
+* Project data includes both source and target locale configurations
+* The `currentLocales` array represents all target locales configured for the project
+* Use this method to validate project configuration before starting translation workflows
+
+## Next Steps
+
+* See [`shouldSetupProject()`](/docs/core/class/methods/translation/shouldSetupProject) to check if project setup is required
+* See [`setupProject()`](/docs/core/class/methods/translation/setupProject) to initialize project setup
+* See [`enqueueFiles()`](/docs/core/class/methods/translation/enqueueFiles) to start translation jobs
+* See [`querySourceFile()`](/docs/core/class/methods/translation/querySourceFile) for file-specific information
+* See [`ProjectData`](/docs/core/types/ProjectData) for detailed type information
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/core/class/methods/translation/meta.json b/apps/docs/content/docs/en/core/class/methods/translation/meta.json
new file mode 100644
index 000000000..a54600e39
--- /dev/null
+++ b/apps/docs/content/docs/en/core/class/methods/translation/meta.json
@@ -0,0 +1,17 @@
+{
+  "title": "Translation",
+  "pages": [
+    "./checkFileTranslations",
+    "./checkSetupStatus",
+    "./downloadFileBatch",
+    "./downloadTranslatedFile",
+    "./enqueueFiles",
+    "./getProjectData",
+    "./querySourceFile",
+    "./setupProject",
+    "./shouldSetupProject",
+    "./translate",
+    "./translateMany",
+    "./uploadSourceFiles"
+  ]
+}
diff --git a/apps/docs/content/docs/en/core/class/methods/translation/querySourceFile.mdx b/apps/docs/content/docs/en/core/class/methods/translation/querySourceFile.mdx
new file mode 100644
index 000000000..ba56bbd45
--- /dev/null
+++ b/apps/docs/content/docs/en/core/class/methods/translation/querySourceFile.mdx
@@ -0,0 +1,159 @@
+---
+title: querySourceFile()
+description: API Reference for the querySourceFile() method to get source file and translation information
+---
+
+## Overview
+
+The `querySourceFile()` method retrieves comprehensive information about a source file and all its associated translations.
+This includes file metadata, translation status across all locales, and timestamps for creation, completion, approval, and publishing.
+
+```typescript
+const gt = new GT({ projectId: 'your-project-id', apiKey: 'your-api-key' });
+
+const result = await gt.querySourceFile({
+  fileId: 'file-123',
+  versionId: 'version-456'
+});
+
+console.log(`Source file: ${result.sourceFile.fileName}`);
+console.log(`Available in ${result.translations.length} locales`);
+```
+
+## Reference
+
+### Parameters
+
+| Name | Type | Description |
+|------|------|-------------|
+| `data` | `FileQuery` | File query object specifying which file to retrieve |
+| `options?` | `CheckFileTranslationsOptions` | Optional configuration for the request |
+
+#### FileQuery
+
+| Name | Type | Description |
+|------|------|-------------|
+| `fileId` | `string` | Unique identifier of the file to query |
+| `versionId?` | `string` | Optional version ID for the specific file version |
+
+#### CheckFileTranslationsOptions
+
+| Name | Type | Description |
+|------|------|-------------|
+| `timeout?` | `number` | Request timeout in milliseconds |
+
+### Returns
+
+`Promise<FileQueryResult>` - Contains source file information and translation status for all locales.
+
+```typescript
+type FileQueryResult = {
+  sourceFile: {
+    id: string;
+    fileId: string;
+    versionId: string;
+    sourceLocale: string;
+    fileName: string;
+    fileFormat: string;
+    dataFormat: string | null;
+    createdAt: string;
+    updatedAt: string;
+    approvalRequiredAt: string | null;
+    locales: string[];
+  };
+  translations: {
+    locale: string;
+    completedAt: string | null;
+    approvedAt: string | null;
+    publishedAt: string | null;
+    createdAt: string | null;
+    updatedAt: string | null;
+  }[];
+}
+```
+
+#### Source File Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `id` | `string` | Internal database ID |
+| `fileId` | `string` | Unique file identifier |
+| `versionId` | `string` | Version identifier |
+| `sourceLocale` | `string` | Source language locale |
+| `fileName` | `string` | Original file name |
+| `fileFormat` | `string` | File format (JSON, MD, MDX, etc.) |
+| `dataFormat` | `string \| null` | Data format within file (ICU, I18NEXT, JSX) |
+| `createdAt` | `string` | ISO timestamp of file creation |
+| `updatedAt` | `string` | ISO timestamp of last update |
+| `approvalRequiredAt` | `string \| null` | ISO timestamp when approval was requested |
+| `locales` | `string[]` | List of target locales for this file |
+
+#### Translation Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `locale` | `string` | Target locale code |
+| `completedAt` | `string \| null` | ISO timestamp of translation completion |
+| `approvedAt` | `string \| null` | ISO timestamp of translation approval |
+| `publishedAt` | `string \| null` | ISO timestamp of translation publishing |
+| `createdAt` | `string \| null` | ISO timestamp of translation job creation |
+| `updatedAt` | `string \| null` | ISO timestamp of last translation update |
+
+---
+
+## Example
+
+
+```typescript title="index.ts" copy
+import { GT } from 'generaltranslation';
+
+const gt = new GT({
+  projectId: 'your-project-id',
+  apiKey: 'your-api-key'
+});
+
+async function getFileInfo(fileId: string, versionId?: string) {
+  const result = await gt.querySourceFile({
+    fileId,
+    versionId
+  });
+  
+  console.log('=== Source File Info ===');
+  console.log(`Name: ${result.sourceFile.fileName}`);
+  console.log(`Format: ${result.sourceFile.fileFormat}`);
+  console.log(`Source Locale: ${result.sourceFile.sourceLocale}`);
+  console.log(`Created: ${new Date(result.sourceFile.createdAt).toLocaleString()}`);
+  console.log(`Updated: ${new Date(result.sourceFile.updatedAt).toLocaleString()}`);
+  
+  console.log('\n=== Translation Status ===');
+  result.translations.forEach(translation => {
+    console.log(`${translation.locale}:`);
+    console.log(`  Created: ${translation.createdAt ? new Date(translation.createdAt).toLocaleString() : 'Not started'}`);
+    console.log(`  Completed: ${translation.completedAt ? new Date(translation.completedAt).toLocaleString() : 'In progress'}`);
+    console.log(`  Published: ${translation.publishedAt ? new Date(translation.publishedAt).toLocaleString() : 'Not published'}`);
+  });
+  
+  return result;
+}
+
+const fileInfo = await getFileInfo('file-123', 'version-456');
+```
+
+
+---
+
+## Notes
+
+* Returns the source file and translation status for all target locales
+* Translation timestamps follow the lifecycle: `createdAt` → `completedAt` → `approvedAt` → `publishedAt`
+* Null timestamps indicate that stage hasn't been reached yet
+* The `locales` array in the source file shows all target locales configured for translation
+* Use this method for detailed reporting, progress tracking, and file management workflows
+
+## Next Steps
+
+* See [`checkFileTranslations()`](/docs/core/class/methods/translation/checkFileTranslations) for lightweight status checking of specific translations
+* See [`downloadTranslatedFile()`](/docs/core/class/methods/translation/downloadTranslatedFile) to download completed translations
+* See [`enqueueFiles()`](/docs/core/class/methods/translation/enqueueFiles) to start translation jobs for files
+* See [`getProjectData()`](/docs/core/class/methods/translation/getProjectData) for project-level information
+* See [`FileQueryResult`](/docs/core/types/FileQueryResult) for detailed result type information
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/core/class/methods/translation/setupProject.mdx b/apps/docs/content/docs/en/core/class/methods/translation/setupProject.mdx
new file mode 100644
index 000000000..724a4f3d7
--- /dev/null
+++ b/apps/docs/content/docs/en/core/class/methods/translation/setupProject.mdx
@@ -0,0 +1,110 @@
+---
+title: setupProject()
+description: API Reference for the setupProject() method to initialize translation project setup
+---
+
+## Overview
+
+The `setupProject()` method initializes the setup process for a translation project using previously uploaded files.
+This creates an asynchronous setup job that analyzes the files and prepares them for translation workflows.
+
+```typescript
+const gt = new GT({ projectId: 'your-project-id', apiKey: 'your-api-key' });
+
+const setupResult = await gt.setupProject(fileRefs, 30000);
+console.log(`Setup job created: ${setupResult.setupJobId}`);
+```
+
+<Callout type="info">
+  You must have previously uploaded the files using [`uploadSourceFiles()`](/docs/core/class/methods/translation/uploadSourceFiles) before calling `setupProject()`.
+</Callout>
+
+## Reference
+
+### Parameters
+
+| Name | Type | Description |
+|------|------|-------------|
+| `files` | `FileUploadRef[]` | Array of file references from previously uploaded source files |
+| `timeoutMs?` | `number` | Optional timeout in milliseconds for the API request |
+
+#### FileUploadRef Structure
+
+```typescript
+type FileUploadRef = {
+  fileId: string;
+  versionId: string;
+  fileName: string;
+  fileFormat?: FileFormat;
+  dataFormat?: DataFormat;
+}
+```
+
+### Returns
+
+`Promise<SetupProjectResult>` - Contains the setup job identifier and initial status.
+
+```typescript
+type SetupProjectResult = {
+  setupJobId: string;
+  status: 'queued';
+}
+```
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `setupJobId` | `string` | Unique identifier for the setup job |
+| `status` | `'queued'` | Initial status of the setup job |
+
+---
+
+## Examples
+
+### Basic Usage
+
+Initialize project setup with uploaded files:
+
+```typescript title="index.ts" copy
+import { GT } from 'generaltranslation';
+
+const gt = new GT({
+  projectId: 'your-project-id',
+  apiKey: 'your-api-key'
+});
+
+// File references from previous upload
+const fileRefs = [
+  {
+    fileId: 'file-123',
+    versionId: 'version-456',
+    fileName: 'app.json',
+    fileFormat: 'JSON'
+  },
+  {
+    fileId: 'file-789',
+    versionId: 'version-012',
+    fileName: 'content.md',
+    fileFormat: 'MD'
+  }
+];
+
+const setupResult = await gt.setupProject(fileRefs);
+console.log(`Setup initiated with job ID: ${setupResult.setupJobId}`);
+```
+
+---
+
+## Notes
+
+* Files must be uploaded using [`uploadSourceFiles()`](/docs/core/class/methods/translation/uploadSourceFiles) before calling `setupProject()`
+* Project setup analyzes file content and structure to optimize translation workflows
+* The setup job runs asynchronously - monitor progress with [`checkSetupStatus()`](/docs/core/class/methods/translation/checkSetupStatus)
+* Setup is typically required before enqueueing translation jobs for new projects
+
+## Next Steps
+
+* See [`uploadSourceFiles()`](/docs/core/class/methods/translation/uploadSourceFiles) to upload files before setup
+* See [`checkSetupStatus()`](/docs/core/class/methods/translation/checkSetupStatus) to monitor setup progress
+* See [`shouldSetupProject()`](/docs/core/class/methods/translation/shouldSetupProject) to check if setup is required
+* See [`enqueueFiles()`](/docs/core/class/methods/translation/enqueueFiles) to start translations after setup
+* See [`FileUploadRef`](/docs/core/types/FileUploadRef) for file reference structure details
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/core/class/methods/translation/shouldSetupProject.mdx b/apps/docs/content/docs/en/core/class/methods/translation/shouldSetupProject.mdx
new file mode 100644
index 000000000..fc14b4dfe
--- /dev/null
+++ b/apps/docs/content/docs/en/core/class/methods/translation/shouldSetupProject.mdx
@@ -0,0 +1,85 @@
+---
+title: shouldSetupProject()
+description: API Reference for the shouldSetupProject() method to check if project setup is required
+---
+
+## Overview
+
+The `shouldSetupProject()` method checks whether a project requires setup before translation jobs can be enqueued.
+This method queries the API to determine if the project has been properly initialized and configured for translation workflows.
+
+```typescript
+const gt = new GT({ projectId: 'your-project-id', apiKey: 'your-api-key' });
+
+const result = await gt.shouldSetupProject();
+if (result.shouldSetupProject) {
+  console.log('Project setup is required');
+} else {
+  console.log('Project is ready for translations');
+}
+```
+
+
+## Reference
+
+### Parameters
+
+None - this method uses the GT instance configuration to check the project.
+
+### Returns
+
+`Promise<ShouldSetupProjectResult>` - Contains a boolean indicating if setup is required.
+
+```typescript
+type ShouldSetupProjectResult = {
+  shouldSetupProject: boolean;
+}
+```
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `shouldSetupProject` | `boolean` | `true` if project setup is required, `false` if already set up |
+
+---
+
+## Examples
+
+### Basic Usage
+
+```typescript title="index.ts" copy
+import { GT } from 'generaltranslation';
+
+const gt = new GT({
+  apiKey: 'your-api-key',
+  projectId: 'my-project'
+});
+
+async function checkProjectStatus() {
+  const result = await gt.shouldSetupProject();
+  
+  if (result.shouldSetupProject) {
+    console.log('Project needs setup');
+    return 'setup-required';
+  } else {
+    console.log('Project is ready for translations');
+    return 'ready';
+  }
+}
+
+const status = await checkProjectStatus();
+```
+
+---
+
+## Notes
+
+* The result determines whether [`setupProject()`](/docs/core/class/methods/translation/setupProject) needs to be called
+* Projects typically need setup when they're newly created or when significant structural changes are made
+
+## Next Steps
+
+* See [`setupProject()`](/docs/core/class/methods/translation/setupProject) to perform setup if required
+* See [`checkSetupStatus()`](/docs/core/class/methods/translation/checkSetupStatus) to monitor setup progress
+* See [`enqueueFiles()`](/docs/core/class/methods/translation/enqueueFiles) to start translations after setup
+* See [`uploadSourceFiles()`](/docs/core/class/methods/translation/uploadSourceFiles) to upload files before setup
+* See [`ShouldSetupProjectResult`](/docs/core/types/ShouldSetupProjectResult) for the result type details
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/core/class/methods/translation/translate.mdx b/apps/docs/content/docs/en/core/class/methods/translation/translate.mdx
new file mode 100644
index 000000000..7d83e5d5e
--- /dev/null
+++ b/apps/docs/content/docs/en/core/class/methods/translation/translate.mdx
@@ -0,0 +1,174 @@
+---
+title: translate()
+description: API Reference for the GT translate method
+---
+
+## Overview
+
+The `translate()` method is the primary translation function in the GT library.
+It translates content from the source locale to a specified target locale using AI-powered translation services.
+
+```typescript
+const gt = new GT({
+  apiKey: 'your-api-key',
+  projectId: 'your-project-id'
+});
+
+const result = await gt.translate('Hello, world!', 'es');
+console.log(result); // "¡Hola, mundo!"
+```
+
+The method supports multiple content types including plain text, ICU message format, and i18next-style messages, with optional metadata for improved translation accuracy.
+
+<Callout>
+**Authentication Required:**
+The `translate()` method requires both `apiKey` (or `devApiKey`) and `projectId` to be configured in the GT instance.
+</Callout>
+
+---
+
+## Reference
+
+### Parameters
+
+The `translate()` method has multiple overloads for different content types:
+
+#### Text Content
+<TypeTable
+  type={{
+    "source": {
+      type: 'string',
+      optional: false,
+    },
+    "targetLocale": {
+      type: 'string',
+      optional: false,
+    },
+    "metadata?": {
+      type: 'EntryMetadata',
+      optional: true,
+    }
+  }}
+/>
+
+#### JSX Content
+<TypeTable
+  type={{
+    "source": {
+      type: 'JsxChildren',
+      optional: false,
+    },
+    "targetLocale": {
+      type: 'string',
+      optional: false,
+    },
+    "metadata?": {
+      type: 'Omit<EntryMetadata, "dataFormat"> & { dataFormat?: "JSX" }',
+      optional: true,
+    }
+  }}
+/>
+
+#### ICU Message Format
+<TypeTable
+  type={{
+    "source": {
+      type: 'IcuMessage',
+      optional: false,
+    },
+    "targetLocale": {
+      type: 'string',
+      optional: false,
+    },
+    "metadata?": {
+      type: 'Omit<EntryMetadata, "dataFormat"> & { dataFormat?: "ICU" }',
+      optional: true,
+    }
+  }}
+/>
+
+#### i18next Format
+<TypeTable
+  type={{
+    "source": {
+      type: 'I18nextMessage',
+      optional: false,
+    },
+    "targetLocale": {
+      type: 'string',
+      optional: false,
+    },
+    "metadata?": {
+      type: 'Omit<EntryMetadata, "dataFormat"> & { dataFormat?: "I18NEXT" }',
+      optional: true,
+    }
+  }}
+/>
+
+### Parameters Description
+
+| Parameter | Description |
+|-----------|-------------|
+| `source` | The content to translate. Can be plain text, JSX elements, ICU messages, or i18next messages |
+| `targetLocale` | BCP-47 locale code for the target language (e.g., 'es', 'fr-CA') |
+| `metadata` | Optional translation context including context, tags, and formatting options |
+
+### Returns
+
+```typescript
+Promise<TranslationResult | TranslationError>
+```
+
+- **TranslationResult**: Contains the translated content and metadata
+- **TranslationError**: Contains error information if translation fails
+
+---
+
+## Behavior
+
+### Content Type Detection
+
+The method automatically detects content type based on the `source` parameter:
+
+- **String**: Treated as plain text or ICU message format
+- **JSX Elements**: Handled as React-style JSX content  
+- **Objects**: Processed as structured message formats
+
+### Locale Resolution
+
+- Target locale is validated against BCP-47 standards
+- Custom locale mappings are applied if configured
+- Canonical locale codes are used for API requests
+
+### Context Enhancement
+
+When custom mapping includes region or script codes for the target locale, they are automatically added to the metadata for improved translation accuracy.
+
+---
+
+## Examples
+
+
+```typescript
+const gt = new GT({
+  apiKey: 'your-api-key',
+  projectId: 'your-project-id'
+});
+
+const result = await gt.translate('Welcome to our application', 'fr');
+console.log(result); 
+// "Bienvenue dans notre application"
+```
+
+---
+
+## Notes
+
+- Translates a given string to a target locale and returns a promise
+
+## Next Steps
+
+- **[Translate multiple items with translateMany()](/docs/core/class/methods/translation/translateMany)**
+- **[Learn about EntryMetadata options](/docs/core/types/EntryMetadata)**
+- **[Explore TranslationResult type](/docs/core/types/TranslationResult)**
+- **[Check translation requirements](/docs/core/class/methods/locales/requiresTranslation)**
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/core/class/methods/translation/translateMany.mdx b/apps/docs/content/docs/en/core/class/methods/translation/translateMany.mdx
new file mode 100644
index 000000000..f812f1c64
--- /dev/null
+++ b/apps/docs/content/docs/en/core/class/methods/translation/translateMany.mdx
@@ -0,0 +1,144 @@
+---
+title: translateMany()
+description: API Reference for the GT translateMany method for batch translations
+---
+
+## Overview
+
+The `translateMany()` method efficiently translates multiple content items in a single API request.
+It's optimized for batch processing and provides better performance than multiple individual `translate()` calls.
+
+```typescript
+const gt = new GT({
+  apiKey: 'your-api-key',
+  projectId: 'your-project-id'
+});
+
+const result = await gt.translateMany([
+  { source: 'Hello, world!' },
+  { source: 'Welcome to our app' },
+  { source: 'Click here to continue' }
+], { targetLocale: 'es' });
+```
+
+---
+
+## Reference
+
+### Parameters
+
+<TypeTable
+  type={{
+    "sources": {
+      type: 'Entry[]',
+      optional: false,
+    },
+    "globalMetadata?": {
+      type: '{ targetLocale: string } & EntryMetadata',
+      optional: true,
+    }
+  }}
+/>
+
+### Parameters Description
+
+| Parameter | Description |
+|-----------|-------------|
+| `sources` | Array of `Entry` objects containing source content and optional per-item metadata |
+| `globalMetadata` | Global metadata applied to all entries, including the required `targetLocale` |
+
+### Entry Object Structure
+
+Each entry in the `sources` array can contain:
+
+```typescript
+interface Entry {
+  source: Content;           // The content to translate
+  targetLocale?: string;     // Override global target locale
+  context?: string;          // Translation context for this entry
+  tags?: string[];          // Tags for categorization
+  // ... other EntryMetadata properties
+}
+```
+
+### Returns
+
+```typescript
+Promise<TranslateManyResult>
+```
+
+The result contains translated entries and any error information:
+
+```typescript
+interface TranslateManyResult {
+  translations: Array<TranslationResult | TranslationError>;
+  metadata: {
+    totalRequests: number;
+    successCount: number;
+    errorCount: number;
+    processingTime: number;
+  };
+}
+```
+
+---
+
+## Behavior
+
+### Global vs Per-Item Metadata
+
+- **Global metadata** is applied to all entries as defaults
+- **Per-item metadata** overrides global settings for specific entries
+- Target locale can be overridden per entry
+
+### Error Handling Strategy
+
+- Individual translation failures don't stop the entire batch
+- Each result indicates success or failure independently  
+- Partial success scenarios are fully supported
+
+### Locale Resolution
+
+- Global target locale is used as default for all entries
+- Per-entry target locales override the global setting
+- All locales are resolved through custom mapping if configured
+
+---
+
+## Examples
+
+```typescript
+const menuItems = await gt.translateMany([
+  { source: 'Home' },
+  { source: 'About' },
+  { source: 'Products' },
+  { source: 'Contact' }
+], {
+  targetLocale: 'fr',
+  context: 'Navigation menu items'
+});
+
+menuItems.translations.forEach((result, index) => {
+  if ('translation' in result) {
+    console.log(`Item ${index}: ${result.translation}`);
+  } else {
+    console.error(`Item ${index} failed: ${result.error}`);
+  }
+});
+```
+
+---
+
+## Notes
+
+- Translates multiple items in a single API request
+- Translation failures in one entry don't affect others
+- Results maintain the same order as input entries
+- Global metadata is merged with per-entry metadata (per-entry takes precedence)
+
+## Next Steps
+
+- Learn about single translations with [translate()](/docs/core/class/methods/translation/translate)
+- Explore [Entry and EntryMetadata types](/docs/core/types/Entry)
+- Understand [TranslateManyResult structure](/docs/core/types/TranslateManyResult)
+- Check file-based workflows with [enqueueFiles()](/docs/core/class/methods/translation/enqueueFiles)
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/core/class/methods/translation/uploadSourceFiles.mdx b/apps/docs/content/docs/en/core/class/methods/translation/uploadSourceFiles.mdx
new file mode 100644
index 000000000..138a64d2e
--- /dev/null
+++ b/apps/docs/content/docs/en/core/class/methods/translation/uploadSourceFiles.mdx
@@ -0,0 +1,226 @@
+---
+title: uploadSourceFiles()
+description: API Reference for the uploadSourceFiles() method to upload source files for translation
+---
+
+## Overview
+
+The `uploadSourceFiles()` method uploads source files to the General Translation platform for translation processing.
+This is typically the first step in a translation workflow before setting up projects or enqueueing translation jobs.
+
+```typescript
+const gt = new GT({ apiKey: 'your-api-key', projectId: 'your-project-id' });
+
+const result = await gt.uploadSourceFiles(files, {
+  sourceLocale: 'en'
+});
+```
+
+<Mermaid
+  chart="
+graph TD;
+A[uploadSourceFiles];
+B[setupProject];
+C[enqueueFiles];
+E[checkFileTranslations];
+F[downloadFileBatch];
+A --> B;
+B --> C;
+C --> E;
+E --> F;
+"
+/>
+
+
+
+
+## Reference
+
+### Parameters
+
+| Name | Type | Description |
+|------|------|-------------|
+| `files` | `FileUpload[]` | Array of source files to upload |
+| `options` | `UploadFilesOptions` | Configuration options for the upload |
+
+#### FileUpload Structure
+
+| Name | Type | Description |
+|------|------|-------------|
+| `content` | `string` | Raw file content as a string |
+| `fileName` | `string` | Unique file identifier (typically file path + name) |
+| `fileFormat` | `FileFormat` | Format of the file (JSON, MDX, MD, XML, etc.) |
+| `dataFormat?` | `DataFormat` | Optional format of data within the file (ICU, I18NEXT, JSX) |
+| `locale` | `string` | Locale of the source file content |
+| `versionId?` | `string` | Optional version ID for advanced use cases |
+| `fileId?` | `string` | Optional file ID for advanced use cases |
+
+#### UploadFilesOptions
+
+| Name | Type | Description |
+|------|------|-------------|
+| `sourceLocale` | `string` | The source locale for all uploaded files |
+| `modelProvider?` | `string` | Optional AI model provider preference |
+| `timeout?` | `number` | Request timeout in milliseconds |
+
+### Returns
+
+`Promise<UploadFilesResponse>` - Contains upload results and file references.
+
+```typescript
+type UploadFilesResponse = {
+  uploadedFiles: FileUploadRef[];
+  count: number;
+  message: string;
+}
+```
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `uploadedFiles` | `FileUploadRef[]` | Array of uploaded file references for subsequent operations |
+| `count` | `number` | Number of files successfully uploaded |
+| `message` | `string` | Status message from the API |
+
+#### FileUploadRef Structure
+
+```typescript
+type FileUploadRef = {
+  fileId: string;
+  versionId: string;
+  fileName: string;
+  fileFormat: FileFormat;
+  dataFormat?: DataFormat;
+  locale?: string;
+}
+```
+
+---
+
+## Examples
+
+### Basic Usage
+
+Upload JSON translation files:
+
+```typescript copy
+import { GT } from 'generaltranslation';
+import fs from 'fs';
+
+const gt = new GT({
+  apiKey: 'your-api-key'
+});
+
+const files = [
+  {
+    content: fs.readFileSync('./locales/en/common.json', 'utf8'),
+    fileName: 'common.json',
+    fileFormat: 'JSON' as const,
+    locale: 'en'
+  },
+  {
+    content: fs.readFileSync('./locales/en/navigation.json', 'utf8'),
+    fileName: 'navigation.json', 
+    fileFormat: 'JSON' as const,
+    locale: 'en'
+  }
+];
+
+const result = await gt.uploadSourceFiles(files, {
+  sourceLocale: 'en'
+});
+
+console.log(`Uploaded ${result.count} files`);
+result.uploadedFiles.forEach(file => {
+  console.log(`  ${file.fileName}: ${file.fileId}`);
+});
+```
+
+### With Data Format Specification
+
+Upload files with explicit data format specification:
+
+```typescript copy
+const files = [
+  {
+    content: '{"welcome": "Welcome, {name}!"}',
+    fileName: 'messages.json',
+    fileFormat: 'JSON' as const,
+    dataFormat: 'ICU' as const, // ICU message format
+    locale: 'en'
+  },
+  {
+    content: '{"greeting": "Hello {{name}}"}',
+    fileName: 'i18next.json',
+    fileFormat: 'JSON' as const,
+    dataFormat: 'I18NEXT' as const,
+    locale: 'en'
+  }
+];
+
+const result = await gt.uploadSourceFiles(files, {
+  sourceLocale: 'en',
+  modelProvider: 'gpt-4',
+  timeout: 30000
+});
+```
+
+### Batch Upload with Error Handling
+
+Upload multiple files with comprehensive error handling:
+
+```typescript copy
+import { glob } from 'glob';
+import path from 'path';
+
+async function uploadAllJsonFiles() {
+  try {
+    // Find all JSON files
+    const jsonPaths = await glob('./locales/en/**/*.json');
+    
+    const files = jsonPaths.map(filePath => ({
+      content: fs.readFileSync(filePath, 'utf8'),
+      fileName: path.relative('./locales/en', filePath),
+      fileFormat: 'JSON' as const,
+      locale: 'en'
+    }));
+
+    console.log(`Uploading ${files.length} files...`);
+    
+    const result = await gt.uploadSourceFiles(files, {
+      sourceLocale: 'en',
+      timeout: 60000 // 60 second timeout for large uploads
+    });
+
+    if (result.count !== files.length) {
+      console.warn(`Expected ${files.length} files, but only ${result.count} uploaded`);
+    }
+
+    return result.uploadedFiles;
+    
+  } catch (error) {
+    console.error('Upload failed:', error);
+    throw error;
+  }
+}
+
+const uploadedFiles = await uploadAllJsonFiles();
+```
+
+---
+
+## Notes
+
+* File content is automatically Base64 encoded for safe transmission
+* File names should be unique identifiers, typically including the file path
+* The `locale` field in each file should match the `sourceLocale` option
+* Large files or many files may require increased timeout values
+* File references returned from this method are needed for subsequent operations
+* Supported file formats include JSON, MD, MDX, XML, and others - see `FileFormat` type for complete list
+
+## Next Steps
+
+* See [`setupProject()`](/docs/core/class/methods/translation/setupProject) to prepare uploaded files for translation
+* See [`enqueueFiles()`](/docs/core/class/methods/translation/enqueueFiles) to start translation jobs
+* See [`uploadTranslations()`](/docs/core/class/methods/translation/uploadTranslations) to upload pre-existing translations
+* See [`FileUpload`](/docs/core/types/FileUpload) for detailed file structure
+* See [`FileFormat`](/docs/core/types/FileFormat) for supported file formats
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/core/class/setConfig.mdx b/apps/docs/content/docs/en/core/class/setConfig.mdx
new file mode 100644
index 000000000..5a70cd704
--- /dev/null
+++ b/apps/docs/content/docs/en/core/class/setConfig.mdx
@@ -0,0 +1,90 @@
+---
+title: setConfig()
+description: API Reference for the GT setConfig method
+---
+
+## Overview
+
+The `setConfig()` method updates the configuration of an existing GT instance.
+This allows you to modify API credentials, locales, and other settings after the instance has been created.
+
+```typescript
+const gt = new GT();
+
+gt.setConfig({
+  apiKey: 'your-new-api-key',
+  projectId: 'your-project-id',
+  sourceLocale: 'en',
+  targetLocale: 'es'
+});
+```
+
+
+The `setConfig()` method will validate all provided locale codes and merge with any existing configuration that was passed to the constructor.
+
+---
+
+## Reference
+
+### Parameters
+
+<TypeTable
+  type={{
+    "params": {
+      type: 'GTConstructorParams',
+      optional: false,
+    }
+  }}
+/>
+
+The `GTConstructorParams` object supports the same properties as the constructor:
+
+| Property | Type | Optional | Description |
+|----------|------|----------|-------------|
+| `apiKey` | `string` | ✓ | Production API key for translation service |
+| `devApiKey` | `string` | ✓ | Development API key |
+| `projectId` | `string` | ✓ | Unique project identifier |
+| `sourceLocale` | `string` | ✓ | Default source locale for translations |
+| `targetLocale` | `string` | ✓ | Default target locale for translations |
+| `locales` | `string[]` | ✓ | Array of supported locale codes |
+| `baseUrl` | `string` | ✓ | Custom API base URL |
+| `customMapping` | `CustomMapping` | ✓ | Custom locale code mappings |
+
+### Returns
+
+`void` - The method updates the instance configuration in-place.
+
+---
+
+## Example
+
+In this example, we switch the target locale from Spanish to French.
+
+```typescript
+const gt = new GT({
+  sourceLocale: 'en',
+  targetLocale: 'es'
+});
+
+// Switch to French
+gt.setConfig({
+  targetLocale: 'fr'
+});
+```
+
+---
+
+## Notes
+
+- Configuration changes take effect immediately for subsequent method calls
+- Environment variables are not re-read when calling `setConfig()`
+- Custom mappings completely replace existing mappings (not merged)
+- Validation failures leave the instance configuration unchanged
+- The method is synchronous and returns `void`
+
+## Next Steps
+
+- **[Initialize with constructor](/docs/core/class/constructor)**
+- **[Start translating content](/docs/core/class/methods/translation/translate)**
+- **[Learn about GTConstructorParams](/docs/core/types/GTConstructorParams)**
+- **[Explore custom mappings](/docs/core/types/CustomMapping)**
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/core/functions/formatting/formatDateTime.mdx b/apps/docs/content/docs/en/core/functions/formatting/formatDateTime.mdx
new file mode 100644
index 000000000..f5d8c10fc
--- /dev/null
+++ b/apps/docs/content/docs/en/core/functions/formatting/formatDateTime.mdx
@@ -0,0 +1,152 @@
+---
+title: formatDateTime()
+description: Standalone function to format dates and times according to locale conventions
+---
+
+## Overview
+
+The standalone `formatDateTime()` function formats dates and times according to locale-specific conventions without requiring a GT instance.
+It provides the same functionality as the GT class method but can be used independently.
+
+```typescript
+import { formatDateTime } from 'generaltranslation';
+
+const formatted = formatDateTime(new Date(), {
+  locales: 'de-DE',
+  dateStyle: 'medium',
+  timeStyle: 'short'
+});
+// Returns: "26.09.2025, 17:33"
+```
+
+## Reference
+
+### Parameters
+
+| Name | Type | Description |
+|------|------|-------------|
+| `date` | `Date` | The date object to format |
+| `options` | `DateTimeFormatOptions & { locales?: string \| string[] }` | Formatting configuration with optional locales |
+
+### DateTimeFormatOptions
+
+| Name | Type | Description |
+|------|------|-------------|
+| `locales?` | `string \| string[]` | Locales for formatting (defaults to system locale) |
+| `dateStyle?` | `'full' \| 'long' \| 'medium' \| 'short'` | Overall date formatting style |
+| `timeStyle?` | `'full' \| 'long' \| 'medium' \| 'short'` | Overall time formatting style |
+| `weekday?` | `'long' \| 'short' \| 'narrow'` | Weekday representation |
+| `year?` | `'numeric' \| '2-digit'` | Year representation |
+| `month?` | `'numeric' \| '2-digit' \| 'long' \| 'short' \| 'narrow'` | Month representation |
+| `day?` | `'numeric' \| '2-digit'` | Day representation |
+| `hour?` | `'numeric' \| '2-digit'` | Hour representation |
+| `minute?` | `'numeric' \| '2-digit'` | Minute representation |
+| `second?` | `'numeric' \| '2-digit'` | Second representation |
+| `timeZone?` | `string` | IANA time zone identifier |
+| `hour12?` | `boolean` | Whether to use 12-hour time format |
+
+### Returns
+
+`string` - The formatted date and time according to locale conventions.
+
+---
+
+## Example
+
+### Basic Usage
+
+```typescript copy
+import { formatDateTime } from 'generaltranslation';
+
+// Basic formatting with explicit locale
+console.log(formatDateTime(date, { locales: 'en-US' }));
+// Output: "3/14/2024"
+
+// German formatting
+console.log(formatDateTime(date, { locales: 'de-DE' }));
+// Output: "14.3.2024"
+
+// Multiple locale fallbacks
+console.log(formatDateTime(date, { 
+  locales: ['ja-JP', 'en-US'] 
+}));
+// Output: "2024/3/14" (Japanese format)
+```
+
+### Date and Time Styles
+
+```typescript copy
+const date = new Date('2024-03-14T14:30:45Z');
+
+// Full date style
+console.log(formatDateTime(date, {
+  locales: 'en-US',
+  dateStyle: 'full'
+}));
+// Output: "Thursday, March 14, 2024"
+
+// Long date with short time
+console.log(formatDateTime(date, {
+  locales: 'fr-FR',
+  dateStyle: 'long',
+  timeStyle: 'short'
+}));
+// Output: "14 mars 2024 à 07:30"
+
+// Short format across locales
+const locales = ['en-US', 'de-DE', 'ja-JP'];
+locales.forEach(locale => {
+  console.log(`${locale}: ${formatDateTime(date, {
+    locales: locale,
+    dateStyle: 'short',
+    timeStyle: 'short'
+  })}`);
+});
+// Output:
+// en-US: 3/14/24, 7:30 AM
+// de-DE: 14.03.24, 07:30
+// ja-JP: 2024/03/14 7:30
+```
+
+### Time Zone Handling
+
+```typescript copy
+const date = new Date('2024-03-14T14:30:45Z');
+
+// Format for different time zones
+const timeZones = [
+  'America/New_York',
+  'Europe/London', 
+  'Asia/Tokyo'
+];
+
+timeZones.forEach(timeZone => {
+  const formatted = formatDateTime(date, {
+    locales: 'en-US',
+    timeZone,
+    dateStyle: 'medium',
+    timeStyle: 'medium'
+  });
+  console.log(`${timeZone}: ${formatted}`);
+});
+// Output varies based on daylight saving time
+```
+
+---
+
+## Notes
+
+* The `locales` parameter is optional and defaults to the system locale if not provided
+* Uses the same underlying `Intl.DateTimeFormat` as the GT class method
+* Results are cached internally for performance with repeated locale/options combinations
+* All standard `Intl.DateTimeFormat` options are supported
+* Time zones are handled correctly when specified
+* Different locales have different default date/time formats and 12-hour vs 24-hour preferences
+
+## Next Steps
+
+* Check out [`Intl.DateTimeFormat` documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat) for more options
+* See [`formatNum()`](/docs/core/functions/formatting/formatNum) for standalone number formatting
+* See [`formatMessage()`](/docs/core/functions/formatting/formatMessage) for standalone message formatting
+* See GT class [`formatDateTime()`](/docs/core/class/methods/formatting/formatDateTime) for instance-based usage
+* See [`formatRelativeTime()`](/docs/core/functions/formatting/formatRelativeTime) for relative time formatting
diff --git a/apps/docs/content/docs/en/core/functions/formatting/formatMessage.mdx b/apps/docs/content/docs/en/core/functions/formatting/formatMessage.mdx
new file mode 100644
index 000000000..946f30734
--- /dev/null
+++ b/apps/docs/content/docs/en/core/functions/formatting/formatMessage.mdx
@@ -0,0 +1,182 @@
+---
+title: formatMessage()
+description: API Reference for the standalone formatMessage function
+---
+
+## Overview
+
+The `formatMessage()` method formats messages with variable substitution and locale-aware formatting.
+Built on top of Format.JS's [`intl-messageformat`](https://formatjs.github.io/docs/intl-messageformat/) library, it supports ICU message format patterns.
+
+This method is essential for variable interpolation and pluralization.
+It also supports number formatting and date formatting among other features.
+
+```typescript
+import { formatMessage } from 'generaltranslation';
+
+const formatted = formatMessage('Hello {name}, you have {count} messages', {
+  locales: ['en'],
+  variables: { name: 'Alice', count: 5 }
+});
+// Returns: "Hello Alice, you have 5 messages"
+```
+
+
+---
+
+## Reference
+
+### Parameters
+
+<TypeTable
+  type={{
+    "message": {
+      type: 'string',
+      optional: false,
+    },
+    "options?": {
+      type: 'object',
+      optional: true,
+    }
+  }}
+/>
+
+### Options Object
+
+| Property | Type | Optional | Default | Description |
+|----------|------|----------|---------|-------------|
+| `locales` | `string \| string[]` | ✓ | `['en']` | Locale(s) to use for formatting |
+| `variables` | `FormatVariables` | ✓ | `{}` | Object containing variables for interpolation |
+
+### Returns
+
+`string` - The formatted message with variables substituted and locale-specific formatting applied.
+
+---
+
+## Behavior
+
+### Locale Handling
+
+- Uses provided `locales` parameter for formatting
+- Falls back to `['en']` if no locales specified
+- Supports locale fallback chains with arrays
+
+### Variable Processing
+
+- Simple substitution: `{variable}` → replaced with value
+- ICU message format: Full support for plurals, selects, and formatting
+- Missing variables: Left unchanged in output
+
+### Message Format Support
+
+Same ICU message format features as the GT class method:
+- Number formatting: `{price, number, currency}`
+- Date formatting: `{date, date, short}`
+- Pluralization: `{count, plural, ...}`
+- Selection: `{gender, select, ...}`
+
+---
+
+## Examples
+
+### Basic Usage
+
+```typescript
+import { formatMessage } from 'generaltranslation';
+
+const greeting = formatMessage('Hello {name}!', {
+  locales: ['en'],
+  variables: { name: 'World' }
+});
+console.log(greeting); // "Hello World!"
+```
+
+### Without GT Instance
+
+```typescript
+// Utility function for formatting without class instantiation
+function quickFormat(template: string, variables: any, locale = 'en') {
+  return formatMessage(template, {
+    locales: [locale],
+    variables
+  });
+}
+
+const notification = quickFormat(
+  'You have {count, plural, =0 {no messages} =1 {one message} other {# messages}}',
+  { count: 3 },
+  'en'
+);
+console.log(notification); // "You have 3 messages"
+```
+
+### Currency and Number Formatting
+
+```typescript
+// German locale formatting
+const germanPrice = formatMessage('Preis: {price, number, currency}', {
+  locales: ['de'],
+  variables: { price: 1234.56 }
+});
+console.log(germanPrice); // "Preis: 1.234,56 €"
+
+// Percentage formatting
+const progress = formatMessage('Progress: {percent, number, percent}', {
+  locales: ['en'],
+  variables: { percent: 0.85 }
+});
+console.log(progress); // "Progress: 85%"
+```
+
+### Template Library
+
+```typescript
+import { formatMessage } from 'generaltranslation';
+
+class MessageTemplates {
+  private locale: string;
+  
+  constructor(locale: string = 'en') {
+    this.locale = locale;
+  }
+  
+  welcome(name: string) {
+    return formatMessage('Welcome back, {name}!', {
+      locales: [this.locale],
+      variables: { name }
+    });
+  }
+  
+  itemCount(count: number) {
+    return formatMessage(
+      '{count, plural, =0 {No items} =1 {One item} other {# items}}',
+      {
+        locales: [this.locale],
+        variables: { count }
+      }
+    );
+  }
+}
+
+const templates = new MessageTemplates('fr');
+console.log(templates.welcome('Marie')); // "Welcome back, Marie!" (in French)
+console.log(templates.itemCount(5)); // "5 éléments"
+```
+
+---
+
+## Notes
+
+- Requires explicit locale specification in options
+- Supports same ICU message format features as GT class method
+- Returns empty string for empty input templates
+- Variables are processed before ICU formatting rules
+
+## Next Steps
+
+- Check out [`Intl.MessageFormat` documentation](https://formatjs.github.io/docs/intl-messageformat/) for more options
+- Use GT class [`formatMessage()`](/docs/core/class/methods/formatting/formatMessage) for stateful formatting
+- Format numbers with standalone [`formatNum()`](/docs/core/functions/formatting/formatNum)
+- Learn about [`FormatVariables` type](/docs/core/types/FormatVariables)
+- Explore other standalone functions [`getLocaleName()`](/docs/core/functions/locales/getLocaleName)
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/core/functions/formatting/formatNum.mdx b/apps/docs/content/docs/en/core/functions/formatting/formatNum.mdx
new file mode 100644
index 000000000..d577ac783
--- /dev/null
+++ b/apps/docs/content/docs/en/core/functions/formatting/formatNum.mdx
@@ -0,0 +1,109 @@
+---
+title: formatNum()
+description: Standalone function to format numbers according to locale conventions
+---
+
+## Overview
+
+The standalone `formatNum()` function formats numbers according to locale-specific conventions without requiring a GT instance.
+It provides the same functionality as the GT class method but can be used independently.
+
+```typescript
+import { formatNum } from 'generaltranslation';
+
+const formatted = formatNum(1234.56, {
+  locales: 'de-DE',
+  style: 'currency',
+  currency: 'EUR'
+});
+// Returns: "1.234,56 €"
+```
+
+## Reference
+
+### Parameters
+
+| Name | Type | Description |
+|------|------|-------------|
+| `number` | `number` | The number to format |
+| `options` | `NumberFormatOptions & { locales: string \| string[] }` | Formatting configuration with required locales |
+
+### NumberFormatOptions
+
+| Name | Type | Description |
+|------|------|-------------|
+| `locales` | `string \| string[]` | **Required** - Locales for formatting |
+| `style?` | `'decimal' \| 'currency' \| 'percent' \| 'unit'` | Number formatting style |
+| `currency?` | `string` | Currency code (required when style is 'currency') |
+| `minimumIntegerDigits?` | `number` | Minimum number of integer digits (1-21) |
+| `minimumFractionDigits?` | `number` | Minimum number of fraction digits (0-20) |
+| `maximumFractionDigits?` | `number` | Maximum number of fraction digits (0-20) |
+| `useGrouping?` | `boolean \| 'always' \| 'auto' \| 'min2'` | Whether to use grouping separators |
+| `notation?` | `'standard' \| 'scientific' \| 'engineering' \| 'compact'` | Number notation format |
+
+### Returns
+
+`string` - The formatted number according to locale conventions.
+
+---
+
+## Example
+
+### Basic Usage
+
+```typescript copy
+import { formatNum } from 'generaltranslation';
+
+// Basic number formatting
+console.log(formatNum(1234.567, { locales: 'en-US' }));
+// Output: "1,234.567"
+
+// German formatting
+console.log(formatNum(1234.567, { locales: 'de-DE' }));
+// Output: "1.234,567"
+```
+
+### Currency Formatting
+
+```typescript copy
+// US Dollar
+console.log(formatNum(1234.56, {
+  locales: 'en-US',
+  style: 'currency',
+  currency: 'USD'
+}));
+// Output: "$1,234.56"
+
+// Euro with German locale
+console.log(formatNum(1234.56, {
+  locales: 'de-DE',
+  style: 'currency',
+  currency: 'EUR'
+}));
+// Output: "1.234,56 €"
+
+// Japanese Yen
+console.log(formatNum(1234.56, {
+  locales: 'ja-JP',
+  style: 'currency',
+  currency: 'JPY'
+}));
+// Output: "¥1,235"
+```
+---
+
+## Notes
+
+* Unlike the GT class method, the `locales` parameter is required
+* Uses the same underlying `Intl.NumberFormat` as the GT class method
+* Results are cached internally for performance with repeated locale/options combinations
+* Fallback locales are processed in order if the primary locale is not supported
+* All standard `Intl.NumberFormat` options are supported
+
+## Next Steps
+
+* Check out [`Intl.NumberFormat` documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat) for more options
+* See [`formatDateTime()`](/docs/core/functions/formatting/formatDateTime) for standalone date formatting
+* See [`formatMessage()`](/docs/core/functions/formatting/formatMessage) for standalone message formatting
+* See GT class [`formatNum()`](/docs/core/class/methods/formatting/formatNum) for instance-based usage
+* See [`formatCurrency()`](/docs/core/functions/formatting/formatCurrency) for specialized currency formatting
diff --git a/apps/docs/content/docs/en/core/functions/formatting/meta.json b/apps/docs/content/docs/en/core/functions/formatting/meta.json
new file mode 100644
index 000000000..0ffd4b92f
--- /dev/null
+++ b/apps/docs/content/docs/en/core/functions/formatting/meta.json
@@ -0,0 +1,4 @@
+{
+  "title": "Formatting",
+  "pages": ["./formatDateTime", "./formatMessage", "./formatNum"]
+}
diff --git a/apps/docs/content/docs/en/core/functions/locales/determineLocale.mdx b/apps/docs/content/docs/en/core/functions/locales/determineLocale.mdx
new file mode 100644
index 000000000..53ed58425
--- /dev/null
+++ b/apps/docs/content/docs/en/core/functions/locales/determineLocale.mdx
@@ -0,0 +1,76 @@
+---
+title: determineLocale()
+description: API Reference for the determineLocale function
+---
+
+## Overview
+
+The `determineLocale()` function determines the best matching locale from approved locales based on user preferences without requiring a GT class instance.
+
+---
+
+## Reference
+
+### Parameters
+
+<TypeTable
+  type={{
+    "locales": {
+      type: 'string | string[]',
+      optional: false,
+    },
+    "approvedLocales?": {
+      type: 'string[]',
+      optional: true,
+      default: '[]'
+    },
+    "customMapping?": {
+      type: 'CustomMapping',
+      optional: true,
+    }
+  }}
+/>
+
+### Returns
+
+`string | undefined` - Best matching locale or undefined if no match
+
+---
+
+## Examples
+
+### Content Negotiation
+
+```typescript
+import { determineLocale } from 'generaltranslation';
+
+const approvedLocales = ['en-US', 'es-ES', 'fr-FR', 'de-DE'];
+
+// Exact match
+console.log(determineLocale('en-US', approvedLocales)); // 'en-US'
+
+// Language fallback
+console.log(determineLocale('en-GB', approvedLocales)); // 'en-US'
+
+// Multiple preferences
+console.log(determineLocale(['fr-CA', 'es-MX'], approvedLocales)); // 'es-ES'
+
+// No match
+console.log(determineLocale('it-IT', approvedLocales)); // undefined
+```
+
+---
+
+## Notes
+
+- Implements intelligent locale negotiation
+- Returns first exact or language match from approved list
+- Respects preference order in input array
+- Returns undefined when no match found
+- Essential for web application locale negotiation
+
+## Next Steps
+
+- Use GT class method [`determineLocale()`](/docs/core/class/methods/locales/determineLocale)
+- Check translation needs with [`requiresTranslation()`](/docs/core/functions/locales/requiresTranslation)
+- Validate locales with [`isValidLocale()`](/docs/core/functions/locales/isValidLocale)
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/core/functions/locales/getLocaleDirection.mdx b/apps/docs/content/docs/en/core/functions/locales/getLocaleDirection.mdx
new file mode 100644
index 000000000..e090005ec
--- /dev/null
+++ b/apps/docs/content/docs/en/core/functions/locales/getLocaleDirection.mdx
@@ -0,0 +1,118 @@
+---
+title: getLocaleDirection()
+description: API Reference for the getLocaleDirection function
+---
+
+## Overview
+
+The `getLocaleDirection()` function determines the text direction (left-to-right or right-to-left) for a locale without requiring a GT class instance.
+It uses the `Intl.Locale` API to provide accurate direction detection for any valid BCP-47 locale code.
+
+This function is most often used to set the `dir` attribute of a HTML element based on the locale.
+
+```typescript
+import { getLocaleDirection } from 'generaltranslation';
+
+const direction = getLocaleDirection('ar-SA');
+console.log(direction); // "rtl"
+
+const englishDirection = getLocaleDirection('en-US');
+console.log(englishDirection); // "ltr"
+```
+
+---
+
+## Reference
+
+### Parameters
+
+<TypeTable
+  type={{
+    "locale": {
+      type: 'string',
+      optional: false,
+    }
+  }}
+/>
+
+### Parameters Description
+
+| Parameter | Description |
+|-----------|-------------|
+| `locale` | BCP-47 locale code to check text direction for |
+
+### Returns
+
+`'ltr' | 'rtl'` - Text direction for the locale:
+- `'ltr'`: Left-to-right (most languages including English, Spanish, French, German, Chinese, Japanese, etc.)
+- `'rtl'`: Right-to-left (Arabic, Hebrew, Persian, Urdu, and other Semitic/Middle Eastern languages)
+
+---
+
+## Behavior
+
+### Direction Detection Algorithm
+
+The function uses the `Intl.Locale` API's `textInfo.direction` property:
+1. Creates an `Intl.Locale` object for the provided locale
+2. Accesses the `textInfo.direction` property for language-specific direction
+3. Returns `'rtl'` for right-to-left languages, `'ltr'` for all others
+4. Defaults to `'ltr'` if the locale is invalid or causes an error
+
+### RTL Language Recognition
+
+Automatically detects RTL languages including:
+- **Arabic** (`ar`, `ar-SA`, `ar-EG`, `ar-AE`, etc.)
+- **Hebrew** (`he`, `he-IL`)
+- **Persian/Farsi** (`fa`, `fa-IR`)
+- **Urdu** (`ur`, `ur-PK`, `ur-IN`)
+- **Pashto** (`ps`)
+- **Sindhi** (`sd`)
+- **Kurdish Sorani** (`ckb`)
+- And other RTL scripts
+
+### Error Handling
+
+- Invalid or malformed locale codes default to `'ltr'`
+- No exceptions thrown for invalid input
+- Robust fallback behavior for edge cases
+
+---
+
+## Examples
+
+### Basic Direction Detection
+
+```typescript
+import { getLocaleDirection } from 'generaltranslation';
+
+// Left-to-right languages
+console.log(getLocaleDirection('en-US')); // "ltr"
+console.log(getLocaleDirection('es-ES')); // "ltr"
+console.log(getLocaleDirection('fr-FR')); // "ltr"
+console.log(getLocaleDirection('ja-JP')); // "ltr"
+console.log(getLocaleDirection('zh-CN')); // "ltr"
+
+// Right-to-left languages
+console.log(getLocaleDirection('ar-SA')); // "rtl"
+console.log(getLocaleDirection('he-IL')); // "rtl"
+console.log(getLocaleDirection('fa-IR')); // "rtl"
+console.log(getLocaleDirection('ur-PK')); // "rtl"
+```
+
+---
+
+## Notes
+
+- Returns `'ltr'` for all left-to-right languages (most languages worldwide)
+- Returns `'rtl'` for right-to-left languages (Arabic, Hebrew, Persian, etc.)
+- Uses the modern `Intl.Locale` API for accurate detection
+- Works with all BCP-47 locale codes
+
+## Next Steps
+
+- Use GT class method [`getLocaleDirection()`](/docs/core/class/methods/locales/getLocaleDirection)
+- Get locale properties with [`getLocaleProperties()`](/docs/core/functions/locales/getLocaleProperties)
+- Validate locales with [`isValidLocale()`](/docs/core/functions/locales/isValidLocale)
+- Get locale emoji with [`getLocaleEmoji()`](/docs/core/functions/locales/getLocaleEmoji)
+- Check out the supported locales [here](/docs/platform/locale-strings)
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/core/functions/locales/getLocaleEmoji.mdx b/apps/docs/content/docs/en/core/functions/locales/getLocaleEmoji.mdx
new file mode 100644
index 000000000..69753cc55
--- /dev/null
+++ b/apps/docs/content/docs/en/core/functions/locales/getLocaleEmoji.mdx
@@ -0,0 +1,92 @@
+---
+title: getLocaleEmoji()
+description: API Reference for the standalone getLocaleEmoji function
+---
+
+## Overview
+
+The standalone `getLocaleEmoji()` function retrieves an emoji flag or symbol for a locale code without requiring a GT class instance.
+It returns appropriate flag emojis for countries and territories based on the locale's region, with support for custom emoji mappings.
+
+```typescript
+import { getLocaleEmoji } from 'generaltranslation';
+
+const emoji = getLocaleEmoji('fr-CA');
+console.log(emoji); // "🇨🇦" (Canadian flag)
+
+const usEmoji = getLocaleEmoji('en-US');
+console.log(usEmoji); // "🇺🇸" (US flag)
+```
+
+---
+
+## Reference
+
+### Parameters
+
+<TypeTable
+  type={{
+    "locale": {
+      type: 'string',
+      optional: false,
+    },
+    "customMapping?": {
+      type: 'CustomMapping',
+      optional: true,
+    }
+  }}
+/>
+
+### Parameters Description
+
+| Parameter | Description |
+|-----------|-------------|
+| `locale` | BCP-47 locale code to get emoji for |
+| `customMapping` | Optional custom mapping for locale codes and emoji overrides |
+
+### Returns
+
+`string` - Emoji flag or symbol representing the locale:
+- Country/territory flag emoji for locales with regions (e.g., `🇺🇸`, `🇫🇷`, `🇯🇵`)
+- Custom emoji if defined in mapping
+- Default flag emoji (`🏳️`) for unrecognized locales
+
+
+---
+
+## Examples
+
+### Basic Emoji Retrieval
+
+```typescript
+import { getLocaleEmoji } from 'generaltranslation';
+
+// Common country flags
+console.log(getLocaleEmoji('en-US')); // "🇺🇸"
+console.log(getLocaleEmoji('fr-FR')); // "🇫🇷"
+console.log(getLocaleEmoji('de-DE')); // "🇩🇪"
+console.log(getLocaleEmoji('ja-JP')); // "🇯🇵"
+console.log(getLocaleEmoji('zh-CN')); // "🇨🇳"
+
+// Regions with multiple languages
+console.log(getLocaleEmoji('en-CA')); // "🇨🇦"
+console.log(getLocaleEmoji('fr-CA')); // "🇨🇦"
+console.log(getLocaleEmoji('de-CH')); // "🇨🇭"
+console.log(getLocaleEmoji('fr-CH')); // "🇨🇭"
+```
+
+---
+
+## Notes
+
+- Returns flag emojis using Unicode Regional Indicator Symbols
+- Custom mapping emojis take priority over region-based selection
+- Supports all ISO 3166-1 alpha-2 region codes for comprehensive coverage
+
+## Next Steps
+
+- Use GT class method [`getLocaleEmoji()`](/docs/core/class/methods/locales/getLocaleEmoji)
+- Get locale properties with [`getLocaleProperties()`](/docs/core/functions/locales/getLocaleProperties)
+- Get locale names with [`getLocaleName()`](/docs/core/functions/locales/getLocaleName)
+- Validate locales with [`isValidLocale()`](/docs/core/functions/locales/isValidLocale)
+- Learn about [`CustomMapping` type](/docs/core/types/CustomMapping)
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/core/functions/locales/getLocaleName.mdx b/apps/docs/content/docs/en/core/functions/locales/getLocaleName.mdx
new file mode 100644
index 000000000..5537b65ca
--- /dev/null
+++ b/apps/docs/content/docs/en/core/functions/locales/getLocaleName.mdx
@@ -0,0 +1,134 @@
+---
+title: getLocaleName()
+description: API Reference for the standalone getLocaleName function
+---
+
+## Overview
+
+The standalone `getLocaleName()` function retrieves the display name of a locale code without requiring a GT class instance.
+It uses the `Intl.DisplayNames` API to provide localized locale names for any valid BCP-47 locale code.
+
+```typescript
+import { getLocaleName } from 'generaltranslation';
+
+const name = getLocaleName('fr-CA', 'en');
+console.log(name); // "French (Canada)"
+```
+
+---
+
+## Reference
+
+### Parameters
+
+<TypeTable
+  type={{
+    "locale": {
+      type: 'string',
+      optional: false,
+    },
+    "defaultLocale?": {
+      type: 'string',
+      optional: true,
+    },
+    "customMapping?": {
+      type: 'CustomMapping',
+      optional: true,
+    }
+  }}
+/>
+
+### Parameters Description
+
+| Parameter | Description |
+|-----------|-------------|
+| `locale` | BCP-47 locale code to get the display name for |
+| `defaultLocale` | Locale to use for localizing the display name (defaults to 'en') |
+| `customMapping` | Optional custom mapping for locale codes and names |
+
+### Returns
+
+`string` - The localized display name of the locale.
+
+---
+
+## Behavior
+
+### Display Language Resolution
+
+The function localizes names using this priority:
+1. `defaultLocale` parameter (if provided)
+2. Library default locale ('en')
+
+### Custom Mapping Integration
+
+- Custom mappings are checked first for both locale codes and names
+- Supports alias resolution and custom display names
+- Falls back to standard Intl.DisplayNames for unmapped codes
+
+### Name Resolution Strategy
+
+1. **Custom mapping name** (highest priority)
+2. **Intl.DisplayNames** in default locale
+3. **Intl.DisplayNames** in library default ('en')
+4. **Locale code itself** (fallback)
+
+---
+
+## Examples
+
+```typescript
+import { getLocaleName } from 'generaltranslation';
+
+// English display names
+console.log(getLocaleName('es', 'en')); // "Spanish (Spain)"
+console.log(getLocaleName('ja', 'en')); // "Japanese (Japan)"
+console.log(getLocaleName('zh', 'en')); // "Chinese (China)"
+```
+
+### Building Locale Options
+
+```typescript
+import { getLocaleName, getLocaleEmoji } from 'generaltranslation';
+
+function buildLocaleOptions(
+  supportedLocales: string[],
+  displayLocale: string = 'en'
+) {
+  return supportedLocales.map(locale => ({
+    value: locale,
+    label: getLocaleName(locale, displayLocale),
+    emoji: getLocaleEmoji(locale)
+  }));
+}
+
+const options = buildLocaleOptions([
+  'en',
+  'es',
+  'fr',
+  'de',
+  'ja'
+], 'en');
+
+console.log(options);
+// [
+//   { value: 'en', label: 'English (United States)', emoji: '🇺🇸' },
+//   { value: 'es', label: 'Spanish (Spain)', emoji: '🇪🇸' },
+//   ...
+// ]
+```
+
+---
+
+## Notes
+
+- Custom mappings take precedence over standard Intl.DisplayNames
+- Returns the locale code itself if no display name can be determined
+- Display locale parameter determines the language of the returned name
+
+## Next Steps
+
+- Get locale emoji with [`getLocaleEmoji()`](/docs/core/functions/locales/getLocaleEmoji)
+- Use GT class method for stateful operations [`getLocaleName()`](/docs/core/class/methods/locales/getLocaleName)
+- Learn about [`CustomMapping` type](/docs/core/types/CustomMapping)
+- Validate locales with [`isValidLocale()`](/docs/core/functions/locales/isValidLocale)
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/core/functions/locales/getLocaleProperties.mdx b/apps/docs/content/docs/en/core/functions/locales/getLocaleProperties.mdx
new file mode 100644
index 000000000..3fbb14751
--- /dev/null
+++ b/apps/docs/content/docs/en/core/functions/locales/getLocaleProperties.mdx
@@ -0,0 +1,118 @@
+---
+title: getLocaleProperties()
+description: API Reference for the standalone getLocaleProperties function
+---
+
+## Overview
+
+The standalone `getLocaleProperties()` function retrieves properties for a locale code without requiring a GT class instance.
+It provides detailed information including display names, region codes, script information, and emoji flags in a complete `LocaleProperties` object.
+
+```typescript
+import { getLocaleProperties } from 'generaltranslation';
+
+const props = getLocaleProperties('fr-CA', 'en');
+console.log(props.name); // "French (Canada)"
+console.log(props.nativeName); // "français (Canada)"
+console.log(props.emoji); // "🇨🇦"
+console.log(props.regionCode); // "CA"
+```
+
+---
+
+## Reference
+
+### Parameters
+
+<TypeTable
+  type={{
+    "locale": {
+      type: 'string',
+      optional: false,
+    },
+    "defaultLocale?": {
+      type: 'string',
+      optional: true,
+    },
+    "customMapping?": {
+      type: 'CustomMapping',
+      optional: true,
+    }
+  }}
+/>
+
+### Parameters Description
+
+| Parameter | Description |
+|-----------|-------------|
+| `locale` | BCP-47 locale code to get properties for |
+| `defaultLocale` | Locale to use for localizing display names (defaults to 'en') |
+| `customMapping` | Optional custom mapping for locale codes and properties |
+
+### Returns
+
+`LocaleProperties` - A comprehensive object containing all locale information:
+
+- `code`: Standardized locale code
+- `name`: Display name in default locale
+- `nativeName`: Display name in the locale itself
+- `languageCode`, `languageName`, `nativeLanguageName`: Language information
+- `regionCode`, `regionName`, `nativeRegionName`: Region information  
+- `scriptCode`, `scriptName`, `nativeScriptName`: Script information
+- `maximizedCode`, `minimizedCode`: Canonical forms
+- `nameWithRegionCode`, `nativeNameWithRegionCode`: Combined display formats
+- `emoji`: Flag or representative emoji
+
+---
+
+## Behavior
+
+### Custom Mapping Integration
+
+- Custom mappings are checked first for all properties
+- Supports alias resolution and property overrides
+- Falls back to standard Intl APIs for unmapped codes
+- Canonical locale resolution for aliased locales
+
+---
+
+## Examples
+
+```typescript
+import { getLocaleProperties } from 'generaltranslation';
+
+// English display names
+const enProps = getLocaleProperties('es-MX', 'en');
+console.log(enProps.name); // "Spanish (Mexico)"
+console.log(enProps.languageName); // "Spanish"
+console.log(enProps.regionName); // "Mexico"
+console.log(enProps.emoji); // "🇲🇽"
+
+// French display names
+const frProps = getLocaleProperties('es-MX', 'fr');
+console.log(frProps.name); // "espagnol (Mexique)"
+console.log(frProps.languageName); // "espagnol"
+console.log(frProps.regionName); // "Mexique"
+
+// Native names are always in the target locale
+console.log(enProps.nativeName); // "español (México)"
+console.log(frProps.nativeName); // "español (México)"
+```
+
+
+---
+
+## Notes
+
+- Function provides locale data without GT class instantiation
+- Custom mapping properties take precedence over standard Intl APIs  
+- The complete `LocaleProperties` interface is always returned
+- Native names are always computed in the target locale itself
+
+## Next Steps
+
+- Explore [`LocaleProperties` interface](/docs/core/types/LocaleProperties) - Complete interface documentation
+- Use GT class method [`getLocaleProperties()`](/docs/core/class/methods/locales/getLocaleProperties)
+- Get simple locale names with [`getLocaleName()`](/docs/core/functions/locales/getLocaleName)
+- Get locale emoji with [`getLocaleEmoji()`](/docs/core/functions/locales/getLocaleEmoji)
+- Learn about [`CustomMapping` type](/docs/core/types/CustomMapping)
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/core/functions/locales/getRegionProperties.mdx b/apps/docs/content/docs/en/core/functions/locales/getRegionProperties.mdx
new file mode 100644
index 000000000..51e874c08
--- /dev/null
+++ b/apps/docs/content/docs/en/core/functions/locales/getRegionProperties.mdx
@@ -0,0 +1,72 @@
+---
+title: getRegionProperties()
+description: API Reference for the getRegionProperties function
+---
+
+## Overview
+
+The `getRegionProperties()` function retrieves detailed information about a region code without requiring a GT class instance.
+
+---
+
+## Reference
+
+### Parameters
+
+<TypeTable
+  type={{
+    "region": {
+      type: 'string',
+      optional: false,
+    },
+    "defaultLocale?": {
+      type: 'string',
+      optional: true,
+    },
+    "customMapping?": {
+      type: 'CustomRegionMapping',
+      optional: true,
+    }
+  }}
+/>
+
+### Returns
+
+`{ code: string; name: string; emoji: string }` - Region information object
+
+---
+
+## Examples
+
+
+```typescript
+import { getRegionProperties } from 'generaltranslation';
+
+// Get region properties with English names
+console.log(getRegionProperties('US', 'en-US'));
+// { code: 'US', name: 'United States', emoji: '🇺🇸' }
+
+console.log(getRegionProperties('JP', 'en-US'));
+// { code: 'JP', name: 'Japan', emoji: '🇯🇵' }
+
+// Get region properties with localized names
+console.log(getRegionProperties('US', 'de-DE'));
+// { code: 'US', name: 'Vereinigte Staaten', emoji: '🇺🇸' }
+```
+
+
+---
+
+## Notes
+
+- Uses `Intl.DisplayNames` API for localized region names
+- Supports ISO 3166-1 alpha-2 and UN M.49 region codes
+- Custom mappings can override default names and emojis
+- Falls back to region code if display name resolution fails
+- No external dependencies beyond browser APIs
+
+## Next Steps
+
+- Use GT class method [`getRegionProperties()`](/docs/core/class/methods/locales/getRegionProperties)
+- Get full locale info with [`getLocaleProperties()`](/docs/core/functions/locales/getLocaleProperties)
+- Get locale emoji with [`getLocaleEmoji()`](/docs/core/functions/locales/getLocaleEmoji)
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/core/functions/locales/isSameDialect.mdx b/apps/docs/content/docs/en/core/functions/locales/isSameDialect.mdx
new file mode 100644
index 000000000..1bc490d8d
--- /dev/null
+++ b/apps/docs/content/docs/en/core/functions/locales/isSameDialect.mdx
@@ -0,0 +1,59 @@
+---
+title: isSameDialect()
+description: API Reference for the isSameDialect function
+---
+
+## Overview
+
+The `isSameDialect()` function checks if multiple BCP-47 locale codes represent the same dialect without requiring a GT class instance.
+
+
+---
+
+## Reference
+
+### Parameters
+
+<TypeTable
+  type={{
+    "...locales": {
+      type: '(string | string[])[]',
+      optional: false,
+    }
+  }}
+/>
+
+### Returns
+
+`boolean` - `true` if all locale codes represent the same dialect
+
+---
+
+## Examples
+
+```typescript
+import { isSameDialect } from 'generaltranslation';
+
+// Same dialect checks
+console.log(isSameDialect('en-US', 'en-US')); // true
+console.log(isSameDialect('en', 'en-US')); // true (base language matches regional)
+console.log(isSameDialect('en-US', 'en-GB')); // false (different regions)
+console.log(isSameDialect('en-US', 'es-ES')); // false (different languages)
+```
+
+
+---
+
+## Notes
+
+- Considers base languages as parents of regional variants
+- Regional variants must match exactly
+- Essential for locale fallback logic
+- Accepts flexible input formats
+- No external dependencies
+
+## Next Steps
+
+- Use GT class method [`isSameDialect()`](/docs/core/class/methods/locales/isSameDialect)
+- Compare languages with [`isSameLanguage()`](/docs/core/functions/locales/isSameLanguage)
+- Check hierarchy with [`isSupersetLocale()`](/docs/core/functions/locales/isSupersetLocale)
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/core/functions/locales/isSameLanguage.mdx b/apps/docs/content/docs/en/core/functions/locales/isSameLanguage.mdx
new file mode 100644
index 000000000..73755ee86
--- /dev/null
+++ b/apps/docs/content/docs/en/core/functions/locales/isSameLanguage.mdx
@@ -0,0 +1,60 @@
+---
+title: isSameLanguage()
+description: API Reference for the isSameLanguage function
+---
+
+## Overview
+
+The `isSameLanguage()` function checks if multiple BCP-47 locale codes represent the same base language, ignoring regional differences.
+
+---
+
+## Reference
+
+### Parameters
+
+<TypeTable
+  type={{
+    "...locales": {
+      type: '(string | string[])[]',
+      optional: false,
+    }
+  }}
+/>
+
+### Returns
+
+`boolean` - `true` if all locale codes represent the same base language
+
+---
+
+## Examples
+
+
+```typescript
+import { isSameLanguage } from 'generaltranslation';
+
+// Same language, different regions
+console.log(isSameLanguage('en-US', 'en-GB')); // true
+console.log(isSameLanguage('es-ES', 'es-MX')); // true
+console.log(isSameLanguage('zh-CN', 'zh-TW')); // true
+
+// Different languages
+console.log(isSameLanguage('en-US', 'es-ES')); // false
+console.log(isSameLanguage('fr-FR', 'de-DE')); // false
+```
+
+---
+
+## Notes
+
+- Compares only base language codes (before first hyphen)
+- Ignores regional, script, and variant differences
+- Essential for language-based content organization
+- Works with variable number of parameters
+
+## Next Steps
+
+- Use GT class method [`isSameLanguage()`](/docs/core/class/methods/locales/isSameLanguage)
+- Compare dialects with [`isSameDialect()`](/docs/core/functions/locales/isSameDialect)
+- Check requirements with [`requiresTranslation()`](/docs/core/functions/locales/requiresTranslation)
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/core/functions/locales/isSupersetLocale.mdx b/apps/docs/content/docs/en/core/functions/locales/isSupersetLocale.mdx
new file mode 100644
index 000000000..bc5e1b76c
--- /dev/null
+++ b/apps/docs/content/docs/en/core/functions/locales/isSupersetLocale.mdx
@@ -0,0 +1,65 @@
+---
+title: isSupersetLocale()
+description: API Reference for the isSupersetLocale function
+---
+
+## Overview
+
+The `isSupersetLocale()` function checks if one locale is a superset of another in the BCP-47 hierarchy without requiring a GT class instance.
+
+---
+
+## Reference
+
+### Parameters
+
+<TypeTable
+  type={{
+    "superLocale": {
+      type: 'string',
+      optional: false,
+    },
+    "subLocale": {
+      type: 'string',
+      optional: false,
+    }
+  }}
+/>
+
+### Returns
+
+`boolean` - `true` if superLocale is a superset of subLocale
+
+---
+
+## Examples
+
+
+```typescript
+import { isSupersetLocale } from 'generaltranslation';
+
+// Base language is superset of regional variant
+console.log(isSupersetLocale('en', 'en-US')); // true
+console.log(isSupersetLocale('es', 'es-ES')); // true
+
+// Regional variant is NOT superset of base language
+console.log(isSupersetLocale('en-US', 'en')); // false
+
+// Same locales are supersets of themselves
+console.log(isSupersetLocale('en-US', 'en-US')); // true
+```
+
+---
+
+## Notes
+
+- Uses BCP-47 locale hierarchy
+- Base languages are supersets of regional variants
+- A locale is always a superset of itself
+- Essential for building fallback systems
+
+## Next Steps
+
+- Use GT class method [`isSupersetLocale()`](/docs/core/class/methods/locales/isSupersetLocale)
+- Compare languages with [`isSameLanguage()`](/docs/core/functions/locales/isSameLanguage)
+- Determine best match with [`determineLocale()`](/docs/core/functions/locales/determineLocale)
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/core/functions/locales/isValidLocale.mdx b/apps/docs/content/docs/en/core/functions/locales/isValidLocale.mdx
new file mode 100644
index 000000000..006699855
--- /dev/null
+++ b/apps/docs/content/docs/en/core/functions/locales/isValidLocale.mdx
@@ -0,0 +1,65 @@
+---
+title: isValidLocale()
+description: API Reference for the isValidLocale function
+---
+
+## Overview
+
+The `isValidLocale()` function validates whether a given string represents a valid BCP-47 locale code. It performs comprehensive format validation without requiring a GT class instance.
+
+---
+
+## Reference
+
+### Parameters
+
+<TypeTable
+  type={{
+    "locale": {
+      type: 'string',
+      optional: false,
+    },
+    "customMapping?": {
+      type: 'CustomMapping',
+      optional: true,
+    }
+  }}
+/>
+
+### Returns
+
+`boolean` - `true` if the locale code is valid, `false` otherwise
+
+---
+
+## Examples
+
+```typescript
+import { isValidLocale } from 'generaltranslation';
+
+// Valid locale codes
+console.log(isValidLocale('en-US')); // true
+console.log(isValidLocale('zh-CN')); // true
+console.log(isValidLocale('es')); // true
+
+// Invalid locale codes
+console.log(isValidLocale('invalid')); // false
+console.log(isValidLocale('en_US')); // false (underscore instead of hyphen)
+console.log(isValidLocale('')); // false
+```
+
+---
+
+## Notes
+
+- Validates BCP-47 locale code format
+- Works with custom locale mappings
+- Essential for user input validation
+- No network requests - pure format validation
+- Stateless function suitable for utility libraries
+
+## Next Steps
+
+- Use GT class method [`isValidLocale()`](/docs/core/class/methods/locales/isValidLocale)
+- Standardize format with [`standardizeLocale()`](/docs/core/functions/locales/standardizeLocale)
+- Get locale properties with [`getLocaleProperties()`](/docs/core/functions/locales/getLocaleProperties)
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/core/functions/locales/meta.json b/apps/docs/content/docs/en/core/functions/locales/meta.json
new file mode 100644
index 000000000..d9b18082a
--- /dev/null
+++ b/apps/docs/content/docs/en/core/functions/locales/meta.json
@@ -0,0 +1,19 @@
+{
+  "title": "Locales",
+  "pages": [
+    "./determineLocale",
+    "./getLocaleDirection",
+    "./getLocaleEmoji",
+    "./getLocaleName",
+    "./getLocaleProperties",
+    "./getRegionProperties",
+    "./isSameDialect",
+    "./isSameLanguage",
+    "./isSupersetLocale",
+    "./isValidLocale",
+    "./requiresTranslation",
+    "./resolveAliasLocale",
+    "./resolveCanonicalLocale",
+    "./standardizeLocale"
+  ]
+}
diff --git a/apps/docs/content/docs/en/core/functions/locales/requiresTranslation.mdx b/apps/docs/content/docs/en/core/functions/locales/requiresTranslation.mdx
new file mode 100644
index 000000000..7b337c178
--- /dev/null
+++ b/apps/docs/content/docs/en/core/functions/locales/requiresTranslation.mdx
@@ -0,0 +1,73 @@
+---
+title: requiresTranslation()
+description: API Reference for the requiresTranslation function
+---
+
+## Overview
+
+The `requiresTranslation()` function determines whether translation is needed between source and target locales without requiring a GT class instance.
+
+---
+
+## Reference
+
+### Parameters
+
+<TypeTable
+  type={{
+    "sourceLocale": {
+      type: 'string',
+      optional: false,
+    },
+    "targetLocale": {
+      type: 'string',
+      optional: false,
+    },
+    "approvedLocales?": {
+      type: 'string[]',
+      optional: true,
+    },
+    "customMapping?": {
+      type: 'CustomMapping',
+      optional: true,
+    }
+  }}
+/>
+
+### Returns
+
+`boolean` - `true` if translation is required, `false` otherwise
+
+---
+
+## Examples
+
+```typescript
+import { requiresTranslation } from 'generaltranslation';
+
+// Different languages require translation
+console.log(requiresTranslation('en-US', 'es-ES')); // true
+console.log(requiresTranslation('en-US', 'fr-FR')); // true
+
+// Same languages don't require translation
+console.log(requiresTranslation('en-US', 'en-US')); // false
+console.log(requiresTranslation('en-US', 'en-GB')); // false
+
+// With approved locales filter
+const approved = ['en-US', 'es-ES', 'fr-FR'];
+console.log(requiresTranslation('en-US', 'it-IT', approved)); // false (not approved)
+console.log(requiresTranslation('en-US', 'es-ES', approved)); // true (approved and different)
+```
+---
+
+## Notes
+
+- Respects approved locale constraints
+- Returns false when target not in approved list
+- Considers custom locale mappings
+
+## Next Steps
+
+- Use GT class method [`requiresTranslation()`](/docs/core/class/methods/locales/requiresTranslation)
+- Compare languages with [`isSameLanguage()`](/docs/core/functions/locales/isSameLanguage)
+- Determine best locale with [`determineLocale()`](/docs/core/functions/locales/determineLocale)
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/core/functions/locales/resolveAliasLocale.mdx b/apps/docs/content/docs/en/core/functions/locales/resolveAliasLocale.mdx
new file mode 100644
index 000000000..2f5abd6f6
--- /dev/null
+++ b/apps/docs/content/docs/en/core/functions/locales/resolveAliasLocale.mdx
@@ -0,0 +1,67 @@
+---
+title: resolveAliasLocale()
+description: API Reference for the resolveAliasLocale function
+---
+
+## Overview
+
+The `resolveAliasLocale()` function converts canonical locale codes back to their alias locale codes when custom mapping is configured. This standalone function provides the same functionality as the GT class method without requiring an instance.
+
+
+---
+
+## Reference
+
+### Parameters
+
+<TypeTable
+  type={{
+    "locale": {
+      type: 'string',
+      optional: false,
+    },
+    "customMapping?": {
+      type: 'CustomMapping',
+      optional: true,
+    }
+  }}
+/>
+
+### Returns
+
+`string` - The alias locale code if mapping exists, otherwise the original locale
+
+---
+
+## Examples
+
+```typescript
+import { resolveAliasLocale } from 'generaltranslation';
+
+const customMapping = {
+  'simplified-chinese': { code: 'zh-CN', name: 'Simplified Chinese' },
+  'traditional-chinese': { code: 'zh-TW', name: 'Traditional Chinese' }
+};
+
+// Resolve canonical to alias
+console.log(resolveAliasLocale('zh-CN', customMapping)); // 'simplified-chinese'
+console.log(resolveAliasLocale('zh-TW', customMapping)); // 'traditional-chinese'
+
+// Non-mapped locale returns original
+console.log(resolveAliasLocale('es-ES', customMapping)); // 'es-ES'
+```
+---
+
+## Notes
+
+- Converts canonical locale codes back to user-friendly aliases
+- Returns original locale if no mapping exists
+- Essential for displaying user-facing locale names
+- Works with custom locale mappings
+- Stateless function - no side effects
+
+## Next Steps
+
+- Use GT class method [`resolveAliasLocale()`](/docs/core/class/methods/locales/resolveAliasLocale)
+- Convert to canonical with [`resolveCanonicalLocale()`](/docs/core/functions/locales/resolveCanonicalLocale)
+- Validate with [`isValidLocale()`](/docs/core/functions/locales/isValidLocale)
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/core/functions/locales/standardizeLocale.mdx b/apps/docs/content/docs/en/core/functions/locales/standardizeLocale.mdx
new file mode 100644
index 000000000..98ee23065
--- /dev/null
+++ b/apps/docs/content/docs/en/core/functions/locales/standardizeLocale.mdx
@@ -0,0 +1,83 @@
+---
+title: standardizeLocale()
+description: API Reference for the standardizeLocale function
+---
+
+## Overview
+
+The `standardizeLocale()` function standardizes a BCP-47 locale code to ensure correct formatting and casing without requiring a GT class instance.
+
+```typescript
+import { standardizeLocale } from 'generaltranslation';
+
+// Fix common formatting issues
+console.log(standardizeLocale('en_us')); // 'en-US'
+console.log(standardizeLocale('zh_cn')); // 'zh-CN'
+console.log(standardizeLocale('EN-gb')); // 'en-GB'
+console.log(standardizeLocale('fr-ca')); // 'fr-CA'
+
+// Already standardized locales pass through
+console.log(standardizeLocale('es-ES')); // 'es-ES'
+```
+
+---
+
+## Reference
+
+### Parameters
+
+<TypeTable
+  type={{
+    "locale": {
+      type: 'string',
+      optional: false,
+    }
+  }}
+/>
+
+### Returns
+
+`string` - Standardized BCP-47 locale code or empty string if invalid
+
+---
+
+## Examples
+
+### User Input Processing
+
+```typescript
+import { standardizeLocale, isValidLocale } from 'generaltranslation';
+
+function processUserInput(input: string) {
+  const standardized = standardizeLocale(input.trim());
+  const isValid = isValidLocale(standardized);
+  
+  return {
+    original: input,
+    standardized,
+    isValid
+  };
+}
+
+// Test various inputs
+const inputs = ['en_us', 'FR-ca', 'invalid', 'zh-CN'];
+inputs.forEach(input => {
+  console.log(processUserInput(input));
+});
+```
+
+---
+
+## Notes
+
+- Converts underscores to hyphens
+- Normalizes casing (language lowercase, region uppercase)
+- Returns empty string for invalid formats
+- Essential for normalizing locale input from various sources
+- No external dependencies - pure string manipulation
+
+## Next Steps
+
+- Use GT class method [`standardizeLocale()`](/docs/core/class/methods/locales/standardizeLocale)
+- Validate with [`isValidLocale()`](/docs/core/functions/locales/isValidLocale)
+- Get properties with [`getLocaleProperties()`](/docs/core/functions/locales/getLocaleProperties)
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/core/functions/meta.json b/apps/docs/content/docs/en/core/functions/meta.json
new file mode 100644
index 000000000..d1120349a
--- /dev/null
+++ b/apps/docs/content/docs/en/core/functions/meta.json
@@ -0,0 +1,4 @@
+{
+  "title": "Utility Functions",
+  "pages": ["./formatting", "./locales"]
+}
diff --git a/apps/docs/content/docs/en/core/index.mdx b/apps/docs/content/docs/en/core/index.mdx
index 25aed0120..4b7fe5030 100644
--- a/apps/docs/content/docs/en/core/index.mdx
+++ b/apps/docs/content/docs/en/core/index.mdx
@@ -1,40 +1,227 @@
 ---
-title: Core
-description: Docs for General Translation's core libraries
+title: Overview
+description: Overview of the generaltranslation library
 ---
 
-## Installation
+## Introduction
+
+The `generaltranslation` library serves as GT's core i18n library housing utility functions and classes for translation and formatting.
+It is most oftenly used with framework packages like `gt-next` and `gt-react`, but can be used as a standalone library.
+
+
+import Video from '@/components/Video';
+
+<Video src="/core-demo.mp4" />
+
+```typescript title="index.ts"
+import { GT } from 'generaltranslation';
 
-`gt-next`, `gt-react`, and `gtx-cli` all depend on the `generaltranslation` package.
+const gt = new GT({
+  apiKey: 'your-api-key',
+  projectId: 'your-project-id',
+  sourceLocale: 'en',
+  targetLocale: 'es'
+});
+
+// Translate content
+const result = await gt.translate('Hello, world!', 'es');
+// "¡Hola, mundo!"
+
+// Format numbers, dates, currencies
+const formattedPrice = gt.formatCurrency(29.99, 'USD');
+const formattedDate = gt.formatDateTime(new Date());
+// "$29.99"
+// "9/25/2025"
+
+// Work with locales
+const localeProps = gt.getLocaleProperties('fr-CA');
+const isValid = gt.isValidLocale('de');
+// { language: "fr", region: "CA", ... }
+// true
+```
+
+---
 
-You can also install `generaltranslation` separately.
+## Installation
 
 <Tabs items={['npm', 'yarn', 'bun', 'pnpm']}>
   <Tab value="npm">
   ```bash 
-  npm i generaltranslation
+  npm install generaltranslation
   ``` 
   </Tab>
   <Tab value="yarn">
   ```bash 
-  yarn generaltranslation
+  yarn add generaltranslation
   ```
   </Tab>
 
   <Tab value="bun">
   ```bash 
-  bun generaltranslation
+  bun add generaltranslation
   ```
   </Tab>
   <Tab value="pnpm">
   ```bash 
-  pnpm generaltranslation
+  pnpm add generaltranslation
   ```
   </Tab>
 </Tabs>
 
-## Usage
+---
+
+## Examples
+
+There are two major types of translation: string translation and file translation.
+
+### Setup
+
+To enable translation, you need to provide a project ID and API key.
+Check out the [`constructor`](/docs/core/class/constructor) method for more information.
+
+```typescript
+const gt = new GT({
+  apiKey: 'your-api-key',
+  projectId: 'your-project-id',
+  targetLocale: 'es'
+});
+```
+
+### String Translation
+Check out the [`translate()`](/docs/core/class/methods/translation/translate) method for more information.
+
+```typescript
+try {
+  const result = await gt.translate('Hello, world!');
+  console.log(result); // "¡Hola, mundo!"
+} catch (error) {
+  console.error('Translation failed:', error.message);
+}
+```
+
+
+### File Translation
+
+Files are translated as jobs.
+You launch a job by uploading a file.
+Uploading many files will launch many jobs.
+
+Check out the [`uploadSourceFiles()`](/docs/core/class/methods/translation/uploadSourceFiles)
+and [`checkFileTranslations()`](/docs/core/class/methods/translation/checkFileTranslations) methods for more information.
+
+```typescript
+// Files to upload
+const files = [
+  {
+    source: {
+      fileName: 'src/components/Button.tsx',
+      fileFormat: 'TSX',
+      locale: 'en',
+      content: '...',
+    }
+  }
+];
+
+// Upload source files
+await gt.uploadSourceFiles(files);
+```
+
+
+---
+
+## Table of Contents
+
+### GT Class
+Main class for translation and locale functionality:
+
+- **[Constructor](/docs/core/class/constructor)** - Initialize GT instance with configuration
+- **[setConfig](/docs/core/class/setConfig)** - Update GT instance configuration
+
+#### Translation Methods
+- **[translate](/docs/core/class/methods/translation/translate)** - Core translation functionality
+- **[translateMany](/docs/core/class/methods/translation/translateMany)** - Batch translation
+- **[setupProject](/docs/core/class/methods/translation/setupProject)** - Project initialization
+- **[shouldSetupProject](/docs/core/class/methods/translation/shouldSetupProject)** - Check if project setup is needed
+- **[checkSetupStatus](/docs/core/class/methods/translation/checkSetupStatus)** - Verify project setup
+- **[getProjectData](/docs/core/class/methods/translation/getProjectData)** - Retrieve project information
+- **[uploadSourceFiles](/docs/core/class/methods/translation/uploadSourceFiles)** - Upload files for translation
+- **[enqueueFiles](/docs/core/class/methods/translation/enqueueFiles)** - Queue files for processing
+- **[checkFileTranslations](/docs/core/class/methods/translation/checkFileTranslations)** - Check translation status
+- **[downloadTranslatedFile](/docs/core/class/methods/translation/downloadTranslatedFile)** - Download single translated file
+- **[downloadFileBatch](/docs/core/class/methods/translation/downloadFileBatch)** - Download multiple translated files
+- **[querySourceFile](/docs/core/class/methods/translation/querySourceFile)** - Query source file information
+
+#### Formatting Methods
+- **[formatMessage](/docs/core/class/methods/formatting/formatMessage)** - Internationalized text formatting
+- **[formatNum](/docs/core/class/methods/formatting/formatNum)** - Number formatting
+- **[formatDateTime](/docs/core/class/methods/formatting/formatDateTime)** - Date and time formatting
+
+#### Locale Methods
+- **[getLocaleName](/docs/core/class/methods/locales/getLocaleName)** - Get locale display name
+- **[getLocaleProperties](/docs/core/class/methods/locales/getLocaleProperties)** - Get comprehensive locale information
+- **[getLocaleDirection](/docs/core/class/methods/locales/getLocaleDirection)** - Get text direction for locale
+- **[getLocaleEmoji](/docs/core/class/methods/locales/getLocaleEmoji)** - Get flag emoji for locale
+- **[getRegionProperties](/docs/core/class/methods/locales/getRegionProperties)** - Get region information and properties
+- **[isValidLocale](/docs/core/class/methods/locales/isValidLocale)** - Validate locale code
+- **[resolveAliasLocale](/docs/core/class/methods/locales/resolveAliasLocale)** - Convert canonical locales to aliases
+- **[resolveCanonicalLocale](/docs/core/class/methods/locales/resolveCanonicalLocale)** - Convert alias locales to canonical form
+- **[standardizeLocale](/docs/core/class/methods/locales/standardizeLocale)** - Standardize locale code formatting
+- **[isSameDialect](/docs/core/class/methods/locales/isSameDialect)** - Check if locales represent same dialect
+- **[isSameLanguage](/docs/core/class/methods/locales/isSameLanguage)** - Check if locales represent same language
+- **[isSupersetLocale](/docs/core/class/methods/locales/isSupersetLocale)** - Check locale hierarchy relationships
+- **[determineLocale](/docs/core/class/methods/locales/determineLocale)** - Find best matching locale from preferences
+- **[requiresTranslation](/docs/core/class/methods/locales/requiresTranslation)** - Determine if translation is needed
+
+### Utility Functions
+
+#### Formatting Functions
+- **[formatMessage](/docs/core/functions/formatting/formatMessage)** - Standalone text formatting
+- **[formatNum](/docs/core/functions/formatting/formatNum)** - Standalone number formatting
+- **[formatDateTime](/docs/core/functions/formatting/formatDateTime)** - Standalone date/time formatting
+
+#### Locale Functions
+- **[getLocaleName](/docs/core/functions/locales/getLocaleName)** - Standalone locale name utility
+- **[getLocaleProperties](/docs/core/functions/locales/getLocaleProperties)** - Standalone locale properties
+- **[getLocaleDirection](/docs/core/functions/locales/getLocaleDirection)** - Standalone text direction utility
+- **[getLocaleEmoji](/docs/core/functions/locales/getLocaleEmoji)** - Standalone emoji utility
+- **[getRegionProperties](/docs/core/functions/locales/getRegionProperties)** - Standalone region properties utility
+- **[isValidLocale](/docs/core/functions/locales/isValidLocale)** - Standalone locale validation
+- **[resolveAliasLocale](/docs/core/functions/locales/resolveAliasLocale)** - Standalone alias locale resolution
+- **[standardizeLocale](/docs/core/functions/locales/standardizeLocale)** - Standalone locale standardization
+- **[isSameDialect](/docs/core/functions/locales/isSameDialect)** - Standalone dialect comparison
+- **[isSameLanguage](/docs/core/functions/locales/isSameLanguage)** - Standalone language comparison
+- **[isSupersetLocale](/docs/core/functions/locales/isSupersetLocale)** - Standalone locale hierarchy checking
+- **[determineLocale](/docs/core/functions/locales/determineLocale)** - Standalone locale negotiation
+- **[requiresTranslation](/docs/core/functions/locales/requiresTranslation)** - Standalone translation requirement checking
+
+### Types and Interfaces
+TypeScript definitions:
+
+- **[GTConstructorParams](/docs/core/types/GTConstructorParams)** - Configuration options
+- **[LocaleProperties](/docs/core/types/LocaleProperties)** - Comprehensive locale information
+- **[TranslationResult](/docs/core/types/TranslationResult)** - Translation response types
+- **[TranslateManyResult](/docs/core/types/TranslateManyResult)** - Batch translation response
+- **[FileToTranslate](/docs/core/types/FileToTranslate)** - File translation configuration
+- **[EnqueueFilesOptions](/docs/core/types/EnqueueFilesOptions)** - File queuing options
+- **[Entry](/docs/core/types/Entry)** - Translation entry structure
+- **[EntryMetadata](/docs/core/types/EntryMetadata)** - Entry metadata information
+- **[Content](/docs/core/types/Content)** - Content type definitions
+- **[Variable](/docs/core/types/Variable)** - Variable structure
+- **[VariableType](/docs/core/types/VariableType)** - Variable type definitions
+- **[JsxElement](/docs/core/types/JsxElement)** - JSX element type
+- **[JsxChild](/docs/core/types/JsxChild)** - JSX child type
+- **[JsxChildren](/docs/core/types/JsxChildren)** - JSX children type
+- **[DataFormat](/docs/core/types/DataFormat)** - Data format specifications
+- **[CustomMapping](/docs/core/types/CustomMapping)** - Custom mapping configuration
+
+---
+
+## Next Steps
 
-import Construction from "@/components/mdx/construction";
+- **[Get started with the GT class](/docs/core/class/constructor)**
+- **[Explore translation methods](/docs/core/class/methods/translation/translate)**
+- **[Learn about locale utilities](/docs/core/class/methods/locales/getLocaleName)**
+- **[Check out formatting options](/docs/core/class/methods/formatting/formatMessage)**
+- **[Browse standalone functions](/docs/core/functions/formatting/formatMessage)**
 
-<Construction />
+For framework-specific usage, see the [Next.js](/docs/next) or [React](/docs/react) documentation.
diff --git a/apps/docs/content/docs/en/core/meta.json b/apps/docs/content/docs/en/core/meta.json
index 64ac7abaa..67e899f1d 100644
--- a/apps/docs/content/docs/en/core/meta.json
+++ b/apps/docs/content/docs/en/core/meta.json
@@ -3,5 +3,13 @@
   "description": "generaltranslation",
   "icon": "Network",
   "root": true,
-  "pages": ["index"]
+  "pages": [
+    "---Getting Started---",
+    "index",
+    "quickstart",
+    "---API---",
+    "class",
+    "functions",
+    "types"
+  ]
 }
diff --git a/apps/docs/content/docs/en/core/quickstart.mdx b/apps/docs/content/docs/en/core/quickstart.mdx
new file mode 100644
index 000000000..416bb1917
--- /dev/null
+++ b/apps/docs/content/docs/en/core/quickstart.mdx
@@ -0,0 +1,240 @@
+---
+title: Quickstart
+description: Quick Start guide for the generaltranslation library
+---
+
+## Overview
+
+This guide will walk you through the basics of using the generaltranslation library.
+We will cover string translation and file translation.
+
+---
+
+
+## Translate your first string
+
+<Steps>
+  <Step>
+
+    ### 1. Get your environment variables
+
+    The very first step is to create a `GT_PROJECT_ID` and `GT_API_KEY`.
+    This is completely free, and will give you access to the translation services.
+
+
+    Navigate to the [`API Keys` page](https://dash.generaltranslation.com/api-keys) click `Create API Key`.
+    Choose a name for your API key, and click `Create`.
+
+    ![API key page](/core/quickstart/core-quickstart-1.png)
+
+    <Callout type='info'>
+      General Translation offers very high free rate limits to support personal projects, solo developers, and the community.
+    </Callout>
+  </Step>
+  <Step>
+    ### 2. Initialize the GT class
+
+    Initialize the [`GT`](/docs/core/class/constructor) class and securely pass your `GT_PROJECT_ID` and `GT_API_KEY`.
+
+    ```typescript title="src/index.ts"
+    import { GT } from 'generaltranslation';
+
+    const gt = new GT({
+      projectId: 'your-project-id',
+      apiKey: 'your-api-key',
+    });
+    ```
+  </Step>
+  <Step>
+    ### 3. Translate your first string
+
+    Call the [`translate()`](/docs/core/class/methods/translation/translate) method to translate your string.
+    Pass the string you want to translate, and the target locale.
+
+    ```typescript title="src/index.ts"
+    const { translation } = await gt.translate('Hello, world!', 'es'); // Spanish
+
+    console.log(translation); // "¡Hola, mundo!"
+    ```
+
+    <Callout type='info'>
+      If you want to look up a locale code, check out the [supported locales](/docs/platform/locale-strings) page.
+    </Callout>
+  </Step>
+</Steps>
+
+---
+
+## Translate your first file
+<Callout type='warn'>
+  This guide assumes you already have followed steps 1 and 2 of the [Translate your first string](/docs/core/quickstart#translate-your-first-string) guide
+  and have a `GT_PROJECT_ID`, `GT_API_KEY`, and a `GT` class instance.
+</Callout>
+
+Let's say you wanted to translate a file called `en.json` to Spanish.
+```json title="en.json"
+{
+  "hello": "Hello",
+  "world": "World"
+}
+```
+
+In order to translate a file, you need to follow these four steps:
+1. Upload the file
+2. Enqueue the file for translation
+3. Check on the file status (optional)
+3. Download the translated file.
+
+<Callout type='info'>
+  #### Why not just one call?
+  Typically, people will want to translate many files at once.
+  By breaking these into four clear steps, it gives users much more flexibility in how they can use the API.
+</Callout>
+
+
+<Steps>
+  <Step>
+    ### 1. Upload the file
+
+    Uploading files returns a list of file references with the [`uploadSourceFiles()`](/docs/core/class/methods/translation/uploadSourceFiles) method.
+    This allows you to later check the enqueue the file for translation, check the status of the file, and download the translated file.
+
+    ```typescript title="src/index.ts"
+    import fs from 'fs';
+    import path from 'path';
+    import { FileUpload } from 'generaltranslation';
+
+    // (i) Read the content of a file
+    const filePath = path.join(process.cwd(), 'en.json');
+    const fileContents = fs.readFileSync(filePath, 'utf8');
+
+    // (ii) Format the file contents
+    const fileUpload: FileUpload = {
+      content: fileContents,
+      fileName: filePath,
+      fileFormat: 'JSON',
+      locale: 'en',
+    };
+    const files = [ { source: fileUpload } ];
+
+    // (iii) Upload the file
+    const { uploadedFiles } = await gt.uploadSourceFiles(
+      files,
+      {
+        sourceLocale: 'en'
+      }
+    );
+    ```
+
+    This will return a list of file references:
+
+    ```ts title="Output"
+    [
+      {
+        fileId: '41726368696562616c64204d6342616c64792074686973206973206a6f6b652e',
+        versionId: '427269616e204c6f75206d6f7265206c696b65204c696f6e2042726f20686121',
+        fileName: '/Users/demo/en.json',
+        fileFormat: 'JSON'
+      }
+    ]
+    ```
+
+  </Step>
+  <Step>
+
+    ### 2. Enqueue the file for translation
+
+    The next step is to select the target locales for the translation with the [`enqueueFiles()`](/docs/core/class/methods/translation/enqueueFiles) method.
+    In this case, we will translate to Spanish.
+
+    ```typescript title="src/index.ts"
+    const fileUploadRef = {
+      fileId: uploadedFiles[0].fileId,
+      versionId: uploadedFiles[0].versionId,
+      fileName: uploadedFiles[0].fileName,
+      fileFormat: uploadedFiles[0].fileFormat,
+    };
+    const enqueueResult = await gt.enqueueFiles(
+      [fileUploadRef],
+      {
+      sourceLocale: 'en',
+      targetLocales: ['es'],
+    });
+    ```
+    This will return a list of file references:
+
+    ```ts title="Output"
+    {
+      translations: [],
+      data: {
+        '41726368696562616c64204d6342616c64792074686973206973206a6f6b652e': {
+          fileName: '/Users/demo/en.json',
+          versionId: '427269616e204c6f75206d6f7265206c696b65204c696f6e2042726f20686121'
+        }
+      },
+      locales: [ 'es' ],
+      message: 'Creating 1 translation(s).'
+    }
+    ```
+
+  </Step>
+  <Step>
+    ### 3. Check on the file status
+
+    Okay, now that the file is uploaded, when do we know it's ready for download?
+    We can use the [`checkFileTranslations()`](/docs/core/class/methods/translation/checkFileTranslations) method to check on the file status.
+
+    ```typescript title="src/index.ts"
+    const status = await gt.checkFileTranslations([{
+      versionId: uploadedFiles[0].versionId,
+      fileName: uploadedFiles[0].fileName,
+      locale: 'es'
+    }]);
+    ```
+
+    If the file is still being translated, there will be no corresponding translations in the output.
+
+    ```ts title="Output"
+    {
+      translations: [
+        {
+          locale: 'es',
+          metadata: {},
+          fileId: '41726368696562616c64204d6342616c64792074686973206973206a6f6b652e',
+          fileName: '/Users/demo/en.json',
+          versionId: '427269616e204c6f75206d6f7265206c696b65204c696f6e2042726f20686121',
+          id: 'skl44z0ieuvdcomw38zb5chv',
+          isReady: true,
+          downloadUrl: '/v2/project/translations/files/skl44z0ieuvdcomw38zb5chv/download'
+        }
+      ]
+    }
+    ```
+
+
+
+  </Step>
+  <Step>
+    ### 4. Download the translated file
+
+    Finally, we can download the translated file with the [`downloadTranslatedFile()`](/docs/core/class/methods/translation/downloadTranslatedFile) method.
+
+    ```typescript title="src/index.ts"
+    const { translation } = await gt.downloadTranslatedFile({
+      fileId: uploadedFiles[0].fileId,
+      locale: 'es',
+      versionId: uploadedFiles[0].versionId,
+    });
+
+    ```
+
+    This will return the translated file content:
+
+    ```ts title="Output"
+    {
+      "hello": "Hola",
+      "world": "Mundo"
+    }
+    ```
+  </Step>
+</Steps>
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/core/types/Content.mdx b/apps/docs/content/docs/en/core/types/Content.mdx
new file mode 100644
index 000000000..0e72fb891
--- /dev/null
+++ b/apps/docs/content/docs/en/core/types/Content.mdx
@@ -0,0 +1,61 @@
+---
+title: Content
+description: Union type representing all supported content formats for translation
+---
+
+## Overview
+
+`Content` represents all supported content formats for translation.
+
+```typescript
+type Content = JsxChildren | IcuMessage | I18nextMessage;
+```
+
+## Type Definition
+
+### Union Members
+
+| Type | Description | Use Case |
+|------|-------------|----------|
+| `JsxChildren` | Rich JSX content with elements and variables | React components, structured HTML content |
+| `IcuMessage` | ICU MessageFormat strings | Complex pluralization, date/number formatting |
+| `I18nextMessage` | i18next compatible message strings | Simple interpolation, existing i18next projects |
+
+---
+
+## Examples
+
+### JSX Content
+
+```typescript copy
+const jsxContent: Content = {
+  t: 'div',
+  c: ['Hello ', { k: 'userName' }]
+};
+```
+
+### ICU Message Format
+
+```typescript copy
+const icuContent: Content = 'Hello {name}!' as IcuMessage;
+```
+
+### i18next Format
+
+```typescript copy
+const i18nextContent: Content = 'Welcome back, {{name}}!' as I18nextMessage;
+```
+
+---
+
+## Notes
+
+* `Content` unifies different message formats under a single type
+* Content type can be inferred from structure or explicitly specified
+
+## Related Types
+
+* [`JsxChildren`](/docs/core/types/JsxChildren) - JSX content structure
+* [`IcuMessage`](/docs/core/types/IcuMessage) - ICU MessageFormat strings
+* [`I18nextMessage`](/docs/core/types/I18nextMessage) - i18next message format
+* [`DataFormat`](/docs/core/types/DataFormat) - Format specification
diff --git a/apps/docs/content/docs/en/core/types/CustomMapping.mdx b/apps/docs/content/docs/en/core/types/CustomMapping.mdx
new file mode 100644
index 000000000..d4a3e3a24
--- /dev/null
+++ b/apps/docs/content/docs/en/core/types/CustomMapping.mdx
@@ -0,0 +1,75 @@
+---
+title: CustomMapping
+description: Type definition for custom locale code mappings and enhanced locale metadata
+---
+
+## Overview
+
+`CustomMapping` defines custom locale code mappings and metadata that extends or overrides standard BCP-47 locale information.
+
+```typescript
+type CustomMapping = Record<string, string | Partial<LocaleProperties>>;
+```
+
+## Type Definition
+
+### Structure
+
+`CustomMapping` is a record where:
+- **Keys**: Custom locale codes or aliases (e.g., `'simplified-chinese'`, `'company-english'`)
+- **Values**: Either a simple string name or partial `LocaleProperties` object
+
+### Value Types
+
+| Type | Description | Example |
+|------|-------------|---------|
+| `string` | Simple display name | `'Simplified Chinese'` |
+| `Partial<LocaleProperties>` | Enhanced locale metadata | `{ code: 'zh-CN', name: 'Chinese', emoji: '🇨🇳' }` |
+
+---
+
+## Examples
+
+### Simple String Mappings
+
+```typescript copy
+const simpleMapping: CustomMapping = {
+  'english': 'English',
+  'spanish': 'Spanish',
+  'mexican-spanish': 'Mexican Spanish'
+};
+
+const gt = new GT({
+  sourceLocale: 'english',
+  targetLocale: 'spanish',
+  customMapping: simpleMapping
+});
+```
+
+### Enhanced Locale Metadata
+
+```typescript copy
+const enhancedMapping: CustomMapping = {
+  'simplified-chinese': {
+    code: 'zh-CN',
+    name: 'Simplified Chinese',
+    nativeName: '简体中文',
+    regionName: 'China',
+    emoji: '🇨🇳'
+  }
+};
+```
+
+---
+
+## Notes
+
+* Custom mappings override standard BCP-47 locale resolution
+* String values provide simple display names
+* Partial LocaleProperties allow detailed locale customization
+* Custom mappings are resolved during GT instance initialization
+
+## Related Types
+
+* [`LocaleProperties`](/docs/core/types/LocaleProperties) - Complete locale metadata structure  
+* [`GTConstructorParams`](/docs/core/types/GTConstructorParams) - GT initialization options
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/core/types/DataFormat.mdx b/apps/docs/content/docs/en/core/types/DataFormat.mdx
new file mode 100644
index 000000000..11344f5d1
--- /dev/null
+++ b/apps/docs/content/docs/en/core/types/DataFormat.mdx
@@ -0,0 +1,66 @@
+---
+title: DataFormat
+description: Enumeration of supported content format types for translation
+---
+
+## Overview
+
+`DataFormat` specifies the format of translatable content.
+
+```typescript
+type DataFormat = 'JSX' | 'ICU' | 'I18NEXT';
+```
+
+## Type Definition
+
+### Values
+
+| Value | Description | Content Type | Use Case |
+|-------|-------------|--------------|----------|
+| `'JSX'` | JSX/React component format | `JsxChildren` | Rich UI components with elements and variables |
+| `'ICU'` | ICU MessageFormat | `IcuMessage` (string) | Complex formatting with plurals, dates, numbers |
+| `'I18NEXT'` | i18next message format | `I18nextMessage` (string) | Simple interpolation, existing i18next projects |
+
+### Format Characteristics
+
+| Format | Variables | Pluralization | HTML Elements | Date/Number Formatting |
+|--------|-----------|---------------|---------------|----------------------|
+| **JSX** | ✅ Rich variables | ✅ Via branching | ✅ Full HTML support | ✅ Via variables |
+| **ICU** | ✅ {variable} syntax | ✅ Built-in plurals | ❌ Text only | ✅ Built-in formatters |
+| **I18NEXT** | ✅ {{variable}} syntax | ✅ Via count | ❌ Text only | ✅ Via formatters |
+
+---
+
+## Examples
+
+### Format Specification
+
+```typescript copy
+const jsxEntry: Entry = {
+  source: { t: 'div', c: ['Hello ', { k: 'name' }] },
+  targetLocale: 'es',
+  metadata: { dataFormat: 'JSX' }
+};
+
+const icuEntry: Entry = {
+  source: 'Hello {name}',
+  targetLocale: 'es',
+  metadata: { dataFormat: 'ICU' }
+};
+```
+
+---
+
+## Notes
+
+* DataFormat determines how content is processed by the translation system
+* Format specification in metadata ensures proper content processing
+* Auto-detection is possible but explicit specification is recommended
+
+## Related Types
+
+* [`Content`](/docs/core/types/Content) - Union of all content format types
+* [`JsxChildren`](/docs/core/types/JsxChildren) - JSX format content
+* [`IcuMessage`](/docs/core/types/IcuMessage) - ICU MessageFormat content
+* [`I18nextMessage`](/docs/core/types/I18nextMessage) - i18next format content
+* [`EntryMetadata`](/docs/core/types/EntryMetadata) - Format specification in entries
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/core/types/EnqueueFilesOptions.mdx b/apps/docs/content/docs/en/core/types/EnqueueFilesOptions.mdx
new file mode 100644
index 000000000..f4c14003a
--- /dev/null
+++ b/apps/docs/content/docs/en/core/types/EnqueueFilesOptions.mdx
@@ -0,0 +1,76 @@
+---
+title: EnqueueFilesOptions
+description: Configuration options for batch file translation operations
+---
+
+## Overview
+
+`EnqueueFilesOptions` configures batch file translation operations.
+
+```typescript
+type EnqueueFilesOptions = {
+  publish?: boolean;
+  requireApproval?: boolean;
+  description?: string;
+  sourceLocale?: string;
+  targetLocales: string[];
+  version?: string;
+  _versionId?: string;
+  timeout?: number;
+  modelProvider?: string;
+  force?: boolean;
+};
+```
+
+## Properties
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `publish?` | `boolean` | No | Auto-publish translations |
+| `requireApproval?` | `boolean` | No | Require approval workflow |
+| `sourceLocale?` | `string` | No | Source locale override |
+| `targetLocales` | `string[]` | **Yes** | Target locale codes |
+| `version?` | `string` | No | Version identifier |
+| `timeout?` | `number` | No | Request timeout (ms) |
+| `modelProvider?` | `string` | No | Translation model provider |
+| `force?` | `boolean` | No | Force reprocessing |
+
+## Examples
+
+### Basic Usage
+
+```typescript copy
+import { GT, EnqueueFilesOptions } from 'generaltranslation';
+
+const options: EnqueueFilesOptions = {
+  targetLocales: ['es', 'fr', 'de'],
+  publish: false,
+  requireApproval: true
+};
+
+const result = await gt.enqueueFiles(files, options);
+```
+
+### Development vs Production
+
+```typescript copy
+// Development
+const devOptions: EnqueueFilesOptions = {
+  targetLocales: ['es'],
+  publish: true,
+  requireApproval: false
+};
+
+// Production  
+const prodOptions: EnqueueFilesOptions = {
+  targetLocales: ['es', 'fr', 'de', 'ja'],
+  publish: false,
+  requireApproval: true,
+  modelProvider: 'premium'
+};
+```
+
+## Related Types
+
+* [`FileToTranslate`](/docs/core/types/FileToTranslate) - File input structure
+* [`enqueueFiles()`](/docs/core/class/methods/files/enqueueFiles) - Method using this type
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/core/types/Entry.mdx b/apps/docs/content/docs/en/core/types/Entry.mdx
new file mode 100644
index 000000000..0748f0f2c
--- /dev/null
+++ b/apps/docs/content/docs/en/core/types/Entry.mdx
@@ -0,0 +1,104 @@
+---
+title: Entry
+description: Type definition for translation entries used in batch translation operations
+---
+
+## Overview
+
+`Entry` represents a translation request object for batch translation operations with [`translateMany()`](/docs/core/class/methods/translation/translateMany).
+
+```typescript
+type Entry = {
+  source: Content;
+  targetLocale?: string;
+  metadata?: EntryMetadata;
+};
+```
+
+## Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `source` | `Content` | Source content to translate |
+| `targetLocale?` | `string` | Target locale (falls back to instance targetLocale) |
+| `metadata?` | `EntryMetadata` | Optional metadata for translation customization |
+
+### Content Type
+
+```typescript
+type Content = JsxChildren | I18nextMessage | IcuMessage | string;
+```
+
+### EntryMetadata
+
+```typescript
+type EntryMetadata = {
+  context?: string;
+  id?: string;
+  hash?: string;
+  dataFormat?: DataFormat;
+  sourceLocale?: string;
+  actionType?: ActionType;
+  timeout?: number;
+  regionCode?: string;
+  scriptCode?: string;
+};
+```
+
+### ActionType
+
+```typescript
+type ActionType = 'standard' | 'fast' | string;
+```
+
+- `'standard'` - Higher quality translation model
+- `'fast'` - Lower latency translation model
+
+---
+
+## Examples
+
+### Basic Usage
+
+```typescript copy
+import { Entry } from 'generaltranslation';
+
+const entries: Entry[] = [
+  {
+    source: 'Hello, world!',
+    targetLocale: 'es'
+  },
+  {
+    source: 'Good morning',
+    targetLocale: 'de',
+    metadata: {
+      context: 'Formal greeting',
+      actionType: 'standard'
+    }
+  }
+];
+```
+
+### With translateMany()
+
+```typescript copy
+import { GT } from 'generaltranslation';
+
+const gt = new GT({
+  apiKey: 'your-api-key',
+  sourceLocale: 'en'
+});
+
+const entries: Entry[] = [
+  { source: 'Home', targetLocale: 'es' },
+  { source: 'About', targetLocale: 'es' }
+];
+
+const results = await gt.translateMany(entries);
+```
+
+## Related Types
+
+* [`EntryMetadata`](/docs/core/types/EntryMetadata) - Metadata options
+* [`TranslateManyResult`](/docs/core/types/TranslateManyResult) - Batch translation results
+* [`Content`](/docs/core/types/Content) - Supported content types
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/core/types/EntryMetadata.mdx b/apps/docs/content/docs/en/core/types/EntryMetadata.mdx
new file mode 100644
index 000000000..a18297166
--- /dev/null
+++ b/apps/docs/content/docs/en/core/types/EntryMetadata.mdx
@@ -0,0 +1,81 @@
+---
+title: EntryMetadata  
+description: Type definition for metadata that customizes translation behavior in Entry objects
+---
+
+## Overview
+
+`EntryMetadata` provides optional configuration for [`Entry`](/docs/core/types/Entry) objects in batch translation operations.
+
+```typescript
+type EntryMetadata = {
+  context?: string;
+  id?: string;
+  hash?: string;
+  dataFormat?: DataFormat;
+  sourceLocale?: string;
+  actionType?: ActionType;
+  timeout?: number;
+  regionCode?: string;
+  scriptCode?: string;
+};
+```
+
+## Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `context?` | `string` | Context for translators |
+| `id?` | `string` | Unique identifier |
+| `hash?` | `string` | Content hash for caching |
+| `dataFormat?` | `DataFormat` | Format specification |
+| `sourceLocale?` | `string` | Source locale override |
+| `actionType?` | `ActionType` | Translation model preference |
+| `timeout?` | `number` | Request timeout (ms) |
+| `regionCode?` | `string` | ISO region code |
+| `scriptCode?` | `string` | ISO script code |
+
+### Related Types
+
+```typescript
+type DataFormat = 'JSX' | 'ICU' | 'I18NEXT';
+type ActionType = 'standard' | 'fast' | string;
+```
+
+## Examples
+
+### Basic Usage
+
+```typescript copy
+import { Entry, EntryMetadata } from 'generaltranslation';
+
+const metadata: EntryMetadata = {
+  context: 'Button text',
+  actionType: 'fast'
+};
+
+const entry: Entry = {
+  source: 'Save',
+  targetLocale: 'es',
+  metadata
+};
+```
+
+### With ICU Format
+
+```typescript copy
+const icuEntry: Entry = {
+  source: '{count, plural, other {{count} items}}',
+  targetLocale: 'es',
+  metadata: {
+    dataFormat: 'ICU',
+    context: 'Item count'
+  }
+};
+```
+
+## Related Types
+
+* [`Entry`](/docs/core/types/Entry) - Parent type using this metadata
+* [`ActionType`](/docs/core/types/ActionType) - Translation model options
+* [`DataFormat`](/docs/core/types/DataFormat) - Content format specifications
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/core/types/FileToTranslate.mdx b/apps/docs/content/docs/en/core/types/FileToTranslate.mdx
new file mode 100644
index 000000000..4a77bc98d
--- /dev/null
+++ b/apps/docs/content/docs/en/core/types/FileToTranslate.mdx
@@ -0,0 +1,69 @@
+---
+title: FileToTranslate
+description: Type definition for file objects used in batch file translation operations
+---
+
+## Overview
+
+`FileToTranslate` represents a file object for batch translation operations with [`enqueueFiles()`](/docs/core/class/methods/files/enqueueFiles).
+
+```typescript
+type FileToTranslate = {
+  content: string;
+  fileName: string;
+  fileFormat: FileFormat;
+  formatMetadata?: Record<string, any>;
+  dataFormat?: DataFormat;
+};
+```
+
+## Properties
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `content` | `string` | **Yes** | Raw file content |
+| `fileName` | `string` | **Yes** | File identifier |
+| `fileFormat` | `FileFormat` | **Yes** | File format |
+| `formatMetadata?` | `Record<string, any>` | No | Format-specific metadata |
+| `dataFormat?` | `DataFormat` | No | Data format within file |
+
+### Related Types
+
+```typescript
+type FileFormat = 'JSON' | 'MDX' | 'MD' | 'HTML' | 'TXT' | string;
+type DataFormat = 'JSX' | 'ICU' | 'I18NEXT';
+```
+
+## Examples
+
+### JSON File
+
+```typescript copy
+import { FileToTranslate } from 'generaltranslation';
+
+const jsonFile: FileToTranslate = {
+  content: JSON.stringify({
+    "welcome": "Welcome",
+    "save": "Save"
+  }),
+  fileName: 'common.json',
+  fileFormat: 'JSON',
+  dataFormat: 'I18NEXT'
+};
+```
+
+### MDX File
+
+```typescript copy
+const mdxFile: FileToTranslate = {
+  content: `# Getting Started\n\nWelcome to our platform!`,
+  fileName: 'docs/start.mdx',
+  fileFormat: 'MDX',
+  dataFormat: 'JSX'
+};
+```
+
+## Related Types
+
+* [`EnqueueFilesOptions`](/docs/core/types/EnqueueFilesOptions) - Batch processing options
+* [`DataFormat`](/docs/core/types/DataFormat) - Data format specifications
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/core/types/GTConstructorParams.mdx b/apps/docs/content/docs/en/core/types/GTConstructorParams.mdx
new file mode 100644
index 000000000..66ce98e94
--- /dev/null
+++ b/apps/docs/content/docs/en/core/types/GTConstructorParams.mdx
@@ -0,0 +1,64 @@
+---
+title: GTConstructorParams
+description: TypeScript interface for GT class constructor parameters
+---
+
+## Overview
+
+`GTConstructorParams` defines configuration options for GT class initialization.
+
+```typescript
+interface GTConstructorParams {
+  apiKey?: string;
+  devApiKey?: string;
+  sourceLocale?: string;
+  targetLocale?: string;
+  locales?: string[];
+  projectId?: string;
+  baseUrl?: string;
+  customMapping?: CustomMapping;
+}
+```
+
+All properties are optional. The constructor reads `GT_API_KEY`, `GT_DEV_API_KEY`, and `GT_PROJECT_ID` from environment variables if not provided.
+
+## Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `apiKey?` | `string` | Production API key |
+| `devApiKey?` | `string` | Development API key |
+| `sourceLocale?` | `string` | Default source locale |
+| `targetLocale?` | `string` | Default target locale |
+| `locales?` | `string[]` | Supported locale codes |
+| `projectId?` | `string` | Project identifier |
+| `baseUrl?` | `string` | Custom API endpoint |
+| `customMapping?` | `CustomMapping` | Custom locale mappings |
+
+## Examples
+
+### Basic Setup
+
+```typescript copy
+const gt = new GT({
+  apiKey: 'your-api-key',
+  sourceLocale: 'en',
+  targetLocale: 'es',
+  locales: ['en', 'es', 'fr']
+});
+```
+
+### With Environment Variables
+
+```typescript copy
+const gt = new GT({
+  sourceLocale: 'en',
+  targetLocale: 'es'
+});
+// Uses GT_API_KEY and GT_PROJECT_ID from environment
+```
+
+## Related Types
+
+* [`CustomMapping`](/docs/core/types/CustomMapping) - Custom locale definitions
+* [`LocaleProperties`](/docs/core/types/LocaleProperties) - Locale information
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/core/types/JsxChild.mdx b/apps/docs/content/docs/en/core/types/JsxChild.mdx
new file mode 100644
index 000000000..e31e76daa
--- /dev/null
+++ b/apps/docs/content/docs/en/core/types/JsxChild.mdx
@@ -0,0 +1,46 @@
+---
+title: JsxChild
+description: Union type representing individual elements within JSX content
+---
+
+## Overview
+
+`JsxChild` represents a single element within JSX content.
+
+```typescript
+type JsxChild = string | JsxElement | Variable;
+```
+
+## Union Members
+
+| Type | Description |
+|------|-------------|
+| `string` | Plain text content |
+| `JsxElement` | Structured element |
+| `Variable` | Dynamic placeholder |
+
+## Examples
+
+### Basic Types
+
+```typescript copy
+import { JsxChild, Variable } from 'generaltranslation';
+
+// String
+const text: JsxChild = "Welcome!";
+
+// Variable
+const name: JsxChild = { k: 'userName' } as Variable;
+
+// Element
+const link: JsxChild = {
+  t: 'a',
+  c: ['Click here']
+};
+```
+
+## Related Types
+
+* [`JsxChildren`](/docs/core/types/JsxChildren) - Collections of JsxChild elements
+* [`JsxElement`](/docs/core/types/JsxElement) - Structured elements
+* [`Variable`](/docs/core/types/Variable) - Dynamic placeholders
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/core/types/JsxChildren.mdx b/apps/docs/content/docs/en/core/types/JsxChildren.mdx
new file mode 100644
index 000000000..797043b43
--- /dev/null
+++ b/apps/docs/content/docs/en/core/types/JsxChildren.mdx
@@ -0,0 +1,76 @@
+---
+title: JsxChildren
+description: Type definition for JSX content that can be translated and rendered
+---
+
+## Overview
+
+`JsxChildren` represents JSX content containing text, elements, and variables for translation.
+
+```typescript
+type JsxChildren = JsxChild | JsxChild[];
+```
+
+## Structure
+
+```typescript
+type JsxChild = string | JsxElement | Variable;
+```
+
+| Type | Description |
+|------|-------------|
+| `string` | Plain text content |
+| `JsxElement` | Structured element |
+| `Variable` | Dynamic placeholder |
+
+### JsxElement
+
+```typescript
+type JsxElement = {
+  t?: string;      // tag name
+  i?: number;      // id  
+  d?: GTProp;      // GT properties
+  c?: JsxChildren; // children
+};
+```
+
+## Examples
+
+### Basic Usage
+
+```typescript copy
+import { JsxChildren, Variable } from 'generaltranslation';
+
+// Simple text
+const text: JsxChildren = "Welcome!";
+
+// Text with variables
+const greeting: JsxChildren = [
+  "Hello, ",
+  { k: 'userName' } as Variable,
+  "!"
+];
+```
+
+### Structured Elements
+
+```typescript copy
+// Div element
+const divElement: JsxChildren = {
+  t: 'div',
+  c: ['Content here']
+};
+
+// Link with title
+const linkElement: JsxChildren = {
+  t: 'a',
+  d: { ti: 'Visit homepage' },
+  c: ['Click here']
+};
+```
+
+## Related Types
+
+* [`JsxChild`](/docs/core/types/JsxChild) - Individual child element types
+* [`JsxElement`](/docs/core/types/JsxElement) - Structured element definitions
+* [`Variable`](/docs/core/types/Variable) - Dynamic content placeholders
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/core/types/JsxElement.mdx b/apps/docs/content/docs/en/core/types/JsxElement.mdx
new file mode 100644
index 000000000..1881c662d
--- /dev/null
+++ b/apps/docs/content/docs/en/core/types/JsxElement.mdx
@@ -0,0 +1,62 @@
+---
+title: JsxElement
+description: Type definition for structured HTML-like elements in translatable JSX content
+---
+
+## Overview
+
+`JsxElement` represents structured HTML-like elements in translatable JSX content.
+
+```typescript
+type JsxElement = {
+  t?: string;      // tag name
+  i?: number;      // id
+  d?: GTProp;      // GT data/properties
+  c?: JsxChildren; // children
+};
+```
+
+## Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `t?` | `string` | HTML tag name |
+| `i?` | `number` | Internal identifier |
+| `d?` | `GTProp` | GT properties/attributes |
+| `c?` | `JsxChildren` | Child content |
+
+### Common GT Keys
+
+| GT Key | HTML Attribute |
+|--------|----------------|
+| `pl` | `placeholder` |
+| `ti` | `title` |
+| `alt` | `alt` |
+| `arl` | `aria-label` |
+
+## Examples
+
+### Basic Usage
+
+```typescript copy
+import { JsxElement, Variable } from 'generaltranslation';
+
+// Simple element
+const heading: JsxElement = {
+  t: 'h1',
+  c: ['Welcome']
+};
+
+// With attributes
+const button: JsxElement = {
+  t: 'button',
+  d: { ti: 'Submit form' },
+  c: ['Submit']
+};
+```
+
+## Related Types
+
+* [`JsxChildren`](/docs/core/types/JsxChildren) - Children content type
+* [`JsxChild`](/docs/core/types/JsxChild) - Individual child elements
+* [`Variable`](/docs/core/types/Variable) - Dynamic content
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/core/types/LocaleProperties.mdx b/apps/docs/content/docs/en/core/types/LocaleProperties.mdx
new file mode 100644
index 000000000..71a074743
--- /dev/null
+++ b/apps/docs/content/docs/en/core/types/LocaleProperties.mdx
@@ -0,0 +1,68 @@
+---
+title: LocaleProperties
+description: TypeScript interface containing comprehensive locale information
+---
+
+## Overview
+
+`LocaleProperties` provides detailed linguistic and regional information about a locale.
+
+```typescript
+interface LocaleProperties {
+  code: string;
+  name: string;
+  nativeName: string;
+  languageCode: string;
+  languageName: string;
+  nativeLanguageName: string;
+  nameWithRegionCode: string;
+  nativeNameWithRegionCode: string;
+  regionCode: string;
+  regionName: string;
+  nativeRegionName: string;
+  scriptCode: string;
+  scriptName: string;
+  nativeScriptName: string;
+  maximizedCode: string;
+  maximizedName: string;
+  nativeMaximizedName: string;
+  minimizedCode: string;
+  minimizedName: string;
+  nativeMinimizedName: string;
+  emoji: string;
+}
+```
+
+Returned by `getLocaleProperties()` methods.
+
+## Key Properties
+
+| Property | Description |
+|----------|-------------|
+| `code` | Original locale code |
+| `name` | Display name in source language |
+| `nativeName` | Display name in native language |
+| `languageCode` | Base language code |
+| `regionCode` | ISO region code |
+| `scriptCode` | ISO script code |
+| `maximizedCode` | Locale with likely script/region |
+| `minimizedCode` | Shortest valid locale code |
+| `emoji` | Flag emoji |
+
+## Examples
+
+### Basic Usage
+
+```typescript
+const gt = new GT({ sourceLocale: 'en-US' });
+const props = gt.getLocaleProperties('de-AT');
+
+console.log(props.name);        // "Austrian German"
+console.log(props.nativeName);  // "Österreichisches Deutsch"
+console.log(props.emoji);       // "🇦🇹"
+```
+
+## Related Types
+
+* [`getLocaleProperties()`](/docs/core/class/methods/locales/getLocaleProperties) - Method that returns this interface
+* [`CustomMapping`](/docs/core/types/CustomMapping) - Custom locale definitions
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/core/types/TranslateManyResult.mdx b/apps/docs/content/docs/en/core/types/TranslateManyResult.mdx
new file mode 100644
index 000000000..ae49d09b8
--- /dev/null
+++ b/apps/docs/content/docs/en/core/types/TranslateManyResult.mdx
@@ -0,0 +1,57 @@
+---
+title: TranslateManyResult
+description: Type definition for results returned by batch translation operations
+---
+
+## Overview
+
+`TranslateManyResult` represents the result of batch translation operations with [`translateMany()`](/docs/core/class/methods/translation/translateMany).
+
+```typescript
+type TranslateManyResult = Array<TranslationResult>;
+```
+
+## Structure
+
+Array of [`TranslationResult`](/docs/core/types/TranslationResult) objects, maintaining the same order as input entries.
+
+```typescript
+type TranslationResult = RequestSuccess | TranslationError;
+```
+
+## Examples
+
+### Basic Usage
+
+```typescript copy
+import { GT, TranslateManyResult } from 'generaltranslation';
+
+const gt = new GT({
+  apiKey: 'your-api-key',
+  sourceLocale: 'en'
+});
+
+const entries = [
+  { source: 'Hello', targetLocale: 'es' },
+  { source: 'Goodbye', targetLocale: 'es' }
+];
+
+const results: TranslateManyResult = await gt.translateMany(entries);
+```
+
+### Error Handling
+
+```typescript copy
+results.forEach((result, index) => {
+  if ('error' in result) {
+    console.error(`Entry ${index} failed: ${result.error}`);
+  } else {
+    console.log(`Entry ${index}: ${result.translation}`);
+  }
+});
+```
+
+## Related Types
+
+* [`TranslationResult`](/docs/core/types/TranslationResult) - Individual result structure
+* [`Entry`](/docs/core/types/Entry) - Input entry format
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/core/types/TranslationResult.mdx b/apps/docs/content/docs/en/core/types/TranslationResult.mdx
new file mode 100644
index 000000000..55ccd502d
--- /dev/null
+++ b/apps/docs/content/docs/en/core/types/TranslationResult.mdx
@@ -0,0 +1,70 @@
+---
+title: TranslationResult
+description: Type definition for translation results returned by translate() methods
+---
+
+## Overview
+
+`TranslationResult` represents the result of translation operations.
+
+```typescript
+type TranslationResult = RequestSuccess | TranslationError;
+```
+
+## Union Types
+
+### RequestSuccess
+
+```typescript
+type RequestSuccess = TypedResult & {
+  locale: string;
+  reference: TranslationResultReference;
+};
+```
+
+### TranslationError
+
+```typescript
+type TranslationError = {
+  error: string;
+  code: number;
+  reference?: TranslationResultReference;
+};
+```
+
+## Examples
+
+### Basic Error Handling
+
+```typescript copy
+import { GT, TranslationResult } from 'generaltranslation';
+
+const gt = new GT({ apiKey: 'your-api-key' });
+
+const result: TranslationResult = await gt.translate('Hello');
+
+if ('error' in result) {
+  console.error(`Translation failed: ${result.error}`);
+} else {
+  console.log(`Translation: ${result.translation}`);
+}
+```
+
+### Type Guards
+
+```typescript copy
+function isTranslationError(result: TranslationResult): result is TranslationError {
+  return 'error' in result;
+}
+
+if (isTranslationError(result)) {
+  // Handle error
+} else {
+  // Handle success
+}
+```
+
+## Related Types
+
+* [`TranslateManyResult`](/docs/core/types/TranslateManyResult) - Batch translation results
+* [`JsxChildren`](/docs/core/types/JsxChildren) - JSX content type
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/core/types/Variable.mdx b/apps/docs/content/docs/en/core/types/Variable.mdx
new file mode 100644
index 000000000..9f37fedd9
--- /dev/null
+++ b/apps/docs/content/docs/en/core/types/Variable.mdx
@@ -0,0 +1,79 @@
+---
+title: Variable
+description: Type definition for variables used in translation content
+---
+
+## Overview
+
+`Variable` represents a placeholder for dynamic content in translations.
+
+```typescript
+type Variable = {
+  k: string;
+  i?: number;
+  v?: VariableType;
+};
+```
+
+## Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `k` | `string` | Variable key/name |
+| `i?` | `number` | Internal identifier |
+| `v?` | `VariableType` | Formatting type |
+
+### VariableType
+
+```typescript
+type VariableType = 'v' | 'n' | 'd' | 'c';
+```
+
+| Value | Description |
+|-------|-------------|
+| `'v'` | Plain text substitution |
+| `'n'` | Number formatting |
+| `'d'` | Date formatting |
+| `'c'` | Currency formatting |
+
+## Examples
+
+### Basic Usage
+
+```typescript copy
+import { Variable } from 'generaltranslation';
+
+// Text variable
+const nameVariable: Variable = {
+  k: 'userName'
+};
+
+// Number variable
+const countVariable: Variable = {
+  k: 'itemCount',
+  v: 'n'
+};
+
+// Currency variable
+const priceVariable: Variable = {
+  k: 'price',
+  v: 'c'
+};
+```
+
+### In JSX Content
+
+```typescript copy
+const welcomeContent = [
+  'Welcome back, ',
+  { k: 'userName' } as Variable,
+  '! You have ',
+  { k: 'messageCount', v: 'n' } as Variable,
+  ' messages.'
+];
+```
+
+## Related Types
+
+* [`VariableType`](/docs/core/types/VariableType) - Formatting type specifications
+* [`JsxChildren`](/docs/core/types/JsxChildren) - JSX content with variables
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/core/types/VariableType.mdx b/apps/docs/content/docs/en/core/types/VariableType.mdx
new file mode 100644
index 000000000..40ca8dd7b
--- /dev/null
+++ b/apps/docs/content/docs/en/core/types/VariableType.mdx
@@ -0,0 +1,39 @@
+---
+title: VariableType
+description: Enumeration of variable formatting types for dynamic content translation
+---
+
+## Overview
+
+`VariableType` specifies how variables are formatted in translated content.
+
+```typescript
+type VariableType = 'v' | 'n' | 'd' | 'c';
+```
+
+## Values
+
+| Value | Description |
+|-------|-------------|
+| `'v'` | Plain text substitution |
+| `'n'` | Number formatting |
+| `'d'` | Date formatting |
+| `'c'` | Currency formatting |
+
+## Examples
+
+### Basic Usage
+
+```typescript copy
+import { Variable, VariableType } from 'generaltranslation';
+
+const textVar: Variable = { k: 'name', v: 'v' };
+const numberVar: Variable = { k: 'count', v: 'n' };
+const dateVar: Variable = { k: 'date', v: 'd' };
+const currencyVar: Variable = { k: 'price', v: 'c' };
+```
+
+## Related Types
+
+* [`Variable`](/docs/core/types/Variable) - Parent type using VariableType
+* [`JsxChildren`](/docs/core/types/JsxChildren) - JSX content with variables
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/core/types/meta.json b/apps/docs/content/docs/en/core/types/meta.json
new file mode 100644
index 000000000..d44a3177b
--- /dev/null
+++ b/apps/docs/content/docs/en/core/types/meta.json
@@ -0,0 +1,21 @@
+{
+  "title": "Types",
+  "pages": [
+    "./Content",
+    "./CustomMapping",
+    "./DataFormat",
+    "./EnqueueFilesOptions",
+    "./Entry",
+    "./EntryMetadata",
+    "./FileToTranslate",
+    "./GTConstructorParams",
+    "./JsxChild",
+    "./JsxChildren",
+    "./JsxElement",
+    "./LocaleProperties",
+    "./TranslateManyResult",
+    "./TranslationResult",
+    "./Variable",
+    "./VariableType"
+  ]
+}
diff --git a/apps/docs/content/docs/en/locadex/auto-merge.mdx b/apps/docs/content/docs/en/locadex/auto-merge.mdx
new file mode 100644
index 000000000..52ab2afe9
--- /dev/null
+++ b/apps/docs/content/docs/en/locadex/auto-merge.mdx
@@ -0,0 +1,61 @@
+---
+title: Auto-merge Pull Requests
+description: Configure Locadex to automatically merge pull requests
+---
+Auto-merge eliminates manual PR review for Locadex-generated pull requests. When enabled, PRs created by Locadex merge automatically without requiring your approval.
+
+This applies to all PRs Locadex creates, including:
+- Continuous i18n
+- Update Locales
+- Translation redeployments
+
+*This does not apply to Setup or Re-run Setup PRs.*
+
+For Mintlify projects, auto-merge is enabled by default.
+
+## Enable auto-merge
+
+Navigate to the Locadex page in your dashboard and toggle auto-merge under "Run Configuration":
+
+![Click the auto merge toggle](/locadex-screenshots/auto-merge/run-configuration.png)
+
+**Make sure to click "Save" after toggling auto-merge** to apply your changes.
+
+**Note**: The Auto-merge toggle only appears when "Locadex Action" is set to "Create pull request".
+
+## Bypass branch protection rules
+
+If your default branch has protection rules, Locadex will continue creating PRs but cannot merge them automatically. Configure Locadex to bypass branch protection:
+
+### Step 1: Open repository rulesets
+
+In your GitHub repository settings, select "Rulesets" from the Rules section.
+
+### Step 2: Identify blocking rules
+
+Find rules preventing automatic merges. Common blockers include:
+
+- "Require a pull request before merging"
+- Required status checks
+- Required review approvals
+
+![Require a pull request before merging](/locadex-screenshots/auto-merge/require-pull-request.png)
+
+**Note**: Multiple rules may need updating.
+
+### Step 3: Add bypass permissions
+
+Click the rule blocking auto-merge, then:
+
+1. Click "Add Bypass"
+2. Select "Locadex Agent" from the dropdown
+
+![Add Bypass button with "Locadex Agent selected"](/locadex-screenshots/auto-merge/add-bypass.png)
+
+### Step 4: Save changes
+
+Click "Save" at the bottom of the page to apply your changes.
+
+**Make sure to click "Save"** — this step is easy to miss.
+
+Locadex will now automatically merge PRs it creates on your default branch.
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/locadex/meta.json b/apps/docs/content/docs/en/locadex/meta.json
index 89125e1f8..b1a5aeea8 100644
--- a/apps/docs/content/docs/en/locadex/meta.json
+++ b/apps/docs/content/docs/en/locadex/meta.json
@@ -3,5 +3,11 @@
   "description": "AI i18n agent",
   "icon": "Brain",
   "root": true,
-  "pages": ["---Getting Started---", "mintlify", "next", "monorepos"]
+  "pages": [
+    "---Getting Started---",
+    "mintlify",
+    "next",
+    "monorepos",
+    "auto-merge"
+  ]
 }
diff --git a/apps/docs/content/docs/en/next/concepts/stand-alone.mdx b/apps/docs/content/docs/en/next/concepts/stand-alone.mdx
index a2e9f3347..46bbd0f05 100644
--- a/apps/docs/content/docs/en/next/concepts/stand-alone.mdx
+++ b/apps/docs/content/docs/en/next/concepts/stand-alone.mdx
@@ -27,6 +27,8 @@ Make sure you load your translated dictionaries with the [`loadDictionary()`](/d
 
 ---
 
+### Manual string translation
+
 If your project is using inline translations with the [`<T>`](/docs/next/guides/jsx) component
 or the [`useGT() & getGT()`](/docs/next/guides/strings) functions,
 you'll also need to manually translate your strings.
diff --git a/apps/docs/content/docs/en/next/config.mdx b/apps/docs/content/docs/en/next/config.mdx
new file mode 100644
index 000000000..24498011d
--- /dev/null
+++ b/apps/docs/content/docs/en/next/config.mdx
@@ -0,0 +1,59 @@
+---
+title: Configuration
+description: A guide on the gt.config.json file
+---
+
+## Overview
+
+The `gt.config.json` file is used to configure your project's GT settings. It should be placed in the root of your project.
+
+The CLI setup wizard [`npx gtx-cli init`](/docs/cli/init) will create a `gt.config.json` file for you in your project.
+
+## Configuration
+
+The three most important properties are:
+
+- `defaultLocale`: The default locale for your project. This is the locale that your source content is written in. This is also the fallback locale for your project.
+
+- `locales`: An array of locales for your project. These are the locales that you want to translate your project into. See the [supported locales](/docs/platform/locale-strings#supported-locales) for more information. 
+If you are using `gt-next` or `gt-react`, these are also the locales that your app supports.
+
+- `files`: While optional for react component translation, this field contains information about the files you want to translate. See the [files](/docs/cli/reference/config#files) section for more information.
+
+## Examples
+
+Here is an example of a `gt.config.json` file:
+
+```json title="gt.config.json"
+{
+  "defaultLocale": "en",
+  "locales": ["fr", "es"],
+  "files": {
+    "json": {
+      "include": ["public/locales/[locale].json"]
+    }
+  }
+}
+```
+
+This will translate the `public/locales/en.json` file to `public/locales/fr.json` and `public/locales/es.json`.
+
+<Files>
+  <Folder name="app">
+    <File name="layout.js" />
+    <File name="page.js" />
+  </Folder>
+  <Folder name="public" defaultOpen={true}>
+    <Folder name="locales" defaultOpen={true}>
+      <File name="en.json" />
+      <File name="fr.json" />
+      <File name="es.json" />
+    </Folder>
+  </Folder>
+  <File name="gt.config.json" />
+  <File name="package.json" />
+</Files>
+
+## Next Steps
+
+Learn how to use the [init command](/docs/cli/init) to generate this configuration file.
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/next/guides/branches.mdx b/apps/docs/content/docs/en/next/guides/branches.mdx
index 2482f1868..9d411341a 100644
--- a/apps/docs/content/docs/en/next/guides/branches.mdx
+++ b/apps/docs/content/docs/en/next/guides/branches.mdx
@@ -1,341 +1,329 @@
 ---
-title: Using Branches
-description: How to use branch components
+title: Branching Components
+description: How to use branching components for conditional content within translations
 ---
 
-## Overview
-
-Branching components in `gt-next` enable dynamic content rendering based on specific conditions. These components include:
-
-- [`<Branch>`](/docs/next/api/components/branch): Renders content based on a matching `branch` prop.
-- [`<Plural>`](/docs/next/api/components/plural): Renders content based on pluralization rules for a given number.
-
-Both components provide powerful tools for managing conditional logic and dynamic content in localized applications.
-
-In this guide, we will cover:
-<Steps>
-  <Step>
-    What are branch components?
-  </Step>
-  <Step>
-    How to use branch components
-  </Step>
-  <Step>
-    When to use branch components
-  </Step>
-  <Step>
-    Examples
-  </Step>
-  <Step>
-    Common pitfalls
-  </Step>
-</Steps>
+Branching components enable conditional content rendering within [`<T>`](/docs/next/api/components/t) components. They handle dynamic logic like if/else statements and pluralization rules while ensuring all content variations can be properly translated.
 
----
-
-## What are branch components?
-
-Branch components dynamically choose which content to render based on a specific condition or value.
-
-### `<Branch>`
+## Available Components
 
-The `<Branch>` component allows you to render different content based on a provided `branch` value.
-If no matching branch is found, the fallback `children` content is rendered.
+- [`<Branch>`](/docs/next/api/components/branch): Conditional content based on values or states
+- [`<Plural>`](/docs/next/api/components/plural): Automatic pluralization using locale-specific rules
 
-For example, the `<Branch>` component is perfect for conditional rendering based on application state, user preferences, or any dynamic data.
+## Quick Start
 
-The most common use case is to use it to replace a ternary or conditional operator.
+Branching components work inside [`<T>`](/docs/next/api/components/t) to handle conditional logic:
 
-### `<Plural>`
+```jsx
+import { T, Branch, Plural, Num, Var } from 'gt-next';
 
-The `<Plural>` component extends the functionality of `<Branch>` by handling pluralization and number agreement automatically.
-It uses the provided `n` value to determine which plural form to display, based on locale-specific rules.
-
-For example, the `<Plural>` component is ideal for rendering singular and plural text dynamically, such as "1 item" vs. "2 items."
-
-Plural components are often combined with `<Num>` components to localize a number and its corresponding text.
-
-### Use with `<T>`
+function NotificationPanel({ user, messageCount }) {
+  return (
+    <T>
+      <Branch 
+        branch={user.status}
+        online={<p><Var>{user.name}</Var> is currently online</p>}
+        away={<p><Var>{user.name}</Var> is away</p>}
+      >
+        <p><Var>{user.name}</Var> status unknown</p>
+      </Branch>
+      
+      <Plural
+        n={messageCount}
+        one={<p>You have <Num>{messageCount}</Num> message</p>}
+        other={<p>You have <Num>{messageCount}</Num> messages</p>}
+      />
+    </T>
+  );
+}
+```
 
-The `<Branch>` and `<Plural>` components should be used within a [`<T>`](/docs/next/guides/jsx) component to sanitize dynamic content for translation.
+## How Branching Components Work
 
-When used within a `<T>` component, the content is automatically translated and rendered in your user's selected language.
+Branching components solve conditional rendering within translations by:
 
-When used standalone, they will just render the content as-is, without translating it.
+1. **Replacing ternary operators** and conditional logic inside [`<T>`](/docs/next/api/components/t)
+2. **Providing fallback content** when conditions don't match expected values
+3. **Enabling translation** of all possible content variations
+4. **Following locale rules** for pluralization automatically
 
----
+```jsx
+// ❌ This breaks - conditional logic in <T>
+<T><p>{isActive ? 'User is active' : 'User is inactive'}</p></T>
 
-## How to use branch components
+// ✅ This works - conditional logic with branching
+<T>
+  <Branch 
+    branch={isActive} 
+    true={<p>User is active</p>}
+    false={<p>User is inactive</p>}
+  />
+</T>
+```
 
-### Branching logic with `<Branch>`
+## Component Guide
 
-The `<Branch>` component is used for flexible content switching based on a `branch` value.
+### `<Branch>` - Conditional Content
 
-You can define multiple possible branches, and the component will render the content corresponding to the matching branch key.
+Use [`<Branch>`](/docs/next/api/components/branch) for any conditional rendering based on values or states:
 
-Additionally, you can use other variable components in combination with the `<Branch>` component.
+```jsx
+// User status display
+<T>
+  <Branch 
+    branch={user.role}
+    admin={<p>Administrator Dashboard</p>}
+    user={<p>User Dashboard</p>}
+    guest={<p>Guest Access</p>}
+  >
+    <p>Access level unknown</p>
+  </Branch>
+</T>
 
-```tsx 
-const branch: 'option1' | 'option2' = 'option1';
+// Boolean conditions
 <T>
   <Branch 
-    branch={branch}
-    option1={<p>Option 1</p>}
-    option2={<p>Option 2</p>}
+    branch={isLoggedIn}
+    true={<p>Welcome back!</p>}
+    false={<p>Please log in</p>}
+  />
+</T>
+
+// Subscription tiers
+<T>
+  <Branch
+    branch={subscription.tier}
+    free={<p>Upgrade to unlock premium features</p>}
+    premium={<p>Enjoy your premium experience</p>}
+    enterprise={<p>Contact support for enterprise solutions</p>}
   >
-    Fallback content
+    <p>Subscription status unavailable</p>
   </Branch>
 </T>
 ```
 
-The `<Branch>` component should be used within a `<T>` component. This allows for the content to be automatically translated.
+### `<Plural>` - Smart Pluralization
 
-See the [API Reference](/docs/next/api/components/branch) for more details.
+Use [`<Plural>`](/docs/next/api/components/plural) for content that changes based on quantity:
 
-### Pluralization with `<Plural>` [#plural-logic]
+```jsx
+// Basic pluralization
+<T>
+  <Plural
+    n={itemCount}
+    one={<p><Num>{itemCount}</Num> item in cart</p>}
+    other={<p><Num>{itemCount}</Num> items in cart</p>}
+  />
+</T>
 
-The `<Plural>` component automates pluralization logic based on the value of `n`.
-The component dynamically chooses the appropriate plural form for the given number and locale.
+// Zero handling
+<T>
+  <Plural
+    n={notifications}
+    zero={<p>No new notifications</p>}
+    one={<p><Num>{notifications}</Num> notification</p>}
+    other={<p><Num>{notifications}</Num> notifications</p>}
+  />
+</T>
 
-```tsx copy
-const count: number = 1;
+// Complex pluralization (follows Unicode CLDR rules)
 <T>
   <Plural
-    n={count}
-    singular={<><Num>{1}</Num> item.</>}
-    plural={<><Num>{count}</Num> items.</>}
-    // Additional options
-    zero={<><Num>{count}</Num> items.</>}
-    one={<><Num>{count}</Num> item.</>}
-    two={<><Num>{count}</Num> items.</>}
-    few={<><Num>{count}</Num> items.</>}
-    many={<><Num>{count}</Num> items.</>}
-    other={<><Num>{count}</Num> items.</>}
-    dual={<><Num>{count}</Num> items.</>}
+    n={days}
+    zero={<p>Due today</p>}
+    one={<p>Due in <Num>{days}</Num> day</p>}
+    few={<p>Due in <Num>{days}</Num> days</p>}
+    many={<p>Due in <Num>{days}</Num> days</p>}
+    other={<p>Due in <Num>{days}</Num> days</p>}
   />
 </T>
 ```
 
-The available plural forms depend on the locale and follow [Unicode CLDR pluralization rules](https://cldr.unicode.org/index/cldr-spec/plural-rules).
-
-See the [API Reference](/docs/next/api/components/plural) for more details.
-
----
+### Combining with Variable Components
 
-## When to use branch components
-
-Branch components are important for managing dynamic content in your application.
-
-When you need to display different content based on a condition, use `<Branch>`.
-
-These conditions can be based on a variable component, a boolean, or a function.
-
-For example, if your code has a ternary operator or conditional rendering, you can use `<Branch>` to replace it.
-
-<Tabs items={["Result", "Original"]}>
-  <Tab value="Result">
-    ```tsx
-    const isActive = true;
-    // Ternary operator
-    <Branch branch={isActive} true={<p>The user is active.</p>} false={<p>The user is inactive.</p>}>
-      <p>Status unknown.</p>
-    </Branch>
-
-    // Conditional rendering
-    <Branch branch={isActive} true={<p>The user is active.</p>}>
-      <></>
-    </Branch>
-    ```
-  </Tab>
-  <Tab value="Original">
-    ```tsx
-    // Ternary operator
-    const isActive = true;
-    {isActive ? <p>The user is active.</p> : <p>The user is inactive.</p>}
-
-    // Conditional rendering
-    {isActive && <p>The user is active.</p>}
-    ```
-  </Tab>
-</Tabs>
-
-If you want to render content with correct pluralization, use `<Plural>`.
-
-<Tabs items={["Result", "Original"]}>
-  <Tab value="Result">
-    ```tsx
-    const count = 1;
-    <Plural n={count} one={<p>1 item</p>} other={<p>{count} items</p>} />
-    ```
-  </Tab>
-  <Tab value="Original">
-    ```tsx
-    const count = 1;
-    {count === 1 ? <p>1 item</p> : <p>{count} items</p>}
-    ```
-  </Tab>
-</Tabs>
+Branching and variable components work together seamlessly:
 
-<Callout>
-  The `<Branch>` and `<Plural>` components can be used standalone, without a `<T>` component.
-  When used standalone, they will just render the content as-is, without translating it.
-
-  However, they are often used within a [`<T>`](/docs/next/guides/jsx) component to sanitize dynamic content for translation.
-</Callout>
-
-
----
+```jsx
+<T>
+  <Branch
+    branch={order.status}
+    pending={
+      <p>
+        Order <Var>{order.id}</Var> is pending. 
+        Total: <Currency currency="USD">{order.total}</Currency>
+      </p>
+    }
+    shipped={
+      <p>
+        Order <Var>{order.id}</Var> shipped on <DateTime>{order.shippedDate}</DateTime>
+      </p>
+    }
+    delivered={
+      <p>Order <Var>{order.id}</Var> was delivered successfully</p>
+    }
+  >
+    <p>Order status unknown</p>
+  </Branch>
+</T>
+```
 
-## Examples
+## When to Use Branching Components
 
-### `<Branch>`
+### Replace Ternary Operators
+Convert conditional logic for use within [`<T>`](/docs/next/api/components/t):
 
-```tsx copy
-import { T, Branch, Var } from 'gt-next';
+```jsx
+// ❌ Can't use ternary in <T>
+<T>{isActive ? <p>Active user</p> : <p>Inactive user</p>}</T>
 
-export default function UserStatus() {
-  const [status, setStatus] = useState<'active' | 'inactive' | undefined>(undefined);
-  const [name, setName] = useState<string>('John Doe');
-  return (
-    <T>
-      <Branch
-        branch={status}
-        active={<p>The user <Var>{name}</Var> is active.</p>}
-        inactive={<p>The user <Var>{name}</Var> is inactive.</p>}
-      >
-        <p>Status unknown.</p>
-      </Branch>
-    </T>
-  );
-}
+// ✅ Use Branch instead
+<T>
+  <Branch 
+    branch={isActive}
+    true={<p>Active user</p>}
+    false={<p>Inactive user</p>}
+  />
+</T>
 ```
-In the example above, the `<Branch>` component dynamically switches between 3 rendered contents based on the value of `status`.
 
-When `status` is `"active"`, the component renders:
-```tsx
-<p>The user <Var>{name}</Var> is active.</p>
-```
+### Handle Multiple Conditions
+Replace switch statements or multiple if/else conditions:
 
-When `status` is `"inactive"`, the component renders:
-```tsx
-<p>The user <Var>{name}</Var> is inactive.</p>
-```
+```jsx
+// ❌ Complex conditional logic
+<T>
+  {status === 'loading' ? <p>Loading...</p> : 
+   status === 'error' ? <p>Error occurred</p> : 
+   status === 'success' ? <p>Success!</p> : 
+   <p>Unknown status</p>}
+</T>
 
-When `status` is neither `"active"` nor `"inactive"`, the component renders the fallback content:
-```tsx
-<p>Status unknown.</p>
+// ✅ Clean branching logic
+<T>
+  <Branch
+    branch={status}
+    loading={<p>Loading...</p>}
+    error={<p>Error occurred</p>}
+    success={<p>Success!</p>}
+  >
+    <p>Unknown status</p>
+  </Branch>
+</T>
 ```
 
-Since the `<Branch>` component is wrapped in a `<T>` component, the rendered content is automatically translated in context.
-
+### Pluralization Rules
+Replace manual plural handling:
 
-In this example, it displays different descriptions based on the user's subscription plan.
-```tsx copy
-import { Branch } from 'gt-next';
+```jsx
+// ❌ Manual pluralization
+<T>{count === 1 ? <p>1 item</p> : <p>{count} items</p>}</T>
 
-export default function SubscriptionDetails() {
-  const [plan, setPlan] = useState<'free' | 'premium' | 'enterprise' | undefined>(undefined);
-  return (
-    <Branch
-      branch={plan}
-      free={<p>You are on the Free plan. Upgrade to unlock more features!</p>}
-      premium={<p>You are enjoying the Premium plan with full access to features.</p>}
-      enterprise={<p>You are on the Enterprise plan. Contact support for tailored solutions.</p>}
-    >
-      <p>No subscription plan detected.</p>
-    </Branch>
-  );
-}
+// ✅ Automatic pluralization
+<T>
+  <Plural
+    n={count}
+    one={<p><Num>{count}</Num> item</p>}
+    other={<p><Num>{count}</Num> items</p>}
+  />
+</T>
 ```
 
- * The `branch` prop determines which plan message to display.
- * If `plan` is `"free"`, `"premium"`, or `"enterprise"`, the corresponding message is shown.
- * If `plan` doesn't match any of these values, the fallback content (`"No subscription plan detected."`) is displayed.
-
+## Standalone Usage
 
-### `<Plural>`
+Branching components can be used outside [`<T>`](/docs/next/api/components/t) for pure logic without translation:
 
-The `<Plural>` component dynamically handles singular and plural content based on the value of `n`.
-This example displays the number of unread messages in a user's inbox.
+```jsx
+// Pure conditional rendering
+<Branch
+  branch={theme}
+  dark={<DarkModeIcon />}
+  light={<LightModeIcon />}
+>
+  <DefaultIcon />
+</Branch>
 
-```tsx copy
-import { T, Plural, Num } from 'gt-next';
-
-export default function UnreadMessages() {
-  const [unreadCount, setUnreadCount] = useState<number>(1);
-  return (
-    <T>
-      <Plural
-        n={unreadCount}
-        one={<>You have <Num>{unreadCount}</Num> unread message.</>}
-        other={<>You have <Num>{unreadCount}</Num> unread messages.</>}
-      />
-    </T>
-  );
-}
+// Pure pluralization
+<Plural
+  n={count}
+  one={<SingleItemComponent />}
+  other={<MultipleItemsComponent />}
+/>
 ```
- * The `n` prop specifies the number of unread messages.
- * If `unreadCount` is `1`, the component renders: `"You have 1 unread message."`
- * For any other value, it renders: `"You have X unread messages."` where `X` is the value of `unreadCount` formatted by `<Num>`.
 
----
-
-## Common Pitfalls
+## Common Issues
 
-### Missing Branch Values [#missing-branch]
+### Missing Branch Keys
+Always provide fallback content for unmatched values:
 
-If a branch value is not provided or does not match any keys, the `<Branch>` component will render the fallback children content.
-Always ensure that the possible branch keys match the values passed to the branch prop.
-
-```tsx copy
-import { Branch } from 'gt-next';
+```jsx
+// ❌ No fallback for unexpected values
+<Branch
+  branch={userRole}
+  admin={<AdminPanel />}
+  user={<UserPanel />}
+  // What if userRole is "moderator"?
+/>
 
-export default function StatusMessage({ status }) {
-  return (
-    <Branch
-      branch={status}
-      active={<p>The user is active.</p>}
-      inactive={<p>The user is inactive.</p>}
-    >
-      <p>Status unknown.</p>
-    </Branch>
-  );
-}
+// ✅ Always include fallback
+<Branch
+  branch={userRole}
+  admin={<AdminPanel />}
+  user={<UserPanel />}
+>
+  <DefaultPanel /> {/* Fallback for any other value */}
+</Branch>
 ```
-If `status` is `undefined` or a value other than `active` or `inactive`, the fallback content `“Status unknown.”` will be displayed.
 
+### Incomplete Plural Forms
+Provide necessary plural forms for your default locale:
 
-### Missing Plural Forms [#plural-locale]
-
-Remember to specify all necessary plural forms in your default language.
-This is how `gt-next` ensures that your application always has fallback content to display.
-
-For example, if English is your default language, you should provide all plural forms for English.
-
-```tsx copy
-import { Plural, Num } from 'gt-next';
+```jsx
+// ❌ Missing "other" form
+<Plural
+  n={count}
+  one={<p>1 item</p>}
+  // What about 0, 2, 3, etc.?
+/>
 
+// ✅ Include required forms
 <Plural
   n={count}
-  one={<>You have <Num>{count}</Num> unread message.</>}
-  other={<>You have <Num>{count}</Num> unread messages.</>}
+  zero={<p>No items</p>}
+  one={<p>1 item</p>}
+  other={<p>{count} items</p>}
 />
 ```
 
-Here, we have provided `one` and `other` plural forms for English.
-
-Alternatively, you can also provide `singular` and `plural` for English.
+### Complex Nested Logic
+Although this works, we recommend keeping branching logic simple and avoid deep nesting:
 
+```jsx
+// ❌ Complex nested branching
+<Branch branch={status}>
+  <Branch branch={subStatus}>
+    {/* Hard to read and maintain */}
+  </Branch>
+</Branch>
+
+// ✅ Flatten logic or use multiple components
+<Branch
+  branch={`${status}-${subStatus}`}
+  active-online={<ActiveOnline />}
+  active-offline={<ActiveOffline />}
+  inactive-online={<InactiveOnline />}
+>
+  <DefaultState />
+</Branch>
+```
 
----
-
-## Notes
- * Branch components are essential for managing dynamic and localized content in applications.
- * The `<Branch>` component is highly flexible and can adapt to various conditions and states.
- * The `<Plural>` component simplifies pluralization by adhering to locale-specific rules automatically.
- * Always include a fallback `children` prop for better error handling and user experience.
+<Callout>
+  Learn more about pluralization rules in the [Unicode CLDR documentation](https://cldr.unicode.org/index/cldr-spec/plural-rules).
+</Callout>
 
 ## Next Steps
- * Check out [`<Branch>`](/docs/next/api/components/branch) and [`<Plural>`](/docs/next/api/components/plural) in the API Reference for more details.
- * Learn more about pluralization rules and branching logic in [Unicode CLDR Pluralization Rules](https://cldr.unicode.org/index/cldr-spec/plural-rules).
- * Explore how to use [Variable Components](/docs/next/guides/variables).
\ No newline at end of file
+
+- [String Translation Guide](/docs/next/guides/strings) - Translate plain text without JSX
+- [Dynamic Content Guide](/docs/next/guides/dynamic-content) - Handle runtime translation
+- API References:
+  - [`<Branch>` Component](/docs/next/api/components/branch)
+  - [`<Plural>` Component](/docs/next/api/components/plural)
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/next/guides/dictionaries.mdx b/apps/docs/content/docs/en/next/guides/dictionaries.mdx
index 4a7d8bf7a..44c4f0ddc 100644
--- a/apps/docs/content/docs/en/next/guides/dictionaries.mdx
+++ b/apps/docs/content/docs/en/next/guides/dictionaries.mdx
@@ -1,281 +1,313 @@
 ---
 title: Dictionaries
-description: How to use dictionaries
+description: How to use traditional dictionary-based translation patterns
 ---
 
-## Overview
-
-In this guide, we will introduce you to dictionaries.
-Please feel free to skip around this page as needed.
-We will cover the following:
-
-<Steps>
-  <Step>
-    What is a dictionary?
-  </Step>
-  <Step>
-    How to use dictionaries
-  </Step>
-  <Step>
-    Loading dictionaries for other languages
-  </Step>
-  <Step>
-    Using dictionaries
-  </Step>
-  <Step>
-    Production considerations
-  </Step>
-</Steps>
+Dictionaries provide a traditional approach to organizing translations in nested objects with key-value pairs. While [`<T>` components](/docs/next/guides/jsx) are the recommended approach, dictionaries can be useful for migration from other i18n libraries or when you prefer centralized translation storage.
 
 <Callout>
-  **Note:** We do not recommend using dictionaries if you are using `gt-next`. Instead, please check out the [`<T>`](/docs/next/api/components/t) component.
-
-  This guide is intended for those who are already familiar with dictionaries and want to learn how to use them with `gt-next`, or those who are 
-  trying to migrate from another i18n library to `gt-next`.
+  **Recommendation:** Use [`<T>` components](/docs/next/guides/jsx) for new projects. Dictionaries are supported primarily for migration and compatibility with existing translation workflows.
 </Callout>
 
----
-
-## What is a dictionary?
-
-A dictionary is a nested object with string values that can be used to store translatable content.
-They can be stored in a `.ts`, `.js`, or `.json` file.
-
-`gt-next` allows you to use dictionaries standalone, or in conjunction with [`<T>`](/docs/next/api/components/t) components.
-
-### Dictionary vs `<T>` Components
-
-The dictionary pattern has a few advantages over the [`<T>`](/docs/next/api/components/t) component:
-
-1. **Centralized Storage**: Dictionaries store all translatable content in a single file.
-2. **Historical Precedent**: The dictionary pattern is a common design pattern in the industry and is used by many other i18n libraries.
-
-At the same time, it has several major disadvantages:
-
-1. **Complexity**: Dictionaries are more complex to set up and use than the `<T>` component.
-2. **Readability**: Dictionaries are less readable than the `<T>` component because the content is not inline.
-3. **Maintainability**: Dictionaries are more difficult to maintain than the `<T>` component because the content is not inline, and is instead stored separately. 
-This makes maintaining and updating translations much more difficult.
-4. **Debuggability**: For the same reason, dictionaries are more difficult to debug than the `<T>` component.
-When trying to debug a React component, you will have to track down where the content in the dictionary is being used, rather than just directly searching your codebase.
-
-Both design patterns are supported by our library and are not mutually exclusive.
-You can use a dictionary alongside `<T>` components.
-
-### Our advice
+## Dictionary vs Component Translation
 
-We recommend using the [`<T>`](/docs/next/api/components/t) component because of its simplicity especially if you are new to internationalization (i18n).
-We offer dictionary support for those who prefer this design pattern from past experiences or for ease of integration with existing code bases.
+### Dictionary Pattern
+```tsx
+// dictionary.ts
+export default {
+  greetings: {
+    hello: 'Hello, world!',
+    welcome: 'Welcome, {name}!'
+  }
+};
 
----
+// Component usage
+function MyComponent() {
+  const d = useTranslations();
+  return <div>{d('greetings.hello')}</div>;
+}
+```
 
-## How to use dictionaries
+### Component Pattern  
+```tsx
+// Direct component usage - recommended
+function MyComponent() {
+  return <T><div>Hello, world!</div></T>;
+}
+```
 
-In this section, we will show you how to set up a bare-bones dictionary implementation in your Next.js application.
-We will walk through the following steps:
+## Trade-offs
 
-<Steps>
-    <Step>
-        Create a dictionary
-    </Step>
-    <Step>
-        Reference the dictionary
-    </Step>
-</Steps>
+### Dictionary Advantages
+- **Centralized storage** - All translations in one place
+- **Industry standard** - Familiar pattern from other i18n libraries
+- **Migration friendly** - Easy to port existing translations
 
-### Step 1: Create a dictionary
+### Dictionary Disadvantages  
+- **Complexity** - More setup and configuration required
+- **Maintainability** - Content separated from usage makes updates harder
+- **Debuggability** - Harder to trace translations back to components
+- **Readability** - Keys don't show actual content
 
-The first step is to create a dictionary.
-This is a `dictionary.[js|ts|json]` file that contains all the content you want to translate.
+## Quick Start
 
-Add the following content to your `dictionary` file:
+### Step 1: Create Dictionary
+Create a dictionary file in your project root or `src` directory:
 
-```ts title="src/dictionary.ts" copy
+```ts title="dictionary.ts"
 const dictionary = {
   greetings: {
-    hello: 'Hello, world!'
+    hello: 'Hello, world!',
+    welcome: 'Welcome to our app!'
   },
-}
+  navigation: {
+    home: 'Home',
+    about: 'About',
+    contact: 'Contact'
+  }
+};
 
 export default dictionary;
 ```
 
-<Callout>
-  You can also use a `dictionary.json` file to store your dictionary. This is useful if you are migrating from a different library or if you prefer to use JSON files.
-  Here is an example of a `dictionary.json` file:
-
-```json title="src/dictionary.json" copy
+Or use JSON format:
+```json title="dictionary.json"
 {
   "greetings": {
-    "hello": "Hello, world!"
+    "hello": "Hello, world!",
+    "welcome": "Welcome to our app!"
+  },
+  "navigation": {
+    "home": "Home", 
+    "about": "About",
+    "contact": "Contact"
   }
 }
-``` 
-
-</Callout>
+```
 
 The [`withGTConfig()`](/docs/next/api/config/withGTConfig) function will automatically pick up the dictionary file in your project root or `src` directory.
 
-### Step 2: Reference the dictionary
-
-You can access dictionary entries with the [`useTranslations()`](/docs/next/api/dictionary/useTranslations) hook or the [`getTranslations()`](/docs/next/api/dictionary/getTranslations) function.
-Just use the function returned by the hook to access the dictionary entries by key.
+### Step 2: Use in Components
 
-<Callout>
-  **Note:**
-  `useTranslations()` should only be used in synchronous components. For async components, use the `getTranslations()` function instead.
-</Callout>
+The [`useTranslations()`](/docs/react/api/dictionary/useTranslations) hook lets you access dictionary entries:
 
-```tsx title="src/components/MyComponent.tsx" copy
+#### Client Components
+```tsx
 import { useTranslations } from 'gt-next';
 
-export default function MyComponent() {
+function MyComponent() {
   const d = useTranslations();
+  
   return (
     <div>
-      {d('greetings.hello')}
+      <h1>{d('greetings.hello')}</h1>
+      <p>{d('greetings.welcome')}</p>
     </div>
   );
 }
 ```
 
-```tsx title="src/components/MyComponent.tsx" copy
+#### Server Components
+```tsx
 import { getTranslations } from 'gt-next/server';
 
-export default async function MyComponent() {
+async function MyServerComponent() {
   const d = await getTranslations();
+  
   return (
     <div>
-      {d('greetings.hello')}
+      <h1>{d('greetings.hello')}</h1>
+      <p>{d('greetings.welcome')}</p>
     </div>
   );
 }
 ```
----
-
-## Loading dictionaries for other languages [#other-languages]
-
-By default, developers only provide a dictionary for the default language.
-
-General Translation automatically generates dictionaries for other languages and loads them with the [`loadTranslations`](/docs/next/api/config/load-translations) function.
 
-However, if you are migrating from another i18n library or already have dictionaries for other languages, you can pass them to the [`loadDictionary`](/docs/next/api/config/load-dictionary) function.
+## Using Variables
 
-`gt-next` will automatically load the corresponding dictionary for the requested locale when using the `useTranslations()` hook or `getTranslations()` function.
+Add variables to dictionary entries using `{variable}` syntax:
 
-See the [API Reference](/docs/next/api/config/load-dictionary) for more information.
-
----
-
-## Using dictionaries [#usage]
-
-### Variables
-
-You can add variables to your dictionary by using the `{variable}` syntax:
-
-```ts title="src/dictionary.ts" copy
+```ts title="dictionary.ts"
 const dictionary = {
-  greetings: {
-    hello: 'Hello, {name}!',    // -> Hello, Alice!
-    goodbye: 'Goodbye, {name}!' // -> Goodbye, Bob!
-  },
-}
-export default dictionary;
+  user: {
+    greeting: 'Hello, {name}!',
+    itemCount: 'You have {count} items',
+    orderTotal: 'Total: ${amount}'
+  }
+};
 ```
-```tsx title="src/components/MyComponent.tsx" copy
-import { useTranslations } from 'gt-next';
 
-export default function MyComponent() {
+```tsx
+function UserDashboard() {
   const d = useTranslations();
+  
   return (
     <div>
-      {d('greetings.hello', { name: 'Alice' })}
-      {d('greetings.goodbye', { name: 'Bob' })}
+      <h1>{d('user.greeting', { name: 'Alice' })}</h1>
+      <p>{d('user.itemCount', { count: 5 })}</p>
+      <p>{d('user.orderTotal', { amount: 99.99 })}</p>
     </div>
   );
 }
 ```
 
-Read more about adding variables to your dictionary in the [`DictionaryTranslationOptions` type](/docs/next/api/types/DictionaryTranslationOptions).
-
-Dictionary strings in `gt-next` support ICU message format, which allows you to also format your variables.
-
+## Using Prefixes
 
-### Prefixes
+Scope dictionary access to specific sections using prefixes:
 
-Additionally, with [`useTranslations()`](/docs/next/api/dictionary/useTranslations), you can pass in a prefix to the function to specify a shared path in the dictionary.
-This is useful if you have a shared path in your dictionary that you want to use in multiple components.
-
-```jsx title="src/dictionary.js" copy
+```ts title="dictionary.ts"
 const dictionary = {
-  greetings: {
-    common: {
-      hello: 'Hello, world!',
-      goodbye: 'Goodbye, World!'
+  dashboard: {
+    header: {
+      welcome: 'Welcome back!',
+      lastLogin: 'Last login: {date}'
     },
-  },
-}
-export default dictionary;
+    stats: {
+      totalUsers: 'Total Users: {count}',
+      activeUsers: 'Active Users: {count}'
+    }
+  }
+};
 ```
 
-```jsx title="src/components/MyComponent.js" copy
-import { useTranslations } from 'gt-next';
-
-export default function MyComponent() {
-  // All translation paths such as 'hello' will be prefixed with 'greetings.common.'
-  const d = useTranslations('greetings.common'); // [!code highlight]
+```tsx
+function DashboardHeader() {
+  // Prefix limits access to 'dashboard.header'
+  const d = useTranslations('dashboard.header');
+  
+  return (
+    <header>
+      <h1>{d('welcome')}</h1> {/* -> dashboard.header.welcome */}
+      <p>{d('lastLogin', { date: 'Today' })}</p> {/* -> dashboard.header.lastLogin */}
+    </header>
+  );
+}
 
+function DashboardStats() {
+  // Different prefix for stats section
+  const d = useTranslations('dashboard.stats');
+  
   return (
     <div>
-      {d('hello')} {/* hello -> greetings.common.hello */}
-      {d('goodbye')} {/* goodbye -> greetings.common.goodbye */}
+      <p>{d('totalUsers', { count: 1000 })}</p> {/* -> dashboard.stats.totalUsers */}
+      <p>{d('activeUsers', { count: 150 })}</p> {/* -> dashboard.stats.activeUsers */}
     </div>
   );
 }
 ```
 
----
-
-## Production considerations
+## Multiple Language Support
 
-### Deploying to production
+### Automatic Translation (Recommended)
+Most users should use [`loadTranslations()`](/docs/next/api/config/load-translations) to automatically generate translations from your base dictionary:
 
-Make sure to run the translate command before deploying to production, so that all translations are available at runtime.
-We recommend adding it to your in your CD pipeline or as a part of your build script.
-```json title="package.json" copy
-{
-  "scripts": {
-    "build": "npx gtx-cli translate && <YOUR_BUILD_COMMAND>",
+```ts title="dictionary.ts"  
+const dictionary = {
+  common: {
+    save: 'Save',
+    cancel: 'Cancel',
+    delete: 'Delete'
+  },
+  forms: {
+    required: 'This field is required',
+    email: 'Please enter a valid email'
   }
+};
+
+export default dictionary;
+```
+
+Create a `loadTranslations()` function to load generated translation files:
+
+```js title="src/loadTranslations.ts"
+export default async function loadTranslations(locale) {
+  const translations = await import(`../public/locales/${locale}.json`);
+  return translations.default;
 }
 ```
 
-For a more detailed guide on deploying your application, please refer to the [Deployment](/docs/next/tutorials/quickdeploy) guide.
-For more information on the command, please refer to the [CLI Tool](/docs/cli/translate) reference guide.
+[`withGTConfig()`](/docs/next/api/config/withGTConfig) automatically picks up the `loadTranslations.[js|ts]` file from your `src/` directory or project root.
 
-### Behavior: Development vs Production
+GT automatically generates translations for other languages based on your base dictionary. Run `npx gtx-cli translate` to generate translations for all configured languages.
 
-In development, the function returned by the `useTranslations()` hook will translate dictionary entries on-demand.
-This means that when the component is rendered, it will perform a translation immediately.
-We do this for convenience to make development with other languages easier.
+### Manual Translation Files (Migration)
+For migration from other i18n libraries or manual translation management, use [`loadDictionary`](/docs/next/api/config/load-dictionary):
 
-To enable this behavior, just add a [Dev API key](/docs/next/concepts/environments) to your environment.
+```ts title="src/loadDictionary.ts"
+export default async function loadDictionary(locale: string) {
+  const translations = await import(`../public/locales/${locale}.json`);
+  return translations.default;
+}
+```
 
-In production, the `d()` function will translate content at build time.
-This means that you have to run the translation command before deploying your application.
+This loads JSON translation files from your `public/locales/` directory:
+
+<Files>
+  <Folder name="my-app" defaultOpen={true}>
+    <Folder name="public" defaultOpen={true}>
+      <Folder name="locales" defaultOpen={true}>
+        <File name="es.json" />
+        <File name="fr.json" />
+        <File name="de.json" />
+      </Folder>
+    </Folder>
+    <Folder name="src">
+      <File name="loadDictionary.ts" />
+    </Folder>
+  </Folder>
+</Files>
 
 <Callout>
-  **Tip:**
-  If you want to simulate production behavior in development, just use a production API key in your development build.
+  **Choose the right approach:** Use [`loadTranslations()`](/docs/next/api/config/load-translations) for new projects with automatic translation generation, or [`loadDictionary()`](/docs/next/api/config/load-dictionary) when migrating existing translation files.
 </Callout>
 
----
+## Production Setup
+
+### Build Process
+Add translation to your build pipeline:
+
+```json title="package.json"
+{
+  "scripts": {
+    "build": "npx gtx-cli translate && <...YOUR_BUILD_COMMAND...>"
+  }
+}
+```
+
+### Development vs Production Behavior
+- **Development**: Dictionary entries translated on-demand with dev API key
+- **Production**: All dictionary translations pre-built during build step
+
+## Combining with Components
+
+Dictionaries and [`<T>` components](/docs/next/guides/jsx) can work together:
+
+```tsx
+function MixedApproach() {
+  const d = useTranslations();
+  
+  return (
+    <div>
+      {/* Dictionary for simple strings */}
+      <h1>{d('page.title')}</h1>
+      
+      {/* T component for complex JSX */}
+      <T>
+        <p>This is a <strong>complex message</strong> with <a href="/link">links</a>.</p>
+      </T>
+      
+      {/* Dictionary for form labels */}
+      <label>{d('forms.email')}</label>
+    </div>
+  );
+}
+```
 
-## Notes
- * Dictionaries are an alternative to the `<T>` component. They can be used in conjunction with `<T>` components or standalone.
- * Dictionary translations occur at build time, so you have to add the [`translate`](/docs/cli/translate) command to your build process.
- * Dictionaries can be used with prefixes to specify a subset of the dictionary.
+## Next Steps
 
-## Next steps
- * Learn about the [`<T>` component](/docs/next/api/components/t) and how to use it in your Next.js application.
- * Learn how to ship to production with our [deployment guide](/docs/next/tutorials/quickdeploy).
\ No newline at end of file
+- [Languages Guide](/docs/next/guides/languages) - Configure supported languages and locale settings
+- [Dynamic Content Guide](/docs/next/guides/dynamic-content) - Handle runtime translation needs
+- API References:
+  - [`useTranslations()` Hook](/docs/next/api/dictionary/useTranslations)
+  - [`getTranslations()` Function](/docs/next/api/dictionary/getTranslations)
+  - [`loadDictionary()` Function](/docs/next/api/config/load-dictionary)
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/next/guides/dynamic-content.mdx b/apps/docs/content/docs/en/next/guides/dynamic-content.mdx
index 645015b8c..81137f4ed 100644
--- a/apps/docs/content/docs/en/next/guides/dynamic-content.mdx
+++ b/apps/docs/content/docs/en/next/guides/dynamic-content.mdx
@@ -1,144 +1,155 @@
 ---
-title: Translating Dynamic Content
-description: How to translate dynamic content in Next.js server components
+title: Dynamic Content
+description: How to translate runtime content using server-side translation APIs
 ---
 
-## Overview
+Dynamic content translation handles text that isn't available at build time - user-generated content, API responses, or database records. Use [`<Tx>`](/docs/next/api/components/tx) for JSX content and [`tx()`](/docs/next/api/strings/tx) for plain strings, both server-side only for security.
 
-This guide will walk you through how to use the [`<Tx>` component](/docs/next/api/components/tx) and the [`tx()`](/docs/next/api/strings/tx) function to translate dynamic content in Next.js server components.
-
-By the end of this guide, you will learn the proper syntax for using these components and functions.
-
-We will cover the following:
+<Callout type="warn">
+  **Use sparingly:** Dynamic translation consumes API quota and adds latency. Prefer [`<T>` components](/docs/next/guides/jsx) with [variable components](/docs/next/guides/variables) whenever possible.
+</Callout>
 
-<Steps>
-  <Step>
-    What is dynamic content?
-  </Step>
-  <Step>
-    When should you translate dynamic content?
-  </Step>
-  <Step>
-    How to use the `<Tx>` component
-  </Step>
-  <Step>
-    How to use the `tx()` function
-  </Step>
-  <Step>
-    Examples
-  </Step>
-  <Step>
-    Production considerations
-  </Step>
-  <Step>
-    Common pitfalls
-  </Step>
-</Steps>
+## When to Use Dynamic Translation
 
-## What is dynamic content?
+Dynamic translation is for content that truly cannot be known at build time:
 
-Dynamic content is content that is not known at build time.
+### Appropriate Use Cases
+- **User-generated content**: Chat messages, reviews, social posts
+- **External API responses**: Third-party data, RSS feeds, external services  
+- **Database records**: Dynamic CMS content, user profiles from APIs
+- **Real-time data**: Live notifications, status messages
 
-These could include things like variables, user names, input fields, etc.
+### Avoid for These Cases
+- User names, account numbers → Use [`<Var>`](/docs/next/api/components/var)
+- Conditional messages → Use [branch components](/docs/next/guides/branches)
+- Form validation → Use [string translation](/docs/next/guides/strings)
+- Static configuration → Use [shared strings](/docs/next/guides/shared-strings)
 
-For example, the following is dynamic content:
+## Quick Start
 
+### JSX Content with `<Tx>`
 ```jsx
-const username = 'John Doe';
-<p>Your username is {username}</p>
-```
-
-## When should you translate dynamic content?
-
-In most cases, you can use [Variable Components](/docs/next/guides/variables) or [Branching Components](/docs/next/guides/branches) to handle dynamic content.
-
-These components are designed to handle dynamic content with the `<T>` component, and thus we recommend using them whenever possible.
-
-However, there are some cases where you need to translate dynamic content on-demand.
-
-For example, if you have a chat message that is created by a user, and want to display it in a different language, you can use `gt-next` to translate it on-demand.
-
-## How to use the `<Tx>` component
-
-<Callout type="warn">
-  The `<Tx>` component is only available in Next.js server components. 
-  This is because it hits the General Translation API using an API key, which is only available on the server for security reasons.
-</Callout>
-
-```jsx copy
 import { Tx } from 'gt-next';
 
-const message = 'Hello, world!';
-<Tx>{message}</Tx>
+async function UserPost({ postContent }) {
+  return (
+    <article>
+      <Tx>{postContent}</Tx>
+    </article>
+  );
+}
 ```
 
-Simply wrap whatever JSX content you want to translate with the `<Tx>` component.
-
-The `<Tx>` component will then translate the content on-demand, and render the translated content asynchronously.
-
-See the [API reference](/docs/next/api/components/tx) for more information.
+### Plain Strings with `tx()`
+```jsx
+import { tx } from 'gt-next/server';
 
-## How to use the `tx()` function
+async function NotificationBanner({ message }) {
+  const translatedMessage = await tx(message);
+  
+  return (
+    <div className="banner">
+      {translatedMessage}
+    </div>
+  );
+}
+```
 
-<Callout type="warn">
-  The `tx()` function is only available in Next.js server components.
-  This is because it hits the General Translation API using an API key, which is only available on the server for security reasons.
-</Callout>
+## Server-Side Only
 
-The `tx()` function is a server-side function that can be used to translate strings dynamically.
+Both [`<Tx>`](/docs/next/api/components/tx) and [`tx()`](/docs/next/api/strings/tx) are server-side only for security:
 
-```jsx copy
-import { tx } from 'gt-next/server';
+```jsx
+// ✅ Server component
+async function ServerComponent() {
+  const translated = await tx(dynamicContent);
+  return <div>{translated}</div>;
+}
 
-const message = 'Hello, world!';
-const translatedMessage = await tx(message);
+// ❌ Client component - won't work
+'use client';
+function ClientComponent() {
+  const translated = await tx(dynamicContent); // Error!
+  return <div>{translated}</div>;
+}
 ```
 
-The `tx()` function returns a promise that resolves to the translated string.
-
-See the [API reference](/docs/next/api/strings/tx) for more information.
-
 ## Examples
 
-### Rendering dynamic content
-
-```jsx copy
+### User-Generated Content
+```jsx
 import { Tx } from 'gt-next';
 
-export default function ChatMessage({ message }: { message: ReactNode }) {
+async function ChatMessage({ message }) {
   return (
-    <Tx>{message}</Tx>
+    <div className="chat-message">
+      <div className="author">{message.author}</div>
+      <Tx>{message.content}</Tx>
+    </div>
   );
 }
 ```
 
-### Translating a string
-
-```jsx copy
+### External API Data
+```jsx
 import { tx } from 'gt-next/server';
 
-export default async function ChatMessage({ message }: { message: string }) {
-  const translatedMessage = await tx(message);
+async function NewsArticle({ article }) {
+  const translatedTitle = await tx(article.title);
+  
   return (
-    <div>{translatedMessage}</div>
+    <article>
+      <h1>{translatedTitle}</h1>
+      <p>{article.publishedAt}</p>
+    </article>
   );
 }
 ```
 
-## Production considerations
+### Mixed Content
+```jsx
+import { T, Tx, Var } from 'gt-next';
 
-The behavior of the `<Tx>` component and the `tx()` function is the same in development as it is in production.
+async function ProductReview({ review }) {
+  return (
+    <div>
+      {/* Static content with variables */}
+      <T>
+        <p><Var>{review.author}</Var> rated this <Var>{review.rating}</Var> stars</p>
+      </T>
+      
+      {/* Dynamic user content */}
+      <Tx>{review.content}</Tx>
+    </div>
+  );
+}
+```
 
-Regardless of the type of API key you use, the behavior is the same.
-In both cases, translations are completed live, on-demand.
+## Common Issues
 
-## Common pitfalls
+### Avoid Overuse
+Don't use dynamic translation for content that can use standard components:
 
-### Unnecessary use of `<Tx>` and `tx()`
+```jsx
+// ❌ Unnecessary
+const content = `Hello, ${userName}!`;
+return <Tx>{content}</Tx>;
+
+// ✅ Use variable components instead
+return (
+  <T>
+    <p>Hello, <Var>{userName}</Var>!</p>
+  </T>
+);
+```
 
-If you are using the `<Tx>` component or the `tx()` function, you should only do so if you are truly unable to use
-[Variable Components](/docs/next/guides/variables) or [Branching Components](/docs/next/guides/branches) with the `<T>` component.
+### API Quota Impact
+Dynamic translation consumes API quota on every request. Use caching and error handling in production applications.
 
-Using `<Tx>` and `tx()` when you don't need to is a waste of resources, and will quickly use up your API quota.
+## Next Steps
 
-Additionally, your content will be rendered slower, as the translations are completed on-demand.
\ No newline at end of file
+- [Local Translation Guide](/docs/next/guides/local-tx) - Handle translations without API calls
+- [Middleware Guide](/docs/next/guides/middleware) - Language detection and routing
+- API References:
+  - [`<Tx>` Component](/docs/next/api/components/tx)
+  - [`tx()` Function](/docs/next/api/strings/tx)
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/next/guides/jsx.mdx b/apps/docs/content/docs/en/next/guides/jsx.mdx
deleted file mode 100644
index 1da7e920c..000000000
--- a/apps/docs/content/docs/en/next/guides/jsx.mdx
+++ /dev/null
@@ -1,427 +0,0 @@
----
-title: Translating JSX
-description: How to internationalize JSX components
----
-
-## Overview
-
-This guide will walk you through how to use the [`<T>` component](/docs/next/api/components/t) to internationalize JSX content.
-
-By the end of this guide, you will know the correct syntax for using the `<T>` component and what to avoid.
-
-We will cover the following:
-<Steps>
-  <Step>
-    How to use the `<T>` component
-  </Step>
-  <Step>
-    Additional options
-  </Step>
-  <Step>
-    When to use the `<T>` component
-  </Step>
-  <Step>
-    Examples
-  </Step>
-  <Step>
-    Production considerations
-  </Step>
-  <Step>
-    Common pitfalls
-  </Step>
-</Steps>
-
-
-If you are looking for how to use [Variable Components](/docs/next/guides/variables) or [Branching Components](/docs/next/guides/branches), please refer to their respective guides.
-
----
-
-## How to use the `<T>` component
-
-Let's say you have some HTML content that you want to translate. 
-
-```jsx
-function Greeting() {
-  return <p>Hello, world!</p>;
-}
-```
-
-All you have to do is wrap the content in a `<T>` component.
-
-```jsx
-import { T } from 'gt-next';
-
-function Greeting() {
-  return <T><p>Hello, world!</p></T>;
-}
-```
-
-Depending on the current language your user has selected, this will render the appropriate translation. 
-See [switching languages](/docs/next/guides/languages) for more information on how to allow your users to switch languages.
-
----
-
-## Additional Options
-
-### Context
-
-In some cases, you may want to provide additional context to the translation.
-This can be done by passing a `context` prop to the `<T>` component.
-
-```jsx
-<T context="toast, as in a pop-up notification">
-  Click on the toast to dismiss it.
-</T>
-```
-
-This is useful in cases where words may have multiple meanings depending on the context.
-For example, "toast" can refer to the food or a pop-up notification.
-
-The context prop is helpful for the AI to understand the intent of the translation.
-
-### `id`
-
-You can also pass an `id` prop to the `<T>` component.
-This is useful for debugging purposes and makes editing the translation easier.
-
-```jsx
-<T id="toast">
-  Click on the toast to dismiss it.
-</T>
-```
-
----
-
-## When to use the `<T>` component
-
-While the `<T>` component is very flexible, it is not always the best solution.
-
-You should always try to use the `<T>` component when you have any **static HTML or JSX content.**
-
-### When not to use the `<T>` component
-
-**DO NOT** use the `<T>` component when you have any unsafe **dynamic** content.
-
-Here, dynamic content means any content that could change at runtime. 
-This rule does not apply if you are using [Variable Components](/docs/next/guides/variables) or [Branching Components](/docs/next/guides/branches).
-
-<Callout>
-  **Note:**
-  
-  Variable components are a special case where the content is dynamic, but the content has been wrapped and sanitized, so it is safe to use the `<T>` component.
-
-  Content wrapped in variable components are never translated directly by the `<T>` component.
-</Callout>
-
-
-The following examples show invalid usage of the `<T>` component:
-
-```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>
-```
-
-<Callout>
-  In the above examples, the content can be safely internationalized using [variable components](/docs/next/guides/variables) and [branching components](/docs/next/guides/branches).
-</Callout>
-
-```jsx
-const chatMessage = getChatMessageFromServer();
-<T>
-  <p>{chatMessage}</p>
-</T>
-```
-
-<Callout>
-  In this example, the content is fully dynamic, so it should be translated on the server side before being passed to the client.
-
-  See the [core](/docs/core) library for more information on how to dynamically translate content via our API.
-</Callout>
-
----
-
-## Examples
-
-Here are some examples of how to use the `<T>` component. These are all correct.
-
-1. HTML content
-<Tabs items={['Result', 'Original']}>
-  <Tab value="Result">
-```jsx
-<T>
-  <p>Hello, world!</p>
-</T>
-```
-  </Tab>
-  <Tab value="Original">
-    ```jsx
-    <p>Hello, world!</p>
-    ```
-  </Tab>
-</Tabs>
-
-2. Simple JSX content
-<Tabs items={['Result', 'Original']}>
-  <Tab value="Result">
-```jsx
-<T>
-  <Button>Click me!</Button>
-</T>
-```
-  </Tab>
-  <Tab value="Original">
-    ```jsx
-    <Button>Click me!</Button>
-    ```
-  </Tab>
-</Tabs>
-
-3. Complex JSX content
-<Tabs items={['Result', 'Original']}>
-  <Tab value="Result">
-```jsx
-<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>
-```
-  </Tab>
-  <Tab value="Original">
-    ```jsx
-    <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>
-    ```
-  </Tab>
-  </Tabs>
-
-
-
-
-
-
-<Callout>
-  The `<T>` component can handle any nested content in the same component.
-</Callout>
-
----
-
-## Production Considerations [#production]
-
-
-### Deploying to production
-
-Make sure to run the translate command before deploying to production, so that all translations are available at runtime.
-We recommend adding it to your CD pipeline or as a part of your build script.
-```json title="package.json" copy
-{
-  "scripts": {
-    "build": "npx gtx-cli translate && <YOUR_BUILD_COMMAND>",
-  }
-}
-```
-
-For a more detailed guide on deploying your application, please refer to the [Deployment](/docs/next/tutorials/quickdeploy) tutorial.
-For more information on the command, please refer to the [CLI Tool](/docs/cli/translate) reference guide.
-
-### Behavior: Development vs Production
-
-In development, the `<T>` component will translate content on-demand.
-This means that when the component is rendered, it will perform a translation immediately.
-The library does this for convenience to make development with other languages easier.
-
-To enable this behavior, just add a Dev API key to your environment.
-
-In production, all translations that the `<T>` component uses are completed at build time.
-This means that you have to run the translation command before deploying your application.
-
-<Callout>
-  **Tip:**
-  If you want to simulate production behavior in development, just use a production API key in your development build.
-</Callout>
-
-### Privacy Concerns
-
-With some exceptions, all content wrapped in a `<T>` component is sent to the General Translation API for translation.
-This might not be desirable for rendering sensitive data, such as usernames, account numbers, etc.
-
-To circumvent this issue, use [Variable Components](/docs/next/guides/variables#privacy) to handle private information.
-This ensures that no sensitive data is sent to the General Translation API for translation.
-Localization of any content wrapped in a variable component is handled locally.
-
----
-
-## Common Pitfalls
-
-
-### Direct descendants only [#direct-text]
-
-The `<T>` component only translates text passed directly as a child.
-This means that if you have content inside a component that is not directly passed to `<T>`, it will not be translated.
-
-Let's illustrate this with an example:
-
-```jsx copy
-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>
-  );
-}
-```
-
-In this example, the content inside `<UntranslatedContent>` will not be translated.
-Only the content directly inside `<T>` will be translated, like the `<h1>` tag and its children.
-
-<Accordions>
-  <Accordion title="Why does this happen?">
-    This occurs because of how React renders components.
-    It is a bit complicated, but the gist is that React does not know the content of a component until it has rendered.
-    Therefore, the contents of components like `<UntranslatedContent>` are not translated.
-    However, any text directly between the two `<T>` tags will be translated.
-  </Accordion>
-</Accordions>
-<Callout>
-  **Note:** A good rule of thumb is that any content that is *literally* between the two `<T>` tags in the file will be translated.
-  You can always add another `<T>` to translate the content that is not being translated, though nesting `<T>` components is not recommended.
-</Callout>
-
-#### What's the fix?
-
-Wrap the text in the `<T>` component directly, like so:
-
-```jsx copy
-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 [#nested-t]
-
-Nesting `<T>` components is not allowed.
-Because of React's rendering system, this can lead to unexpected behavior and performance issues.
-
-Here is an example of **what not to do**:
-
-```jsx copy
-function SomeComponent() {
-  return (
-    <T>
-      Hello, friend!
-    </T>
-  );
-}
-
-export default function NestedTranslation() {
-  return (
-    <T>
-      <T> {/* Don't do this! */} 
-        Hello, world! 
-      </T>
-      <SomeComponent /> {/* This still counts. Don't do this! */}
-    </T>
-  );
-}
-```
-
-The solution here is to remove the outtermost `<T>` component.
-
-### Translating dynamic content
-
-If you attempt to wrap dynamic content with the `<T>` component, the CLI tool will error.
-
-For example, the following will error:
-
-```jsx
-const username = 'John Doe';
-<T>
-  <p>Your username is {username}</p>
-</T>
-```
-
-To get around this, try to use [Variable Components](/docs/next/guides/variables) or [Branching Components](/docs/next/guides/branches) to wrap the dynamic content.
-
-Alternatively, if your content truly is dynamic and needs to be translated on-demand, 
-you can use the [`<Tx>` component](/docs/next/guides/dynamic-content).
-
-
----
-
-## Summary
- * `<T>` components are used to internationalize arbitrary JSX Content.
- * `<T>` components should not be used for dynamic content, without using variable components or branching components.
- * In development, the `<T>` component will translate content on-demand.
- * In production, all translations that the `<T>` component uses are completed at build time.
-
-## Next Steps
- * Read about the [API](/docs/next/api/components/t) for the `<T>` component.
- * Explore [Variable Components](/docs/next/guides/variables) and [Branching Components](/docs/next/guides/branches).
- * Learn about [translating strings](/docs/next/guides/strings).
-
diff --git a/apps/docs/content/docs/en/next/guides/languages.mdx b/apps/docs/content/docs/en/next/guides/languages.mdx
index 7d0778222..6391ee794 100644
--- a/apps/docs/content/docs/en/next/guides/languages.mdx
+++ b/apps/docs/content/docs/en/next/guides/languages.mdx
@@ -1,29 +1,24 @@
 ---
 title: Changing Languages
-description: How to change the language of your Next.js app
+description: How to configure and switch between languages in your Next.js app
 ---
 
-## Overview
+Language switching allows users to change their preferred locale for your application's content. GT Next provides several approaches from simple programmatic switching to full URL-based routing with middleware.
 
-In this guide, we'll show you how to change the language of your Next.js app.
+## Available Methods
 
-If you have not yet setup your app with `gt-next`, please refer to the [quickstart guide](/docs/next) before continuing.
+- **Programmatic**: [`useSetLocale()`](/docs/next/api/helpers/useSetLocale) hook for custom controls
+- **Pre-built UI**: [`<LocaleSelector>`](/docs/next/api/components/localeSelector) component with dropdown
+- **Custom UI**: [`useLocaleSelector()`](/docs/next/api/helpers/useLocaleSelector) hook for building custom selectors
+- **URL-based**: [Middleware routing](/docs/next/guides/middleware) for locale in URL paths
 
-There are three ways to change the language of your app using `gt-next`.
+## Using the `useSetLocale()` hook
 
-1. Using the [`useSetLocale()`](/docs/next/api/helpers/useSetLocale) hook
-2. Using the [`<LocaleSelector>`](/docs/next/api/components/localeSelector) component
-3. Using the [`useLocaleSelector()`](/docs/next/api/helpers/useLocaleSelector) hook
-4. Using [middleware i18n routing](/docs/next/guides/middleware)
-
-We'll cover the first three methods in this guide. See the [middleware routing](/docs/next/guides/middleware) guide for more information on how to change the language of your app using middleware.
-
-## Using the `useSetLocale` hook
-
-The `useSetLocale` hook is a client-side hook that allows you to change the language of your app. It must be used within a `GTProvider` component.
+The [`useSetLocale`](/docs/next/api/helpers/useSetLocale) hook is a client-side hook that allows you to change the language of your app:
 
 ```tsx
- } from 'gt-next/client';
+import { useSetLocale } from 'gt-next/client';
+
 export default function MyComponent() {
   const setLocale = useSetLocale();
 
@@ -31,13 +26,11 @@ export default function MyComponent() {
 }
 ```
 
-Simply provide the locale you want to change to as the argument to the callback function returned by the `useSetLocale` hook.
+Simply provide the locale you want to change to as the argument to the function returned by the hook.
 
 ## Using the `<LocaleSelector>` component
 
-The `<LocaleSelector>` component is a client-side component that allows you to change the language of your app. It must be used within a `GTProvider` component.
-
-This is a bare-bones UI dropdown that displays all the locales you have enabled in your project, and allows users to select a different locale.
+The [`<LocaleSelector>`](/docs/next/api/components/localeSelector) component provides a ready-to-use dropdown that automatically shows all configured locales:
 
 ```tsx
 import { LocaleSelector } from 'gt-next/client';
@@ -47,67 +40,92 @@ export default function MyComponent() {
 }
 ```
 
-## Using the `useLocaleSelector` hook
-
-Alternatively, if you would like to create your own locale selector component, you can use the `useLocaleSelector` hook.
+This component automatically:
+- Shows all configured locales for your project
+- Displays locales in their native language names
+- Handles the switching logic
+- Maintains current selection state
 
-This hook returns the current locale, the list of locales your project supports, and the `useSetLocale` hook.
+## Using the `useLocaleSelector()` hook
 
-Here is an example of how to use the `useLocaleSelector` hook to create a custom locale selector component.
+If you want to build your own custom locale selector component, use [`useLocaleSelector()`](/docs/next/api/helpers/useLocaleSelector):
 
-```tsx copy
-import { useLocaleSelector, useGTClass } from 'gt-next/client';
-
-function capitalizeLanguageName(language: string): string {
-  if (!language) return '';
+```tsx
+import { useLocaleSelector } from 'gt-next/client';
+
+function CustomLocaleSelector() {
+  const { 
+    locale,              // Current active locale (e.g., 'en', 'es')
+    locales,             // Array of locales your project supports ['en', 'es', 'fr']
+    setLocale,           // Function to change the locale: setLocale('es')
+    getLocaleProperties  // Function to get display info for a locale
+  } = useLocaleSelector();
+  
+  if (!locales?.length) return null;
+  
   return (
-    language.charAt(0).toUpperCase() +
-    (language.length > 1 ? language.slice(1) : '')
+    <select 
+      value={locale || ''} 
+      onChange={(e) => setLocale(e.target.value)}
+    >
+      {locales.map((loc) => {
+        const props = getLocaleProperties(loc);
+        return (
+          <option key={loc} value={loc}>
+            {props.nativeNameWithRegionCode} {/* e.g., "English (US)", "Español (ES)" */}
+          </option>
+        );
+      })}
+    </select>
   );
 }
+```
 
-export default function LocaleDropdown({ className }: { className?: string }) {
-  // Retrieve the locale, locales, and setLocale function
-  const { locale, locales, setLocale, getLocaleProperties } = useLocaleSelector();
+## URL-based Language Switching
 
-  // Helper function to get the display name of a locale
-  const getDisplayName = (locale: string) => {
-    return capitalizeLanguageName(
-      getLocaleProperties(locale).nativeNameWithRegionCode
-    );
-  };
+For SEO and better UX, you can include locale in your URLs using middleware routing. You can find more information about this approach in the [Middleware Guide](/docs/next/guides/middleware):
 
-  // If no locales are returned, just render nothing or handle gracefully
-  if (!locales || locales.length === 0 || !setLocale) {
-    return null;
-  }
+```
+/en/products  → English products page  
+/es/products  → Spanish products page
+/fr/products  → French products page
+```
 
-  return (
-    <Select onValueChange={setLocale} defaultValue={locale}>
-      <SelectTrigger>
-        <SelectValue placeholder='Select language' />
-      </SelectTrigger>
-      <SelectContent className='z-[200!important]' position='popper'>
-        <SelectGroup>
-          {!locale && <SelectItem value='' />}
-
-          {locales.map((locale) => (
-            <SelectItem key={locale} value={locale} suppressHydrationWarning>
-              {getDisplayName(locale)}
-            </SelectItem>
-          ))}
-        </SelectGroup>
-      </SelectContent>
-    </Select>
-  );
+This approach provides SEO benefits, direct links to language versions, and shareable localized links.
+
+## Important Notes
+
+### Client Components Only
+All language switching hooks and components must be used in client components marked with `'use client'`:
+
+```tsx
+'use client';
+import { useSetLocale } from 'gt-next/client';
+
+function LanguageSwitcher() {
+  const setLocale = useSetLocale();
+  // ... component logic
 }
 ```
 
-See the [API reference](/docs/next/api/helpers/useLocaleSelector) for more information.
+### GTProvider Requirement
+Language switching components must be used within a [`<GTProvider>`](/docs/next/api/components/gtprovider):
+
+```tsx
+// ✅ Correct
+<GTProvider>
+  <LanguageSwitcher />
+</GTProvider>
+
+// ❌ Wrong - outside provider
+<LanguageSwitcher />
+```
 
-## Next steps
+## Next Steps
 
-- Learn more about the [`useSetLocale`](/docs/next/api/helpers/useSetLocale) hook.
-- Learn more about the [`<LocaleSelector>`](/docs/next/api/components/localeSelector) component.
-- Learn more about the [`useLocaleSelector`](/docs/next/api/helpers/useLocaleSelector) hook.
-- Learn more about [middleware i18n routing](/docs/next/guides/middleware).
\ No newline at end of file
+- [Middleware Guide](/docs/next/guides/middleware) - URL-based language routing
+- [Dynamic Content Guide](/docs/next/guides/dynamic-content) - Runtime content translation  
+- API References:
+  - [`useSetLocale()` Hook](/docs/next/api/helpers/useSetLocale)
+  - [`<LocaleSelector>` Component](/docs/next/api/components/localeSelector)
+  - [`useLocaleSelector()` Hook](/docs/next/api/helpers/useLocaleSelector)
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/next/guides/local-tx.mdx b/apps/docs/content/docs/en/next/guides/local-tx.mdx
index 28af489ab..d34928fac 100644
--- a/apps/docs/content/docs/en/next/guides/local-tx.mdx
+++ b/apps/docs/content/docs/en/next/guides/local-tx.mdx
@@ -1,126 +1,139 @@
 ---
-title: Local Translations
-description: How to set up local translations for your Next.js app
+title: Local Translation Storage
+description: Store translations in your app bundle instead of using a CDN
 ---
 
 ## What are local translations?
 
-Local translations are stored in your app's bundle, as opposed to being fetched from a CDN (Content Distribution Network).
-
-Let's say that you have added the [`gtx-cli translate`](/docs/cli/translate) command to your CD process.
-This will generate translations in JSON format for your app.
-The final step is to get these translations out of our API and into your app, where they can be used.
+Local translations are stored in your app's bundle, as opposed to being fetched from a CDN (Content Distribution Network). When you add the `gtx-cli translate` command to your build process, this generates translations in JSON format. The final step is getting these translations into your app where they can be used.
 
 There are two ways to do this:
- * **In your app's bundle:** After translations are generated, save them to your app's bundle.
- * **In a CDN (default):** Fetch translations from a CDN at runtime.
 
-By default, `gt-next` will fetch translations from the General Translation CDN, and when translating your app using our API, translations will be automatically saved to our CDN.
+1. **In your app's bundle** (local): Save translations to your app's bundle after generation
+2. **In a CDN** (default): Fetch translations from a CDN at runtime
 
+By default, `gt-next` fetches translations from the General Translation CDN. When translating your app using our API, translations are automatically saved to our CDN.
 
-## Overview
+<Callout>
+  **Default behavior:** GT uses CDN storage by default. Only switch to local storage if you need the specific benefits it provides.
+</Callout>
 
-This guide will show you how to store translations in your Next.js app bundle, rather than using an external CDN, such as ours.
-This means that translations will live in your app's code and avoids reliance on external infrastructure.
+## Trade-offs
 
-In this guide, we will walk you through:
+### Benefits of Local Translations
+- **Faster load times**: Local translations are served directly from your app, loading faster than translations served from a CDN
+- **No reliance on external services**: Your app's ability to load translations isn't dependent on CDN uptime. If translations aren't found for a locale, the app automatically falls back to the default language
+- **Works offline**: Translations are bundled with your app
 
-<Steps>
-  <Step>
-    The trade-offs of using local translations.
-  </Step>
-  <Step>
-    How to set up local translations for your Next.js app.
-  </Step>
-</Steps>
+### Drawbacks of Local Translations  
+- **Increased bundle size**: Local translations increase your app's bundle size, potentially making the app slower to load initially
+- **Content management**: To edit a translation, you must redeploy your app with the new translation every time you make changes
 
+## Setup
 
+### Step 1: Create Load Function
+Add a `loadTranslations.[js|ts]` file under `./src` with the following content:
 
----
+```ts title="src/loadTranslations.ts"
+export default async function loadTranslations(locale: string) {
+  const translations = await import(`../public/_gt/${locale}.json`);
+  return translations.default;
+}
+```
 
-## Trade-offs
+[`withGTConfig()`](/docs/next/api/config/withGTConfig) automatically picks up the `loadTranslations.[js|ts]` file from your `src/` directory or project root.
 
-### What are the benefits?
+### Step 2: Configure CLI
+Run the configuration command and select local storage:
 
-1. **Faster load times:** Local translations are served directly from your app,
-meaning that they will load faster than translations served from a CDN.
+```bash
+npx gtx-cli configure
+```
 
-2. **No reliance on external services:** Your app's ability to load translations is not dependent on CDN uptime. 
-With `gt-next`, if translations are not found for a given locale, the app will automatically fall back to the default language and display the original content.
+When prompted:
+- **Save to CDN?** Select "No"  
+- **Translation directory:** Enter `./public/_gt`
 
-### What are the drawbacks?
+Alternatively, you can manually configure the `gt.config.json` file to use local translations. See the [CLI Configuration docs](/docs/cli/configuration) for more information.
 
-1. **Increased bundle size:** Local translations will increase your app's bundle size as they will be served alongside your app.
-This means that your app may take longer to load on the client.
+### Step 3: Generate Translations
+Now when you run the translate command, translations will be automatically downloaded and included in your codebase:
 
-2. **Content management:** If you want to edit a translation (i.e., you do not like how your content has been phrased in a different language),
-you must redeploy your app with the new translation every time you make changes.
+```bash
+npx gtx-cli translate
+```
 
----
+Translations will be stored in `public/_gt/` and bundled with your app.
 
-## Setup
+## Build Integration
 
-### Prerequisites
-
-Make sure that you have already setup your Next.js app with GT. 
-If not, please complete the [Quick Start Guide](/docs/next) first.
-
-
-### Steps
-<Steps>
-  <Step>
-    Add a `loadTranslations.[js|ts]` file under `./src` with the following content:
-
-    <Tabs items={['ts', 'js']}>
-      <Tab value="ts">
-        ```ts title="src/loadTranslations.ts" copy
-        export default async function loadTranslations(locale: string) {
-          const t = await import(`../public/_gt/${locale}.json`);
-          return t.default;
-        }
-        ```
-      </Tab>
-      <Tab value="js">
-        ```js title="src/loadTranslations.js" copy
-        export default async function loadTranslations(locale) {
-          const t = await import(`../public/_gt/${locale}.json`);
-          return t.default;
-        }
-        ```
-      </Tab>
-    </Tabs>
-  </Step>
-
-  <Step>
-    Run the following command in your project root, and when asked if you want to save translations on the GT CDN, select the "No" option.
-    ```bash
-    npx gtx-cli configure
-    ```
-    When asked for the path to the translations directory, enter `./public/_gt`.
-    
-    Alternatively, you can manually configure the `gt.config.json` file to use local translations.
-    See the [CLI Configuration](/docs/cli/reference/config#gt) docs for more information.
-
-    Now, when you run the translate command, translations will be automatically downloaded and included in your codebase.
-    ```bash
-    npx gtx-cli translate
-    ```
-    The `loadTranslations` function will then be used to load these translations into your app.
-  </Step>
-</Steps>
-
-That's it! Your app will now only load translations from your local files.
-
-### Further customization
-
-You can further customize the `loadTranslations` function to load translations from other sources, such as your database or your own CDN.
-See the [`loadTranslations()`](/docs/next/api/config/load-translations) docs for more information.
+### Next.js Build Process
+Add translation generation to your build script:
 
----
+```json
+{
+  "scripts": {
+    "build": "npx gtx-cli translate && <...YOUR_BUILD_COMMAND...>"
+  }
+}
+```
+
+### CI/CD Pipeline
+```yaml
+# .github/workflows/deploy.yml
+- name: Generate Translations
+  run: npx gtx-cli translate
+  
+- name: Build Application  
+  run: npm run build
+```
+
+## Common Issues
+
+### Missing Translation Files
+Ensure translations are generated before building:
+
+```bash
+# ❌ Build without translations
+<...YOUR_BUILD_COMMAND...>
+
+# ✅ Generate translations first
+npx gtx-cli translate && <...YOUR_BUILD_COMMAND...>
+```
+
+### Import Path Errors
+Match your directory structure in the load function:
+
+```ts
+// ❌ Wrong path
+const t = await import(`../translations/${locale}.json`);
+
+// ✅ Correct path for public/_gt
+const t = await import(`../public/_gt/${locale}.json`);
+```
+
+### Large Bundle Size
+Consider code splitting for apps with many languages:
+
+```ts
+// Load translations only when needed
+export default async function loadTranslations(locale: string) {
+  // Only load if locale is active
+  if (locale === getCurrentLocale()) {
+    const translations = await import(`../public/_gt/${locale}.json`);
+    return translations.default;
+  }
+  return {};
+}
+```
 
-## Notes
- * Local translations are an alternative to fetching translations from a CDN.
- * There are benefits and drawbacks to using local translations, which are discussed in the [Trade-offs](#trade-offs) section.
+<Callout>
+  Local storage works best for apps with stable translations that don't need frequent updates.
+</Callout>
 
-## Next steps
- * See [`loadTranslations()`](/docs/next/api/config/load-translations) for more information on writing a custom translation loader.
\ No newline at end of file
+## Next Steps
+
+- [Middleware Guide](/docs/next/guides/middleware) - Language detection and routing
+- [Languages Guide](/docs/next/guides/languages) - Configure supported languages
+- API References:
+  - [`loadTranslations()` Function](/docs/next/api/config/load-translations)
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/next/guides/middleware.mdx b/apps/docs/content/docs/en/next/guides/middleware.mdx
index 45e9151da..a79790cbb 100644
--- a/apps/docs/content/docs/en/next/guides/middleware.mdx
+++ b/apps/docs/content/docs/en/next/guides/middleware.mdx
@@ -1,205 +1,145 @@
 ---
-title: Middleware
-description: A step by step guide on adding internationalization (i18n) middleware routing to your application
+title: Language Detection Middleware
+description: Automatic language detection and URL routing based on user preferences
 ---
 
-## Overview
-This guide will walk you through adding i18n middleware routing and localized paths to your Next.js application using `gt-next`'s built-in middleware.
-
-### What is i18n middleware routing?
-
-Creating new routes for each language has the advantage of making your website more user friendly and improve SEO.
-i18n routing allows you to associate specific URLs with different locales.
-For example, you can have `/en/airplanes` for English, `/zh/airplanes` for Chinese, and so on.
-
-You can take this one step further with localized paths.
-These are an extension of i18n routing that allow you to specify an alias path for a locale.
-For example, you can specify `/en/airplanes` for English, `/zh/飞机` for Chinese, and so on.
-
----
-
-## Set up i18n routing
-
-We will take you through two easy steps to add i18n routing to your Next.js application:
-
-<Steps>
-    <Step>
-        Add a dynamic route to your app folder.
-    </Step>
-    <Step>
-        Create the middleware file.
-    </Step>
-</Steps>
+Middleware automatically detects user language preferences and redirects them to the appropriate localized version of your site. It uses browser settings, geolocation, and user preferences to serve the right language before any content loads.
 
+<Callout>
+  **File location:** Place `middleware.ts` in your project root, at the same level as your `app/` directory - not inside it.
+</Callout>
 
-### Step 1: Add a Dynamic Route [#dynamic-route]
+## Setup
 
-Insert a directory in your app folder called `[locale]` (e.g., `app/[locale]`).
-Include all of your pages and layouts under this directory.
+### Step 1: Create Dynamic Route
+Create a `[locale]` directory in your `app/` folder and move all pages inside it:
 
 <Files>
   <Folder name="my-app" defaultOpen={true}>
-    <File name="middleware.js" />
+    <File name="middleware.ts" />
     <Folder name="app" defaultOpen={true}>
       <Folder name="[locale]" defaultOpen={true}>
-        <File name="layout.js" />
-        <File name="page.js" />
-        <Folder name="some-page">
-          <File name="page.js" />
+        <File name="layout.tsx" />
+        <File name="page.tsx" />
+        <Folder name="about">
+          <File name="page.tsx" />
         </Folder>
       </Folder>
       <Folder name="api">
-        <File name="route.js" />
+        <File name="route.ts" />
       </Folder>
     </Folder>
-    <Folder name="public">
-      <Folder name="images">
-        <File name="logo.png" />
-      </Folder>
-    </Folder>
-    <Folder name="styles">
-      <File name="globals.css" />
-    </Folder>
     <File name="next.config.js" />
   </Folder>
 </Files>
 
-Ensure all special files inside `app/` are nested under `app/[locale]`.
+### Step 2: Add Middleware
+Create `middleware.ts` in your project root:
 
+```ts
+import { createNextMiddleware } from 'gt-next/middleware';
 
+export default createNextMiddleware();
 
-### Step 2: Add the middleware file [#middleware]
+export const config = {
+  // Match all paths except API routes, static files, and Next.js internals
+  matcher: ['/((?!api|static|.*\\..*|_next).*)']
+};
+```
 
-In Next.js, create a file called `middleware.js` (or `.ts` if you are using TypeScript) inside the root directory.
-If you are using the `src/` folder, place it in `src/middleware.js` (or `.ts`) instead.
-Add the [`createNextMiddleware()`](/docs/next/api/middleware/createNextMiddleware) function to the file.
+This enables automatic language detection and URL routing with locale prefixes like `/en/about`, `/es/about`.
 
-```js title="middleware.js" copy
-import { createNextMiddleware } from 'gt-next/middleware'
+## Language Detection
 
-export default createNextMiddleware();
+The middleware detects user language preferences in this order:
 
-export const config = {
-  matcher: [
-    /*
-      * Match all request paths except for the ones starting with:
-      * - api (API routes)
-      * - _next (internal files)
-      * - static files
-      */
-    "/((?!api|static|.*\\..*|_next).*)",
-  ],
-}
-```
+1. **URL locale** - `/es/about` → Spanish
+2. **User cookie** - Previous language selection  
+3. **Browser headers** - `Accept-Language` header
+4. **Default locale** - Configured fallback language
 
----
+The middleware automatically handles browser language detection and cookie persistence without additional configuration.
 
-## Set up localized paths
+## Localized Paths
 
-You can specify localized paths through the `pathConfig` option in the middleware file.
+Customize URL paths for different languages:
 
-```js title="middleware.js" copy
+```ts
 export default createNextMiddleware({
   pathConfig: {
-    // You can specify a shared path (optional)
-    // This will create "/en/about" and "/zh/about"
-    "/about": "/about",
-
-    // Specify localized paths
-    // This will create "/en/airplanes" and "/zh/飞机"
-    "/airplanes": {
-      "zh": "/飞机",
+    // English: /en/products, Chinese: /zh/产品
+    "/products": {
+      "zh": "/产品"
+    },
+    
+    // Dynamic routes: /en/product/123, /zh/产品/123
+    "/product/[id]": {
+      "zh": "/产品/[id]"
     }
-
-    // Add dynamic path parameters
-    // This will create "/en/airports/123" and "/zh/飞机机场/123"
-    "/airports/[id]": {
-      "zh": "/飞机机场/[id]",
-    }
-  },
+  }
 });
 ```
-In this example we create a default path for `/en/about` and localized paths for `/en/airplanes` and `/en/airports/[id]`.
-In Chinese, these will be aliased to `/zh/about`, `/zh/飞机` and `/zh/飞机机场/[id]` respectively.
 
-<Callout>
-  **Tip:**
-  Because the `/about` path remains the same for all locales, you don't need to include it in the `pathConfig` object.
-  Any paths that are not specified in the `pathConfig` object will use the same path for all locales following the locale prefix.
-</Callout>
+## URL Structure
 
+By default, your default locale will **not** be prefixed with a locale code:
 
----
+```
+/about     → /about        (default locale: English)
+/about     → /es/about     (Spanish)
+/about     → /fr/about     (French)
+```
+
+### Add Prefix to Default Locale
+To prefix all locales including the default:
 
-## Routing behavior
-
-### Default locale prefixing
-By default, your `defaultLocale` (a.k.a. your app's default language) will not be prefixed with a locale code in the url.
-For example, if your default locale is `en` and you have a page at `/about`, it will be accessible at `/about` in English.
-However, in Chinese, it will be accessible at `/zh/about` in Chinese.
-
-If you do not want this behavior, it can be disabled by setting the `prefixDefaultLocale` to `false` in the middleware configuration.
-
-### Locale detection and redirection
-The middleware will detect the user's locale based on (1) the url path locale, (2) the referrer locale, (3) the accepted languages from the browser, and (4) finally the `defaultLocale`.
-The user will then be redirected accordingly.
-
-
-<Steps>
-  <Step>
-    Locale is always first checked from the url path.
-    This means that if you visit `/zh/about`, your language will assume to be Chinese.
-  </Step>
-  <Step>
-    If the page you visit is not prefixed by a locale, then the middleware will check the user's previous locale.
-    For example, if you are on `/zh`, and you visit `/about`, your language will assume to be Chinese, and you will be redirected to `/zh/about`.
-  </Step>
-  <Step>
-    If neither of these are available, then locale detection will fallback to the user's browser language.
-    For instance, if someone's preferred language is Chinese, and they visit `/about` for the firs time, they will be redirected to `/zh/about`.
-  </Step>
-  <Step>
-    If none of these conditions are met, then the `defaultLocale` will be used as the fallback.
-  </Step>
-</Steps>
-
-If at any time a localized version of the page exists, they will be redirected to the localized url.
-For instance, `/zh/airplanes` will always redirect to `/zh/飞机`.
-
-#### Edge case: Localized paths without locale prefix
-
-If you navigate to a localized path without the locale prefix (e.g., `/飞机`), the middleware will prefix that path with whatever it thinks your current locale is.
-
-For example, visiting `/飞机` will only redirect to `/zh/飞机` if the middleware explicitly recognizes your locale as `zh`.
-This is great but it only works when the middleware thinks your locale is `zh`.
-
-Otherwise, your path will be prefixed with your current locale.
-For example, visiting `/飞机` will redirect to `/en/飞机` if the middleware thinks your locale is `en`.
-This will result in a 404.
-
-We recommend always using the path from your `defaultLocale` for any links in your project.
-This will always automatically redirect to the correct locale localized path.
-```jsx
-<Link href="/about">About</Link>
-<Link href="/planes">Planes</Link>
-<Link href="/airports/123">Airport 123</Link>
+```ts
+export default createNextMiddleware({
+  prefixDefaultLocale: true
+});
 ```
 
-If you want to explicitly link to a different locale, then you can do so by using the localized path.
-```jsx
-<Link href="/zh/about">About in Chinese</Link>
-<Link href="/zh/飞机">Planes in Chinese</Link>
-<Link href="/zh/飞机机场/123">Airport 123 in Chinese</Link>
+Result:
+```
+/about     → /en/about     (English, with prefix)
+/about     → /es/about     (Spanish, with prefix)
+/about     → /fr/about     (French, with prefix)
 ```
 
+## Common Issues
 
----
+### Missing Dynamic Route
+All pages must be inside `[locale]/`:
+
+```
+❌ Wrong:
+app/
+├── page.tsx
+└── about/page.tsx
+
+✅ Correct:
+app/
+└── [locale]/
+    ├── page.tsx
+    └── about/page.tsx
+```
+
+### Matcher Configuration
+Exclude API routes and static files:
 
+```ts
+export const config = {
+  matcher: ['/((?!api|static|.*\\..*|_next).*)']
+};
+```
 
-## Notes
- * i18n routing changes the URL structure of your application. Each language has its own URL.
- * The middleware file is required to handle the routing logic.
- * You can specify the supported locales in the middleware configuration and next config file.
+<Callout>
+  Test your middleware configuration thoroughly - incorrect matchers can cause infinite redirects or break static assets.
+</Callout>
 
 ## Next Steps
- * See the API docs for [`createNextMiddleware()`](/docs/next/api/middleware/createNextMiddleware).
\ No newline at end of file
+
+- [SSG Guide](/docs/next/guides/ssg) - Static generation with locale routing
+- [RTL Support](/docs/next/guides/rtl) - Right-to-left languages  
+- API References:
+  - [`createNextMiddleware()` Function](/docs/next/api/middleware/createNextMiddleware)
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/next/guides/migration.mdx b/apps/docs/content/docs/en/next/guides/migration.mdx
index 1a0e255e8..a667f710c 100644
--- a/apps/docs/content/docs/en/next/guides/migration.mdx
+++ b/apps/docs/content/docs/en/next/guides/migration.mdx
@@ -36,8 +36,7 @@ You'll never have to wait for translations again.
 <Tabs items={['npm', 'yarn', 'bun', 'pnpm']}>
   <Tab value="npm">
   ```bash 
-  npm i gt-next
-  npm i --save-dev gtx-cli
+  npm i gt-next gtx-cli
   ``` 
   </Tab>
   <Tab value="yarn">
@@ -227,6 +226,4 @@ If you are using AI to help you migrate your project, we have a `LLMs.txt` and `
 - [LLMs.txt](/llms.txt)
 - [LLMs-full.txt](/llms-full.txt)
 
-These files contain the full content of these docs, so your AI tool will have access to all the information it needs to help you migrate your project.
-
-
+These files contain the full content of these docs, so your AI tool will have access to all the information it needs to help you migrate your project.
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/next/guides/rtl.mdx b/apps/docs/content/docs/en/next/guides/rtl.mdx
index 972ce6171..cce403598 100644
--- a/apps/docs/content/docs/en/next/guides/rtl.mdx
+++ b/apps/docs/content/docs/en/next/guides/rtl.mdx
@@ -1,32 +1,25 @@
 ---
 title: Right-to-Left Support
-description: A step by step guide on adding Right-to-Left (RTL) support to your application
+description: Configure your Next.js app for Arabic, Hebrew, and other RTL languages
 ---
 
-## Overview
+Right-to-left (RTL) language support handles text direction and layout mirroring for languages like Arabic, Hebrew, Persian, and Urdu. GT provides automatic direction detection through the `useLocaleDirection()` hook.
 
-While most languages are written left-to-right (LTR), some languages are written right-to-left (RTL).
-These languages include Arabic, Hebrew, Persian, and Urdu which have a combined total of over 500 million speakers worldwide.
+<Callout>
+  **RTL languages:** Over 500 million people speak RTL languages including Arabic, Hebrew, Persian, and Urdu.
+</Callout>
 
-Look at the General Translation landing page in [English](https://generaltranslation.com/en-US/welcome)
-and [Arabic](https://generaltranslation.com/ar/welcome) to illustrate the difference between ltr and rtl rendering.
+## Quick Setup
 
-## Guide
+Use GT's built-in hooks to automatically detect and set text direction:
 
-To add RTL support to your application, all we need to do to is determine the direction of the language and set the direction of
-the text on the screen accordingly.
-
-You can use the `useLocaleDirection()` hook to determine if a language goes `"rtl"` or `"ltr"`.
-
-Use the `useLocale()` function to get the locale in the root layout, then add the `lang` and `dir` props to the `<html>` tag:
-
-```javascript title="my-app/app/layout.tsx" copy
-import { useLocale, useLocaleDirection, GTProvider } from 'gt-next'
+```tsx
+// app/[locale]/layout.tsx
+import { useLocale, useLocaleDirection, GTProvider } from 'gt-next';
 
 export default function RootLayout({ children }) {
-        
   const locale = useLocale(); // e.g. "ar" for Arabic
-  const dir = useLocaleDirection(); // e.g. "rtl" for "right-to-left"
+  const dir = useLocaleDirection(); // e.g. "rtl" for right-to-left
 
   return (
     <html lang={locale} dir={dir}>
@@ -36,6 +29,11 @@ export default function RootLayout({ children }) {
         </GTProvider>
       </body>
     </html>
-  )
+  );
 }
-```
\ No newline at end of file
+```
+
+That's it! GT automatically detects RTL languages and returns the correct direction.
+
+Compare with the [General Translation website](https://generaltranslation.com) in [English](https://generaltranslation.com/en-US/home) vs [Arabic](https://generaltranslation.com/ar/home) to see RTL in action.
+
diff --git a/apps/docs/content/docs/en/next/guides/shared-strings.mdx b/apps/docs/content/docs/en/next/guides/shared-strings.mdx
index 5cc089149..685f7825d 100644
--- a/apps/docs/content/docs/en/next/guides/shared-strings.mdx
+++ b/apps/docs/content/docs/en/next/guides/shared-strings.mdx
@@ -1,460 +1,435 @@
 ---
-title: Translating Shared Strings
-description: How to internationalize shared strings
+title: Shared Strings
+description: How to internationalize strings used across multiple components and files
 ---
 
-## Overview
+Shared strings are text values used in multiple places throughout your application - like navigation labels, form messages, or configuration data. Instead of duplicating translation logic everywhere, use [`msg()`](/docs/next/api/strings/msg) to mark strings for translation and [`useMessages()`](/docs/next/api/dictionary/useMessages) to decode them.
 
-Shared strings are strings or constants that are used in multiple places in your app.
+## The Problem with Shared Content
 
-For example, you may have a string that is used in multiple components, or a constant that is used in multiple files.
+Consider this navigation configuration used across your app:
 
-In traditional i18n libraries, you would need to create a dictionary for each shared string.
-
-This guide will walk you through how to easily internationalize shared strings in your Next.js app using the [`msg()`](/docs/next/api/strings/msg) function & [`useMessages()`](/docs/next/api/dictionary/useMessages) hook.
-
-We will cover the following:
-<Steps>
-  <Step>
-    When to use the `msg()` function
-  </Step>
-  <Step>
-    How to use the `msg()` function and `useMessages()` hook
-  </Step>
-  <Step>
-    Using variables
-  </Step>
-  <Step>
-    Examples
-  </Step>
-  <Step>
-    Common pitfalls
-  </Step>
-</Steps>
-
---- 
-
-## When to use the `msg()` function
-
-The `msg()` function is a simple function that is used to mark strings for translation.
-
-Let's look at an example of a shared object containing strings:
-
-```tsx title="src/navData.ts"
-export const navData = {
-  home: {
+```tsx
+// navData.ts
+export const navData = [
+  {
     label: 'Home',
     description: 'The home page',
-    icon: 'home',
-    href: '/',
+    href: '/'
   },
-  about: {
-    label: 'About',
+  {
+    label: 'About', 
     description: 'Information about the company',
-    icon: 'info',
-    href: '/about',
-  },
-}
-```
-
-Normally, to internationalize this object, you would need to either create a dictionary entry for each string, or refactor your object into a function that returns the data with translations.
-
-For example, you might have:
-```tsx title="src/navData.ts"
-export const getNavData = (t: (content: string) => string) => ({
-  home: {
-    label: t('Home'),
-    description: t('The home page'),
-    icon: 'home',
-    href: '/',
-  },
-  about: {
-    label: t('About'),
-    description: t('Information about the company'),
-    icon: 'info',
-    href: '/about',
-  },
-})
-```
-Everywhere else in your app where `navData` was imported, you would need to call `getNavData(t)` instead.
-
-```tsx title="src/app/page.tsx"
-import { getNavData } from '@/navData';
-
-export default function Home() {
-  const t = useGT();
-  const navData = getNavData(t);
-  return <div>{navData.home.label}</div>;
-}
+    href: '/about'
+  }
+];
 ```
 
-This can lead to a lot of work. The solution is to use the `msg()` function.
+To internationalize this, you'd typically need to:
+1. Convert it to a function that accepts a translation function
+2. Update every usage to call the function with `t`
+3. Manage the complexity across your codebase
 
----
+This creates maintenance overhead and makes your code harder to read. The [`msg()`](/docs/next/api/strings/msg) function solves this by letting you mark strings for translation in-place, then decode them when needed.
 
-## How to use the `msg()` function
+## Quick Start
 
-To use the `msg()` function, pass the string directly to the function.
-The function returns a special, encoded string that can be used for translations.
+Use [`msg()`](/docs/next/api/strings/msg) to mark strings and [`useMessages()`](/docs/next/api/dictionary/useMessages) to decode them:
 
-```tsx title="src/navData.ts"
+```tsx
+// navData.ts - Mark strings for translation
 import { msg } from 'gt-next';
 
 export const navData = [
   {
-    label: msg('Home'), // Output has type `string`
-    description: msg('The home page'),
-    icon: 'home',
-    href: '/',
+    label: msg('Home'),
+    description: msg('The home page'), 
+    href: '/'
   },
   {
     label: msg('About'),
     description: msg('Information about the company'),
-    icon: 'info',
-    href: '/about',
-  },
-]
+    href: '/about'
+  }
+];
 ```
 
-Then, simply pass the encoded string to the `useMessages()` hook.
-
-```tsx title="src/app/page.tsx"
+```tsx
+// Component usage - Decode marked strings
 import { useMessages } from 'gt-next';
-import { navData } from '@/navData';
+import { navData } from './navData';
 
-export default function Home() {
+function Navigation() {
   const m = useMessages();
+  
   return (
-    <div>
+    <nav>
       {navData.map((item) => (
-        <div key={item.label}>{m(item.label)}</div>
+        <a key={item.href} href={item.href} title={m(item.description)}>
+          {m(item.label)}
+        </a>
       ))}
-    </div>
+    </nav>
   );
 }
 ```
 
-If you are in an async component, use the `getMessages()` function instead of the `useMessages()` hook.
+## How Shared Strings Work
+
+The shared string system works in two phases:
+
+1. **Mark Phase**: [`msg()`](/docs/next/api/strings/msg) encodes strings with translation metadata
+2. **Decode Phase**: [`useMessages()`](/docs/next/api/dictionary/useMessages) or [`getMessages()`](/docs/next/api/dictionary/getMessages) decode and translate the strings
+
+```tsx
+// msg() encodes the string with metadata
+const encoded = msg('Hello, world!');
+console.log(encoded); // "Hello, world!:eyIkX2hhc2giOiJkMjA3MDliZGExNjNlZmM2In0="
+
+// useMessages() decodes and translates
+const m = useMessages();
+const translated = m(encoded); // "Hello, world!" in user's language
+```
+
+<Callout type="warn">
+  Encoded strings from [`msg()`](/docs/next/api/strings/msg) cannot be used directly - they must be decoded with [`useMessages()`](/docs/next/api/dictionary/useMessages) or [`getMessages()`](/docs/next/api/dictionary/getMessages).
+</Callout>
+
+## Client vs Server Usage
+
+### Client Components
+Use [`useMessages()`](/docs/next/api/dictionary/useMessages) hook:
+
+```tsx
+import { useMessages } from 'gt-next';
+
+const encodedString = msg('Hello, world!');
+
+function MyComponent() {
+  const m = useMessages();
+  return <div>{m(encodedString)}</div>;
+}
+```
+
+### Server Components  
+Use [`getMessages()`](/docs/next/api/dictionary/getMessages) function:
 
-```tsx title="src/app/page.tsx"
+```tsx
 import { getMessages } from 'gt-next/server';
 
-export default async function Home() {
+const encodedString = msg('Hello, world!');
+
+async function MyServerComponent() {
   const m = await getMessages();
-  return (
-    <div>
-      {navData.map((item) => (
-        <div key={item.label}>{m(item.label)}</div>
-      ))}
-    </div>
-  );
+  return <div>{m(encodedString)}</div>;
 }
 ```
 
-<Callout type='warn'>
-  Beware! The string returned by the `msg()` function is encoded and will be different from the original input string.
-  If want to get back the original string, you need to decode it with [`decodeMsg()`](/docs/next/api/strings/msg#decodemsg)
-</Callout>
+## Getting Original Strings with `decodeMsg()`
 
----
-## Using variables
+Sometimes you need to access the original string without translation, such as for logging, debugging, or comparisons. Use [`decodeMsg()`](/docs/next/api/strings/msg#decodemsg) to extract the original text:
 
-If your string is a template string and contains variables, you can pass the variables to the `msg()` function.
+```tsx
+import { decodeMsg } from 'gt-next';
 
-Simply change the `${}` notation in the template string to `{variable}`, and pass an object as the second argument to `msg()` with the variable name as the key.
+const encoded = msg('Hello, world!');
+const original = decodeMsg(encoded); // "Hello, world!" (original)
+const translated = m(encoded); // "Hello, world!" (in user's language)
 
-```tsx title="src/navData.ts"
-const items = 100;
-export const pricing = [
-  {
-    name: 'Basic',
-    price: 100,
-    description: `The basic plan includes ${items} items`
-  },
-]
+// Useful for logging or debugging
+console.log('Original string:', decodeMsg(encoded));
+console.log('Translated string:', m(encoded));
 ```
 
-Should be turned into:
+### Use Cases for `decodeMsg()`
 
-```tsx title="src/navData.ts"
-import { msg } from 'gt-next';
+- **Development & Debugging**: Log original strings for troubleshooting
+- **Fallback Handling**: Use original text when translations fail
+- **String Comparisons**: Compare against known original values
+- **Analytics**: Track original string usage
+
+```tsx
+// Example: Fallback handling
+function getDisplayText(encodedStr) {
+  const m = useMessages();
+  try {
+    return m(encodedStr);
+  } catch (error) {
+    console.warn('Translation failed, using original:', decodeMsg(encodedStr));
+    return decodeMsg(encodedStr);
+  }
+}
+```
 
+## Using Variables
+
+For strings with dynamic content, use placeholders and pass variables:
+
+```tsx
+// Mark string with variables
 const items = 100;
 export const pricing = [
   {
     name: 'Basic',
     price: 100,
     description: msg('The basic plan includes {items} items', { items })
-  },
-]
+  }
+];
 ```
 
-The `{items}` placeholder will be replaced with the value of the `items` variable.
-
-This allows you to display dynamic values in your translations.
-
-For more information on the API, see the [API reference](/docs/next/api/strings/msg).
+```tsx
+// Use in component
+function PricingCard() {
+  const m = useMessages();
+  
+  return (
+    <div>
+      <h3>{pricing[0].name}</h3>
+      <p>{m(pricing[0].description)}</p>
+    </div>
+  );
+}
+```
 
-`gt-next` supports ICU message format, which allows you to also format your variables.
+### ICU Message Format
+For advanced formatting, use ICU syntax:
 
-```jsx copy
-const price = 100;
-msg('There are {count, plural, =0 {no items} =1 {one item} other {{count} items}} in the cart', { count: 10 });
+```tsx
+const count = 10;
+const message = msg('There are {count, plural, =0 {no items} =1 {one item} other {{count} items}} in the cart', { count });
 ```
 
 <Callout>
-  ICU message format is a powerful way to format your variables.
-  For more information, see the [ICU message format documentation](https://unicode-org.github.io/icu/userguide/format_parse/messages/).
+  Learn more about ICU Message Format in the [Unicode documentation](https://unicode-org.github.io/icu/userguide/format_parse/messages/).
 </Callout>
 
-
----
-
 ## Examples
 
-1. Translating a shared global object
-
-<Tabs items={['Result', 'Original']}>
-  <Tab value="Result">
-```jsx copy title="src/llms.ts"
+### Navigation Configuration
+```tsx
+// config/navigation.ts
 import { msg } from 'gt-next';
 
-export const llmData = [
+export const mainNav = [
   {
-    name: 'GPT-4.1',
-    id: 'gpt-4.1',
-    description: msg('GPT-4.1 is a large language model developed by OpenAI'),
+    label: msg('Home'),
+    href: '/',
+    icon: 'home'
   },
   {
-    name: 'Claude 3.7 Sonnet',
-    id: 'claude-3-7-sonnet',
-    description: msg('Claude 3.7 Sonnet is a large language model developed by Anthropic'),
+    label: msg('Products'),
+    href: '/products', 
+    icon: 'package'
   },
+  {
+    label: msg('About Us'),
+    href: '/about',
+    icon: 'info'
+  }
 ];
-```
-
-```jsx copy title="src/app/page.tsx"
-import { llmData } from '@/llms';
-import { useMessages } from 'gt-next';
-
-export default function MyComponent() {
-  const m = useMessages();
-  return (
-    <div>
-      {llmData.map((llm) => (
-        <div key={llm.id}>
-          <h1>{llm.name}</h1>
-          <p>{m(llm.description)}</p>
-        </div>
-      ))}
-    </div>
-  )
-}
-```
-  </Tab>
 
-<Tab value="Original">
-```jsx copy title="src/llms.ts"
-export const llms = [
+export const footerLinks = [
   {
-    name: 'GPT-4.1',
-    id: 'gpt-4.1',
-    description: 'GPT-4.1 is a large language model developed by OpenAI',
+    title: msg('Company'),
+    links: [
+      { label: msg('About'), href: '/about' },
+      { label: msg('Careers'), href: '/careers' },
+      { label: msg('Contact'), href: '/contact' }
+    ]
   },
   {
-    name: 'Claude 3.7 Sonnet',
-    id: 'claude-3-7-sonnet',
-    description: 'Claude 3.7 Sonnet is a large language model developed by Anthropic',
-  },
-]
+    title: msg('Support'), 
+    links: [
+      { label: msg('Help Center'), href: '/help' },
+      { label: msg('Documentation'), href: '/docs' },
+      { label: msg('API Reference'), href: '/api' }
+    ]
+  }
+];
 ```
 
-```jsx copy title="src/app/page.tsx"
-import { llms } from '@/llms';
+```tsx
+// components/Navigation.tsx
+import { useMessages } from 'gt-next';
+import { mainNav } from '../config/navigation';
 
-export default function MyComponent() {
+function Navigation() {
+  const m = useMessages();
+  
   return (
-    <div>
-      {llms.map((llm) => (
-        <div key={llm.id}>
-          <h1>{llm.name}</h1>
-          <p>{llm.description}</p>
-        </div>
+    <nav>
+      {mainNav.map((item) => (
+        <a key={item.href} href={item.href}>
+          <Icon name={item.icon} />
+          {m(item.label)}
+        </a>
       ))}
-    </div>
-  )
+    </nav>
+  );
 }
 ```
-</Tab>
-</Tabs>
 
-2. Translating a function's return value
-
-<Tabs items={['Result', 'Original']}>
-  <Tab value="Result">
-```jsx copy title="src/llms.ts"
+### Form Configuration
+```tsx
+// config/forms.ts
 import { msg } from 'gt-next';
 
-function mockData() {
-  return [
-    {
-      name: 'GPT-4.1',
-      id: 'gpt-4.1',
-      company: 'OpenAI',
-    },
-    {
-      name: 'Claude 3.7 Sonnet',
-      id: 'claude-3-7-sonnet',
-      company: 'Anthropic',
-    },
-  ];
-}
-
-export function getData() {
-  const data = mockData();
-  const modifiedData = data.map((item) => ({
-    ...item,
-    description: msg('{name} is a large language model developed by {company}', {
-      name: item.name,
-      company: item.company,
-    }),
-  }));
-  return modifiedData;
-}
+export const formMessages = {
+  placeholders: {
+    email: msg('Enter your email address'),
+    password: msg('Enter your password'),
+    message: msg('Type your message here...')
+  },
+  actions: {
+    send: msg('Send Message'),
+    save: msg('Save Changes'),
+    cancel: msg('Cancel')
+  },
+  validation: {
+    required: msg('This field is required'),
+    email: msg('Please enter a valid email address'),
+    minLength: msg('Must be at least {min} characters', { min: 8 }),
+    maxLength: msg('Cannot exceed {max} characters', { max: 100 })
+  },
+  success: {
+    saved: msg('Changes saved successfully'),
+    sent: msg('Message sent successfully'),
+    updated: msg('Profile updated')
+  },
+  errors: {
+    network: msg('Network error - please try again'),
+    server: msg('Server error - please contact support'),
+    timeout: msg('Request timed out - please try again')
+  }
+};
 ```
 
-```jsx copy title="src/app/page.tsx"
-import { getData } from '@/llms';
+```tsx
+// components/ContactForm.tsx
 import { useMessages } from 'gt-next';
+import { formMessages } from '../config/forms';
 
-export default function MyComponent() {
+function ContactForm() {
   const m = useMessages();
-  const data = getData();
+  const [errors, setErrors] = useState({});
+  
   return (
-    <div>
-      {data.map((item) => (
-        <div key={item.id}>
-          <h1>{item.name}</h1>
-          <p>{m(item.description)}</p>
-        </div>
-      ))}
-    </div>
-  )
+    <form>
+      <input 
+        type="email"
+        placeholder={m(formMessages.placeholders.email)}
+        required
+      />
+      {errors.email && <span>{m(formMessages.validation.email)}</span>}
+      
+      <button type="submit">
+        {m(formMessages.actions.send)}
+      </button>
+    </form>
+  );
 }
 ```
-  </Tab>
 
-<Tab value="Original">
-```jsx copy title="src/llms.ts"
+### Dynamic Content Generation
+```tsx
+// utils/productData.ts
 import { msg } from 'gt-next';
 
-function mockData() {
+function mockProducts() {
   return [
-    {
-      name: 'GPT-4.1',
-      id: 'gpt-4.1',
-      company: 'OpenAI',
-    },
-    {
-      name: 'Claude 3.7 Sonnet',
-      id: 'claude-3-7-sonnet',
-      company: 'Anthropic',
-    },
+    { name: 'iPhone 15', company: 'Apple', category: 'Electronics' },
+    { name: 'Galaxy S24', company: 'Samsung', category: 'Electronics' }
   ];
 }
 
-export function getData() {
-  const data = mockData();
-  const modifiedData = data.map((item) => ({
-    ...item,
-    description: `${item.name} is a large language model developed by ${item.company}`,
+export function getProductData() {
+  const products = mockProducts();
+  
+  return products.map(product => ({
+    ...product,
+    description: msg('{name} is a {category} product by {company}', {
+      name: product.name,
+      category: product.category,
+      company: product.company
+    })
   }));
-  return modifiedData;
 }
 ```
 
-```jsx copy title="src/app/page.tsx"
-import { getData } from '@/llms';
+```tsx
+// components/ProductList.tsx
+import { useMessages } from 'gt-next';
+import { getProductData } from '../utils/productData';
 
-export default function MyComponent() {
-  const data = getData();
+function ProductList() {
+  const m = useMessages();
+  const products = getProductData();
+  
   return (
     <div>
-      {data.map((item) => (
-        <div key={item.id}>
-          <h1>{item.name}</h1>
-          <p>{item.description}</p>
+      {products.map(product => (
+        <div key={product.name}>
+          <h3>{product.name}</h3>
+          <p>{m(product.description)}</p>
         </div>
       ))}
     </div>
-  )
+  );
 }
 ```
-</Tab>
-</Tabs>
-
----
-
-## Common Pitfalls
 
-### Forgetting to call `useMessages()`
+## Common Issues
 
-`msg()` encodes the input string, so you cannot use it directly in JSX or elsewhere. 
+### Using Encoded Strings Directly
+Never use the output of [`msg()`](/docs/next/api/strings/msg) directly:
 
-If you attempt to use the encoded string directly, you will get a weird string that looks something like this:
+```tsx
+// ❌ Wrong - encoded string used directly
+const encoded = msg('Hello, world!');
+return <div>{encoded}</div>; // Shows encoded string, not translation
 
-```jsx
-const encodedString = msg('Hello, world!');
-console.log(encodedString); // "Hello, world!:eyIkX2hhc2giOiJkMjA3MDliZGExNjNlZmM2In0="
+// ✅ Correct - decode the string first  
+const encoded = msg('Hello, world!');
+const m = useMessages();
+return <div>{m(encoded)}</div>; // Shows proper translation
 ```
 
-To fix this, you need to use the `useMessages()` hook to get the translated string.
+### Dynamic Content in msg()
+Strings must be known at build time:
 
-```jsx
-import { useMessages } from 'gt-next';
+```tsx
+// ❌ Wrong - dynamic template literal
+const name = 'John';
+const message = msg(`Hello, ${name}`); // Build time error
 
-const encodedString = msg('Hello, world!');
-
-export default function MyComponent() {
-  const m = useMessages();
-  return <div>{m(encodedString)}</div>; // 'Hello, world!' in the current language
-}
-```
-
-Alternatively, if you want to recover the original string, you can use the `decodeMsg()` function.
-
-```jsx
-import { decodeMsg } from 'gt-next';
-
-const encodedString = msg('Hello, world!');
-const decodedString = decodeMsg(encodedString);
-console.log(decodedString); // "Hello, world!"
+// ✅ Correct - use variables  
+const name = 'John';
+const message = msg('Hello, {name}', { name });
 ```
 
-### Wrapping dynamic content in `msg()`
+### Forgetting to Decode
+Every [`msg()`](/docs/next/api/strings/msg) string needs to be decoded:
 
-All strings must be known at build time. This means that you cannot wrap dynamic content in `msg()`.
+```tsx
+// ❌ Missing decoding
+const config = {
+  title: msg('Dashboard'),
+  subtitle: msg('Welcome back')
+};
 
-For example, this is invalid:
+// Later in component - forgot to decode
+return <h1>{config.title}</h1>; // Shows encoded string
 
-```jsx
-const dynamicContent = msg(`Hello, ${name}`);
+// ✅ Correct - decode when using
+const m = useMessages();
+return <h1>{m(config.title)}</h1>; // Shows translated title
 ```
 
-To fix this, provide the dynamic content as a variable, and then pass it to `msg()`.
-
-```jsx
-const dynamicContent = msg('Hello, {name}', { name });
-```
-
-<Callout type="warn">
-  The CLI tool will warn you if you try to wrap dynamic content with `msg()`.
-</Callout>
-
-
----
-
 ## Next Steps
- * See the [API reference for `msg()`](/docs/next/api/strings/msg).
- * See the [API reference for `useMessages()`](/docs/next/api/dictionary/useMessages).
- * Learn more about the [`<T>` component](/docs/next/guides/jsx).
\ No newline at end of file
+
+- [Dictionaries Guide](/docs/next/guides/dictionaries) - Organize translations with structured data
+- [Languages Guide](/docs/next/guides/languages) - Configure supported languages
+- API References:
+  - [`msg()` Function](/docs/next/api/strings/msg)
+  - [`useMessages()` Hook](/docs/next/api/dictionary/useMessages)
+  - [`getMessages()` Function](/docs/next/api/dictionary/getMessages)
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/next/guides/ssg.mdx b/apps/docs/content/docs/en/next/guides/ssg.mdx
index c25387f00..e9d4168f8 100644
--- a/apps/docs/content/docs/en/next/guides/ssg.mdx
+++ b/apps/docs/content/docs/en/next/guides/ssg.mdx
@@ -1,146 +1,109 @@
 ---
 title: Static Site Generation
-description: How to support static site generation for your i18n app
+description: Pre-render internationalized pages at build time for optimal performance
 ---
 
-## Overview
+Static Site Generation pre-renders pages at build time, creating static HTML files for each locale. This provides excellent performance and SEO benefits while ensuring all translation content is available immediately when users visit your site.
 
-This guide will show you how to setup your i18n app to support static site generation.
+<Callout>
+  **Requirements:** SSG requires [middleware routing](/docs/next/guides/middleware) and [local translations](/docs/next/guides/local-tx) to work properly with internationalization.
+</Callout>
 
----
+## App Router
 
-### What is static site generation?
-
-[Static site generation](https://nextjs.org/docs/pages/building-your-application/rendering/static-site-generation) (SSG) is a feature of Next.js that allows you to generate static pages at build time.
-This is useful for performance and SEO. 
-
-## SSG for the `app` router
-
-### Requirements
-
-There are a few requirements to enable static site generation for your i18n app.
-Depending on whether you are using the `app` or `pages` directory, the requirements are slightly different.
-
-1. Your app must be using the Next.js app router.
-2. Your app must support i18n routing (see [i18n routing](/docs/next/guides/middleware))
-3. Your app must be using local translations (see [local translations](/docs/next/guides/local-tx))
-
-### Steps
-
-<Steps>
-  <Step>
-    **Step 1:**
-    First, make sure your app has a `<GTProvider>` component at the root layout.
-
-    ```tsx title="app/[locale]/layout.tsx" copy
-    import { GTProvider } from 'gt-next';
-    ```
-    Since the app is using i18n routing, the provider should be placed in the `[locale]/layout.tsx` file.
-    
-    <Accordions>
-      <Accordion title="Why is this required?">
-        SSG requires all parameters to be known at build time. This includes the locale for every statically generated page.
-        Since the `<GTProvider>` component is responsible for providing the translation context to your app, it must know the locale.
-
-        For the same reason, your app must be using i18n routing (since each route must correspond to a specific locale, for a specific page).
-      </Accordion>
-    </Accordions>
-  </Step>
-  <Step>
-    **Step 2:**
-    Next, make sure your app is using the `loadTranslations` function to load translations.
-    Additionally, pass in the locale as a parameter to the `<GTProvider>`. You can obtain the locale from the `params` object.
-
-    ```tsx title="app/[locale]/layout.tsx"
-    import { loadTranslations } from '@/i18n/loadTranslations';
-    import { GTProvider } from 'gt-next/client';
-
-    export default async function RootLayout({
-      children,
-      params,
-    }: {
-      children: React.ReactNode;
-      params: Promise<{ locale: string }>;
-    }) {
-      const { locale } = await params;
-      return (
-        <GTProvider loadTranslations={loadTranslations} locale={locale}>
-          {children}
-        </GTProvider>
-      )
-    }
-    ```
-  </Step>
-  <Step>
-    **Step 3:**
-    Then, make sure all of your hooks and components are importing from `gt-next/client`.
-
-    ```tsx
-    import { useGT } from 'gt-next/client';
-    import { T } from 'gt-next/client';
-    ```
-    <Callout type="info">
-      This is important because hooks and components imported from `gt-next/client` never read headers, which don't exist at build time for statically generated pages.
-    </Callout>
-  </Step>
-</Steps>
-
-Make sure you have configured your Next.js app to use the [`getStaticParams` function](https://nextjs.org/docs/app/api-reference/functions/generate-static-params) correctly!
-
-That's it! Your app should now support static site generation for multiple languages!
-
-<Accordions>
-  <Accordion title="My pages aren't being statically generated!">
-    If you've followed the steps above and your pages are still not being statically generated, double check that all of your hooks and components are importing from `gt-next`.
-
-    As a rule of thumb, anything that reads headers or cookies will prevent SSG. This means you can't use any of the following:
-    - `await getGT()`
-    - `await getLocale()`
-    - `await getTranslations()`
-    - `import { T } from 'gt-next'`
-    
-  </Accordion>
-</Accordions>
-
-### SSG with custom getLocale [#ssg-custom-get-locale]
-
-SSG can disrupt locale resolution.
-Because of this, you will have to define your own `getLocale()` function that accesses the locale through the url path.
-Depending on your version of Next.js, your solution may be different.
+### Setup Requirements
 
-#### Next.js 15.5+
+To enable SSG with GT, you need:
+
+1. **App Router with middleware routing** - see [middleware guide](/docs/next/guides/middleware)
+2. **Local translations** - see [local translations guide](/docs/next/guides/local-tx) 
+3. **Client-side imports** - use `gt-next/client` instead of `gt-next`
+
+### Step 1: GTProvider Configuration
+
+Place `GTProvider` in your `[locale]` layout with the `loadTranslations` function:
+
+```tsx
+// app/[locale]/layout.tsx
+import { GTProvider } from 'gt-next/client';
+import { loadTranslations } from '@/loadTranslations';
+
+export default async function RootLayout({ children, params }) {
+  const { locale } = await params;
+  
+  return (
+    <GTProvider loadTranslations={loadTranslations} locale={locale}>
+      {children}
+    </GTProvider>
+  );
+}
+```
+
+### Step 2: Use Client Imports
+
+Import all GT components and hooks from `gt-next/client`:
+
+```tsx
+// ✅ Use client imports for SSG
+import { useGT, T } from 'gt-next/client';
 
-Create a new file in the root of your project called `getLocale.ts`.
+// ❌ These prevent SSG
+import { getGT } from 'gt-next/server';
+import { T } from 'gt-next';
+```
+
+### Step 3: Configure generateStaticParams
+
+Make sure you have [`generateStaticParams`](https://nextjs.org/docs/app/api-reference/functions/generate-static-params) configured for your locales.
 
-```ts title="getLocale.ts"
+### Custom getLocale
+
+For SSG, create a custom `getLocale()` function that works with static generation:
+
+#### Next.js 15.5+
+```ts
+// getLocale.ts
 import { locale } from "next/root-params";
 export default async function getLocale() {
-    return await locale();
+  return await locale();
 }
 ```
 
 #### Next.js 15.1-15.4
-
-Create a new file in the root of your project called `getLocale.ts`.
-
-```ts title="getLocale.ts"
+```ts
+// getLocale.ts  
 import { unstable_rootParams } from "next/server";
 export default async function getLocale() {
-  const result = (await unstable_rootParams())?.locale;
-  return result;
+  return (await unstable_rootParams())?.locale;
 }
 ```
 
+#### Earlier Versions
+Unfortunately, for earlier versions there is no way to access the URL path parameters with SSG. You will have to upgrade to Next.js 15.1 or later.
+
+### Common Issues
 
-#### Earlier versions
+#### Pages Not Generating Statically
 
-Unfortunately, for earlier versions there is no way to access the url path parameters with SSG.
-You will have to upgrade to Next.js 15.1 or later.
+If your pages aren't being statically generated, check that all GT components and hooks import from `gt-next/client`:
+
+```tsx
+// ❌ These prevent SSG
+import { getGT } from 'gt-next/server';
+import { getLocale } from 'gt-next/server';
+import { getTranslations } from 'gt-next/server';
+import { T } from 'gt-next';
+
+// ✅ These work with SSG
+import { useGT, T } from 'gt-next/client';
+```
 
+Anything that reads headers or cookies will prevent static generation.
 
-## SSG for the `pages` router
+## Next Steps
 
-🚧 This section is currently under construction. 🚧
+- [Local Translation Storage](/docs/next/guides/local-tx) - Required for SSG setup
+- [Middleware Guide](/docs/next/guides/middleware) - Required for locale routing
 
 
 
diff --git a/apps/docs/content/docs/en/next/guides/strings.mdx b/apps/docs/content/docs/en/next/guides/strings.mdx
index f6fabeb37..01e11182b 100644
--- a/apps/docs/content/docs/en/next/guides/strings.mdx
+++ b/apps/docs/content/docs/en/next/guides/strings.mdx
@@ -1,435 +1,344 @@
 ---
-title: Translating Strings
-description: How to internationalize strings
+title: Strings
+description: How to internationalize plain text strings using useGT and getGT
 ---
 
-## Overview
-
-This guide will walk you through how to internationalize strings in your Next.js app using the [`useGT()`](/docs/next/api/strings/useGT) hook & [`getGT()`](/docs/next/api/strings/getGT) function.
-
-We will cover the following:
-<Steps>
-  <Step>
-    When to use the `useGT()` hook
-  </Step>
-  <Step>
-    How to use the `useGT()` hook
-  </Step>
-  <Step>
-    Using variables
-  </Step>
-  <Step>
-    Examples
-  </Step>
-  <Step>
-    Common pitfalls
-  </Step>
-</Steps>
+String translation provides direct access to text translations without JSX, perfect for attributes, object properties, and plain text values. Use [`useGT()`](/docs/next/api/strings/useGT) in synchronous components and [`getGT()`](/docs/next/api/strings/getGT) in asynchronous components.
 
-<Callout>
-  In this guide, when we refer to the `useGT()` hook, we are also referring to the `getGT()` function.
-  
-  **The only difference between the two is when to use them.**
-  
-  The `getGT()` function is an asynchronous function that returns a promised function, 
-  while the `useGT()` hook returns the function directly.
-  
-  Use the `getGT()` function in synchronous components, 
-  and the `useGT()` hook in async components.
-
-<Tabs items={['Synchronous Component', 'Async Component']}>
-  <Tab value="Synchronous Component">
-  ```tsx title="src/app/page.tsx"
-  import { useGT } from 'gt-next';
-  export function MyComponent() {
-    const translate = useGT();
-    const translatedString = translate('Hello, world!');
-    return <div>{translatedString}</div>;
-  }
-  ```
-  </Tab>
-  <Tab value="Async Component">
-  ```tsx title="src/app/page.tsx"
-  import { getGT } from 'gt-next/server';
-  export async function MyComponent() {
-    const translate = await getGT();
-    const translatedString = translate('Hello, world!');
-    return <div>{translatedString}</div>;
-  }
-  ```
-  </Tab>
-</Tabs>
-</Callout>
-
---- 
-
-## When to use the `useGT()` hook
+## Synchronous vs Asynchronous Usage
 
-The `useGT()` hook is a React hook that can be used to translate strings.
+- **Synchronous Components**: [`useGT()`](/docs/next/api/strings/useGT) hook for React components
+- **Asynchronous Components**: [`getGT()`](/docs/next/api/strings/getGT) async function for async components
 
-In most cases, you can use the [`<T>` component](/docs/next/guides/jsx).
-However, in cases where JSX is not appropriate, the `useGT()` hook can be used. 
+## Quick Start
 
-Some cases where the `useGT()` hook could be more appropriate are:
-- In properties that expect strictly strings, such as `placeholder` or `title` attributes.
-- When the string is part of a larger object, for example:
+### Synchronous Components
+```jsx
+import { useGT } from 'gt-next';
 
-```jsx copy
-const user = {
-  title: 'Mr.',
-  name: 'John',
-  description: 'John is a software engineer at General Translation',
+function MyComponent() {
+  const t = useGT();
+  return (
+    <input 
+      placeholder={t('Enter your email')}
+      title={t('Email address field')}
+    />
+  );
 }
 ```
-Here, only the `description` property should be translated.
-
-<Callout>
-  Wherever possible, you should use the [`<T>` component](/docs/next/guides/jsx).
-  The `<T>` component allows you to translate JSX content, and is the recommended way to translate strings.
-</Callout>
-
----
-
-## How to use the `useGT()` hook
-
-The `useGT()` hook has to be called within the [`<GTProvider>`](/docs/next/api/components/gtprovider).
-
-To translate a string, simply pass the string directly to the function returned by the hook.
 
+### Asynchronous Components
+```jsx
+import { getGT } from 'gt-next/server';
 
-```tsx copy
-import { useGT } from 'gt-next';
-export function MyComponent() {
-  const translate = useGT();
-  return <div>{translate('Hello, world!')}</div>;
+async function MyServerComponent() {
+  const t = await getGT();
+  return (
+    <input 
+      placeholder={t('Enter your email')}
+      title={t('Email address field')}
+    />
+  );
 }
 ```
 
-<Callout>
-  Unlike traditional i18n libraries, the `useGT()` hook does not require you to pass a `key` to the function.
-  Instead, the string is passed directly to the function.
+## When to Use String Translation
 
-  This means that you don't need to use dictionaries!
-</Callout>
+String translation is ideal when you need plain text rather than JSX:
 
-## How to use the `getGT()` function
+### HTML Attributes
+```jsx
+const t = useGT();
 
-On the other hand, since the `getGT()` function is an asynchronous function, 
-it can be used in async components, and does not need to be called within the `<GTProvider>`.
+<input 
+  placeholder={t('Search products...')}
+  aria-label={t('Product search input')}
+  title={t('Type to search our catalog')}
+/>
+```
 
-The context for `getGT()` is handed by the `withGTConfig` function in your `next.config.ts` file.
+### Object Properties
+```jsx
+const t = useGT();
 
-```tsx copy
-import { getGT } from 'gt-next/server';
-export async function MyComponent() {
-  const translate = await getGT();
-  return <div>{translate('Hello, world!')}</div>;
-}
+const user = {
+  name: 'John',
+  role: 'admin',
+  bio: t('Experienced software developer with 5 years in React'),
+  status: t('Currently available for projects')
+};
 ```
 
+### Configuration & Constants
+```jsx
+const t = useGT();
 
-## Using variables
-
-Often, you will need to translate strings that contain variables.
+const navigationItems = [
+  { label: t('Home'), href: '/' },
+  { label: t('Products'), href: '/products' },
+  { label: t('Contact'), href: '/contact' }
+];
+```
 
-For example, you may need to translate a string that contains numerical values. 
+### When to Use `<T>` Instead
+Use the [`<T>` component](/docs/next/guides/jsx) for JSX content:
 
-To add variables, simply add the variable to the string as a placeholder with `{variable}`, 
-and pass an object as the second argument to the function returned by the hook.
+```jsx
+// ✅ Use <T> for JSX content
+<T><p>Welcome to <strong>our store</strong>!</p></T>
 
-```jsx copy
-const price = 100;
-const translate = useGT();
-translate('There are {count} items in the cart', { count: 10 });
+// ✅ Use string translation for plain text
+<input placeholder={t('Search products')} />
 ```
 
-The `{count}` placeholder will be replaced with the value of the `count` variable.
+## Using Variables
 
-This allows you to display dynamic values in your translations.
+### Basic Variables
+Replace placeholders with dynamic values:
 
-For more information on the API, see the [API reference](/docs/next/api/strings/useGT).
+```jsx
+const t = useGT();
+const itemCount = 5;
 
+// String with placeholder
+const message = t('You have {count} items in your cart', { count: itemCount });
+// Result: "You have 5 items in your cart"
+```
 
-`gt-next` supports ICU message format, which allows you to also format your variables.
+### Multiple Variables
+```jsx
+const t = useGT();
+const order = { id: 'ORD-123', total: 99.99, date: '2024-01-15' };
+
+const confirmation = t(
+  'Order {orderId} for ${total} was placed on {date}',
+  { 
+    orderId: order.id, 
+    total: order.total, 
+    date: order.date 
+  }
+);
+```
 
-```jsx copy
-const price = 100;
-const translate = useGT();
+### ICU Message Format
+For advanced formatting, use ICU syntax:
+
+```jsx
+const t = useGT();
 translate('There are {count, plural, =0 {no items} =1 {one item} other {{count} items}} in the cart', { count: 10 });
 ```
 
 <Callout>
-  ICU message format is a powerful way to format your variables.
-  For more information, see the [ICU message format documentation](https://unicode-org.github.io/icu/userguide/format_parse/messages/).
+  Learn more about ICU Message Format in the [Unicode documentation](https://unicode-org.github.io/icu/userguide/format_parse/messages/).
 </Callout>
 
-
----
-
 ## Examples
 
-1. Translating a string in a component
-
-<Tabs items={['Result', 'Original']}>
-  <Tab value="Result">
+### Form Inputs
 ```jsx
 import { useGT } from 'gt-next';
 
-export default function MyComponent() {
+function ContactForm() {
   const t = useGT();
+  
   return (
-    <div>
-      <h1>{t('Hello, world!')}</h1>
-    </div>
-  )
-}
-```
-  </Tab>
-  <Tab value="Original">
-```jsx
-export default function MyComponent() {
-  return (
-    <div>
-      <h1>Hello, world!</h1>
-    </div>
-  )
+    <form>
+      <input 
+        type="email"
+        placeholder={t('Enter your email address')}
+        aria-label={t('Email input field')}
+      />
+      <textarea 
+        placeholder={t('Tell us about your project...')}
+        aria-label={t('Project description')}
+      />
+      <button type="submit">
+        {t('Send Message')}
+      </button>
+    </form>
+  );
 }
 ```
-  </Tab>
-</Tabs>
 
-2. Translating a string with variables
-
-<Tabs items={['Result', 'Original']}>
-  <Tab value="Result">
+### Navigation Menu
 ```jsx
 import { useGT } from 'gt-next';
 
-export default function MyComponent() {
+function Navigation() {
   const t = useGT();
-  const count = 10;
+  
+  const menuItems = [
+    { label: t('Home'), href: '/', icon: 'home' },
+    { label: t('About Us'), href: '/about', icon: 'info' },
+    { label: t('Services'), href: '/services', icon: 'briefcase' },
+    { label: t('Contact'), href: '/contact', icon: 'mail' }
+  ];
+
   return (
-    <div>
-      <h1>{t('There are {count} items in the cart', { count })}</h1>
-    </div>
-  )
+    <nav>
+      {menuItems.map((item) => (
+        <a key={item.href} href={item.href} title={item.label}>
+          <Icon name={item.icon} />
+          {item.label}
+        </a>
+      ))}
+    </nav>
+  );
 }
 ```
-  </Tab>
-  <Tab value="Original">
+
+### Dynamic Content Factory
 ```jsx
-export default function MyComponent() {
-  const count = 10;
-  return (
-    <div>
-      <h1>There are {count} items in the cart</h1>
-    </div>
-  )
+// utils/productData.js
+export function getProductMessages(t) {
+  return {
+    categories: [
+      { id: 'electronics', name: t('Electronics') },
+      { id: 'clothing', name: t('Clothing') },
+      { id: 'books', name: t('Books') }
+    ],
+    statusMessages: {
+      available: t('In stock and ready to ship'),
+      backordered: t('Currently backordered - ships in 2-3 weeks'),  
+      discontinued: t('This item has been discontinued')
+    },
+    errors: {
+      notFound: t('Product not found'),
+      outOfStock: t('Sorry, this item is currently out of stock')
+    }
+  };
 }
-```
-  </Tab>
-</Tabs>
-
 
-
-3. Translating parts of an object
-
-<Tabs items={['Result', 'Original']}>
-  <Tab value="Result">
-```jsx
+// components/ProductCard.jsx
 import { useGT } from 'gt-next';
+import { getProductMessages } from '../utils/productData';
 
-export default function MyComponent() {
+function ProductCard({ product }) {
   const t = useGT();
-  const users = [
-    {
-      name: 'John',
-      description: t('John is a software engineer at General Translation'),
-    },
-    {
-      name: 'Jane',
-      description: t('Jane is a software engineer at Google'),
-    },
-  ]
+  const messages = getProductMessages(t);
+  
   return (
     <div>
-      {users.map((user) => (
-        <div key={user.name}>
-          <h1>{user.name}</h1>
-          <p>{user.description}</p>
-        </div>
-      ))}
+      <h3>{product.name}</h3>
+      <p>{messages.statusMessages[product.status]}</p>
+      <span>{messages.categories.find(c => c.id === product.categoryId)?.name}</span>
     </div>
-  )
+  );
 }
 ```
-  </Tab>
-  <Tab value="Original">
+
+### Server Component with Metadata
 ```jsx
-export default function MyComponent() {
-  const users = [
-    {
-      name: 'John',
-      description: 'John is a software engineer at General Translation',
-    },
-    {
-      name: 'Jane',
-      description: 'Jane is a software engineer at Google',
-    },
-  ]
+import { getGT } from 'gt-next/server';
+
+export async function generateMetadata({ params }) {
+  const t = await getGT();
+  
+  return {
+    title: t('Product Catalog - Find What You Need'),
+    description: t('Browse our extensive collection of high-quality products'),
+    openGraph: {
+      title: t('Shop Our Products'),
+      description: t('Discover amazing deals on top-rated items')
+    }
+  };
+}
+
+export default async function ProductPage() {
+  const t = await getGT();
+  
   return (
     <div>
-      {users.map((user) => (
-        <div key={user.name}>
-          <h1>{user.name}</h1>
-          <p>{user.description}</p>
-        </div>
-      ))}
+      <h1>{t('Featured Products')}</h1>
+      <p>{t('Check out our latest and most popular items')}</p>
     </div>
-  )
+  );
 }
 ```
-  </Tab>
-</Tabs>
 
+## Common Issues
 
-
-4. Translating shared constants
-
-<Tabs items={['Result', 'Original']}>
-  <Tab value="Result">
-```jsx copy title="src/llms.ts"
-// Custom function to get LLM data with translations
-export function getLLMData(t: (content: string) => string) {
-  return [
-    {
-      name: 'GPT-4.1',
-      id: 'gpt-4.1',
-      description: t('GPT-4.1 is a large language model developed by OpenAI'),
-    },
-    {
-      name: 'Claude 3.7 Sonnet',
-      id: 'claude-3-7-sonnet',
-      description: t('Claude 3.7 Sonnet is a large language model developed by Anthropic'),
-    },
-  ]
-}
-```
+### Dynamic Content at Runtime
+Strings must be known at build time - you cannot translate dynamic content:
 
 ```jsx
-import { getLLMData } from './llms';
-import { useGT } from 'gt-next';
+// ❌ Dynamic content won't work
+function MyComponent() {
+  const [userMessage, setUserMessage] = useState('');
+  const t = useGT();
+  
+  return <p>{t(userMessage)}</p>; // This will fail
+}
 
-export default function MyComponent() {
+// ✅ Use predefined strings
+function MyComponent() {
+  const [messageType, setMessageType] = useState('welcome');
   const t = useGT();
-  const llms = getLLMData(t);
-  return (
-    <div>
-      {llms.map((llm) => (
-        <div key={llm.id}>
-          <h1>{llm.name}</h1>
-          <p>{llm.description}</p>
-        </div>
-      ))}
-    </div>
-  )
+  
+  const messages = {
+    welcome: t('Welcome to our app!'),
+    goodbye: t('Thanks for visiting!')
+  };
+  
+  return <p>{messages[messageType]}</p>;
 }
-```
-  </Tab>
-
-<Tab value="Original">
-```jsx copy title="src/llms.ts"
-export const llms = [
-  {
-    name: 'GPT-4.1',
-    id: 'gpt-4.1',
-    description: 'GPT-4.1 is a large language model developed by OpenAI',
-  },
-  {
-    name: 'Claude 3.7 Sonnet',
-    id: 'claude-3-7-sonnet',
-    description: 'Claude 3.7 Sonnet is a large language model developed by Anthropic',
-  },
-]
 ```
 
+### Hook Rules Violations
+Follow React hook rules when using [`useGT()`](/docs/next/api/strings/useGT):
+
 ```jsx
-import { llms } from './llms';
+// ❌ Don't call hooks conditionally
+function MyComponent({ showMessage }) {
+  if (showMessage) {
+    const t = useGT(); // Hook rule violation
+    return <p>{t('Hello!')}</p>;
+  }
+  return null;
+}
 
-export default function MyComponent() {
-  return (
-    <div>
-      {llms.map((llm) => (
-        <div key={llm.id}>
-          <h1>{llm.name}</h1>
-          <p>{llm.description}</p>
-        </div>
-      ))}
-    </div>
-  )
+// ✅ Always call hooks at top level
+function MyComponent({ showMessage }) {
+  const t = useGT();
+  
+  if (showMessage) {
+    return <p>{t('Hello!')}</p>;
+  }
+  return null;
 }
 ```
-</Tab>
-</Tabs>
-
-<Callout type="info">
-  In this last example, we turned the `llms` array into a function that returns the data with translations.
-  We passed the `t` function to the function that returns the data.
-
-  Alternatively, you could also turn the `llms` array into a custom hook.
-  However, this is not recommended, as you will need to be very careful about how you use the `useGT()` hook,
-  so as to not violate the [rules of React](https://react.dev/reference/rules/rules-of-hooks).
-
-  <Accordions>
-    <Accordion title="Why can't I directly import the `llms` array?">
-      This is because the `useGT()` hook requires access to the React context of the component that is calling it.
-      This context includes information about the current language and the translations for the current language.
-
-      If you try to import the `llms` array directly, without knowing the current language,
-      you will not be able to translate the strings.
-    </Accordion>
-  </Accordions>
-</Callout>
 
----
+### Synchronous vs Asynchronous Confusion
+Use the right function for your component type:
 
-## Common Pitfalls
-
-### Translating Dynamic Content
-
-All strings must be known at build time.
-
-This means that you cannot translate dynamic content that is generated or retrieved at runtime.
+```jsx
+// ❌ Wrong: useGT in async component
+export default async function AsyncComponent() {
+  const t = useGT(); // This won't work
+  return <p>{t('Hello')}</p>;
+}
 
-This includes variables, even if they are strings.
+// ✅ Correct: getGT in async component  
+export default async function AsyncComponent() {
+  const t = await getGT();
+  return <p>{t('Hello')}</p>;
+}
 
-```jsx
-export default function MyComponent() {
-  const [dynamicContent, setDynamicContent] = useState('Hello, world!');
+// ✅ Correct: useGT in synchronous component
+export default function SyncComponent() {
   const t = useGT();
-  return (
-    <div>
-      <h1>{t(dynamicContent)}</h1> {/* This will not work */}
-    </div>
-  )
+  return <p>{t('Hello')}</p>;
 }
 ```
 
-<Accordions>
-  <Accordion title="What if I need to translate dynamic content?">
-    If you need to translate dynamic content, read our guide on how to [translate content on-demand](/docs/next/guides/dynamic-content).
-    This only works on Next.js server components.
-  </Accordion>
-</Accordions>
-
-<Callout type="warn">
-  The CLI tool will warn you if you try to translate dynamic content with the `useGT()` hook.
+<Callout>
+  For truly dynamic content that needs runtime translation, see the [Dynamic Content Guide](/docs/next/guides/dynamic-content).
 </Callout>
 
-
----
-
 ## Next Steps
- * Learn about how to [translate JSX content on-demand](/docs/next/guides/dynamic-content).
- * Learn more about the [`<T>` component](/docs/next/guides/jsx).
- * See the [API reference for `useGT()`](/docs/next/api/strings/useGT).
\ No newline at end of file
+
+- [Dynamic Content Guide](/docs/next/guides/dynamic-content) - Handle runtime translation
+- [Shared Strings Guide](/docs/next/guides/shared-strings) - Organize reusable translations
+- API References:
+  - [`useGT()` Hook](/docs/next/api/strings/useGT)
+  - [`getGT()` Function](/docs/next/api/strings/getGT)
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/next/guides/t.mdx b/apps/docs/content/docs/en/next/guides/t.mdx
new file mode 100644
index 000000000..d5a5bc3aa
--- /dev/null
+++ b/apps/docs/content/docs/en/next/guides/t.mdx
@@ -0,0 +1,226 @@
+---
+title: The <T> Component
+description: How to internationalize JSX components using the <T> component
+---
+
+The [`<T>` component](/docs/next/api/components/t) is the primary tool for internationalizing JSX content in your Next.js application. It wraps your JSX elements and automatically translates them based on the user's locale.
+
+## Quick Start
+
+Transform any static JSX content by wrapping it with [`<T>`](/docs/next/api/components/t):
+
+```jsx
+import { T } from 'gt-next';
+
+// Before
+function Greeting() {
+  return <p>Hello, world!</p>;
+}
+
+// After
+function Greeting() {
+  return <T><p>Hello, world!</p></T>;
+}
+```
+
+For dynamic content within [`<T>`](/docs/next/api/components/t), use [Variable Components](/docs/next/guides/variables) and [Branching Components](/docs/next/guides/branches).
+
+## Basic Usage
+
+The [`<T>` component](/docs/next/api/components/t) accepts any JSX content as children:
+
+```jsx
+// Simple text
+<T>Welcome to our app</T>
+
+// HTML elements
+<T><h1>Page Title</h1></T>
+
+// Complex nested JSX
+<T>
+  <div className="alert">
+    <span>Important:</span> Please read carefully.
+  </div>
+</T>
+```
+
+## Configuration Options
+
+### Adding Context
+
+Provide translation context for ambiguous terms:
+
+```jsx
+<T context="notification popup, not bread">
+  Click the toast to dismiss
+</T>
+```
+
+### Setting Translation IDs
+
+Use explicit IDs for consistent translations:
+
+```jsx
+<T id="welcome-message">
+  Welcome back, user!
+</T>
+```
+
+## When to Use `<T>`
+
+Use [`<T>`](/docs/next/api/components/t) for **static content only**:
+
+```jsx
+// ✅ Static content works
+<T><button>Click here</button></T>
+<T><h1>Welcome to our site</h1></T>
+
+// ❌ Dynamic content breaks
+<T><p>Hello {username}</p></T>
+<T><p>Today is {new Date()}</p></T>
+
+// ✅ Use Variable components for dynamic content
+<T>
+  <p>Hello <Var>{username}</Var></p>
+</T>
+```
+
+<Callout>
+  Variable and Branching components are designed to work inside [`<T>`](/docs/next/api/components/t) for dynamic content. See [Variable Components](/docs/next/guides/variables) and [Branching Components](/docs/next/guides/branches) guides for details.
+</Callout>
+
+## Examples
+
+### Simple Elements
+```jsx
+// Basic text
+<T>Hello, world!</T>
+
+// Button with text
+<T><Button>Submit Form</Button></T>
+
+// Heading with styling
+<T><h1 className="text-2xl font-bold">Welcome</h1></T>
+```
+
+### Complex Components
+```jsx
+// Navigation menu
+<T>
+  <nav className="navbar">
+    <a href="/about">About Us</a>
+    <a href="/contact">Contact</a>
+  </nav>
+</T>
+
+// Alert message
+<T>
+  <div className="alert alert-warning">
+    <AlertIcon className="w-5 h-5" />
+    <span>Your session expires in 5 minutes</span>
+  </div>
+</T>
+```
+
+### With Variables
+```jsx
+// Combining static text with dynamic values
+<T>
+  <p>Welcome back, <Var>{user.name}</Var>!</p>
+</T>
+
+// Form with mixed content
+<T>
+  <label>
+    Email: <input type="email" placeholder="Enter your email" />
+  </label>
+</T>
+```
+
+<Callout>
+  Learn more about the [`<Var>` component](/docs/next/api/components/var) in the [Variable Components Guide](/docs/next/guides/variables).
+</Callout>
+
+## Production Setup
+
+### Build Process
+Add translation to your build pipeline:
+
+```json title="package.json"
+{
+  "scripts": {
+    "build": "npx gtx-cli translate && <...YOUR_BUILD_COMMAND...>"
+  }
+}
+```
+
+### Development vs Production Behavior
+- **Development**: With a dev API key, translations happen on-demand when components render. You'll see real-time translation as you develop.
+- **Production**: All translations are pre-built during the build stage and will be visible once your application is live.
+
+Set your development API key in your environment to enable live translation during development. You can create one in the Dashboard under [API Keys](https://dash.generaltranslation.com/en-US/project/api-keys).
+
+### Privacy Considerations
+Content in [`<T>`](/docs/next/api/components/t) components is sent to the GT API for translation. For sensitive data, use [Variable Components](/docs/next/guides/variables#privacy) to keep private information local:
+
+```jsx
+// Safe - sensitive data stays local
+<T>
+  Welcome back, <Var>{username}</Var>
+</T>
+```
+
+## Common Issues
+
+### Component Boundaries
+[`<T>`](/docs/next/api/components/t) only translates direct children, not content inside other components:
+
+```jsx
+// ❌ Wrong - content inside components won't be translated
+function MyComponent() {
+  return <p>This won't be translated</p>;
+}
+
+<T>
+  <h1>This will be translated</h1>
+  <MyComponent /> {/* Content inside won't be translated */}
+</T>
+
+// ✅ Correct - wrap each component individually
+function MyComponent() {
+  return <T><p>This will be translated</p></T>;
+}
+
+<T><h1>This will be translated</h1></T>
+<MyComponent />
+```
+
+### Nesting `<T>` Components
+
+```jsx
+// ❌ Don't nest <T> components
+<T>
+  <T>Hello world</T> {/* Don't do this */}
+</T>
+```
+
+### Dynamic Content Errors
+The CLI will error on dynamic content in [`<T>`](/docs/next/api/components/t). Wrap dynamic values with Variable components:
+
+```jsx
+// ❌ Wrong - dynamic content breaks
+<T><p>Hello {username}</p></T>
+
+// ✅ Correct - use Variable components
+<T><p>Hello <Var>{username}</Var></p></T>
+```
+
+<Callout>
+  See the [Variable Components Guide](/docs/next/guides/variables) for handling dynamic values and the [Branching Components Guide](/docs/next/guides/branches) for conditional content.
+</Callout>
+
+## Next Steps
+
+- [Variable Components Guide](/docs/next/guides/variables) - Handle dynamic content within JSX translations
+- [Branching Components Guide](/docs/next/guides/branches) - Add conditional logic to your translations
+- [\<T\> Component API Reference](/docs/next/api/components/t)
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/next/guides/variables.mdx b/apps/docs/content/docs/en/next/guides/variables.mdx
index 31eaca57a..bfa3db832 100644
--- a/apps/docs/content/docs/en/next/guides/variables.mdx
+++ b/apps/docs/content/docs/en/next/guides/variables.mdx
@@ -1,278 +1,225 @@
 ---
-title: Using Variables
-description: How to use variable components
+title: Variable Components
+description: How to use variable components for dynamic content within translations
 ---
 
-## Overview
+Variable components allow you to safely include dynamic content within [`<T>`](/docs/next/api/components/t) components. They handle formatting and localization locally without sending data to the translation API, making them perfect for sensitive information like usernames, account numbers, and financial data.
 
-Variable components in `gt-next` allow you to insert dynamic content into translations.
-These components include:
+## Available Components
 
-- [`<Var>`](/docs/next/api/components/var): For rendering variables.
-- [`<Num>`](/docs/next/api/components/num): For formatting numbers.
-- [`<Currency>`](/docs/next/api/components/currency): For formatting currency values.
-- [`<DateTime>`](/docs/next/api/components/datetime): For formatting dates and times.
+- [`<Var>`](/docs/next/api/components/var): Raw dynamic content without formatting
+- [`<Num>`](/docs/next/api/components/num): Numbers with locale-specific formatting
+- [`<Currency>`](/docs/next/api/components/currency): Currency values with symbols and formatting
+- [`<DateTime>`](/docs/next/api/components/datetime): Dates and times with locale conventions
 
-In this guide, we will cover:
-<Steps>
-  <Step>
-    What are variable components?
-  </Step>
-  <Step>
-    How to use variable components
-  </Step>
-  <Step>
-    Examples
-  </Step>
-  <Step>
-    Common pitfalls
-  </Step>
-</Steps>
+## Quick Start
 
+Variable components work inside [`<T>`](/docs/next/api/components/t) to handle dynamic content:
 
-## What are variable components?
-
-Variable components are used to wrap dynamic content such as user names, numerical values, dates, and currencies.
-
-These components allow you to format and render dynamic values in a way that aligns with your user's locale, without requiring any external translations.
-
-Use variable components in conjunction with the `<T>` component to ensure that dynamic content is displayed accurately and consistently.
+```jsx
+import { T, Var, Num, Currency, DateTime } from 'gt-next';
 
-Each variable component has different behavior:
+function UserProfile({ user }) {
+  return (
+    <T>
+      <p>Welcome back, <Var>{user.name}</Var>!</p>
+      <p>You have <Num>{user.itemCount}</Num> items.</p>
+      <p>Balance: <Currency currency="USD">{user.balance}</Currency></p>
+      <p>Last login: <DateTime>{user.lastLogin}</DateTime></p>
+    </T>
+  );
+}
+```
 
-- [`<Var>`](/docs/next/api/components/var): Renders any content dynamically, such as user names or identifiers.
-- [`<Num>`](/docs/next/api/components/num): Formats numerical values according to locale-specific rules.
-- [`<Currency>`](/docs/next/api/components/currency): Formats currency values with symbols and localization rules.
-- [`<DateTime>`](/docs/next/api/components/datetime): Formats dates and times using locale-specific conventions.
+## How Variable Components Work
 
-While JSX content and strings are translated via the General Translation API, variable components are completely handled locally.
+Variable components solve the dynamic content problem by:
 
-The `<Num>`, `<Currency>`, and `<DateTime>` components use the [JS i18n API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl) to format the content according to the user's locale.
+1. **Wrapping dynamic values** so they can be used inside [`<T>`](/docs/next/api/components/t)
+2. **Handling formatting locally** using the browser's built-in i18n APIs  
+3. **Keeping data private** - content is never sent to the translation API
+4. **Providing localization** based on the user's current locale
 
-<Callout type="info">
-  Content wrapped in variable components is never sent to the General Translation API, ensuring data privacy and security.
+```jsx
+// ❌ This breaks - dynamic content in <T>
+<T><p>Hello {username}</p></T>
 
-  See the section on [Data Privacy](#privacy) for more information.
-</Callout>
+// ✅ This works - dynamic content wrapped
+<T><p>Hello <Var>{username}</Var></p></T>
+```
 
----
+## Component Guide
 
-## How to use variable components
+### `<Var>` - Raw Dynamic Content
 
-### Basic Usage
+Use [`<Var>`](/docs/next/api/components/var) for any dynamic content that doesn't need special formatting:
 
-The usage for all variable components is the same.
+```jsx
+// User information
+<T>
+  <p>Hello, <Var>{user.name}</Var>!</p>
+  <p>Your account ID is <Var>{user.accountId}</Var></p>
+</T>
 
-```tsx
-const user = {
-  name: 'John',
-  age: 30,
-  balance: 1000,
-  birthday: new Date('1990-01-01'),
-}
-<div>
-  <Var>{user.name}</Var>
-  <Num>{user.age}</Num>
-  <Currency>{user.balance}</Currency>
-  <DateTime>{user.birthday}</DateTime>
-</div>
+// Conditional rendering
+<T>
+  Dashboard: <Var>{isAdmin ? <AdminPanel /> : <UserPanel />}</Var>
+</T>
 ```
 
-Simply wrap the variable component around the content you want to display.
-
-### Using Variable Components in `<T>` [#variable-in-t]
+### `<Num>` - Formatted Numbers
 
-By themselves, variable components don't do much, since they require knowledge of the user's locale to format the content.
+Use [`<Num>`](/docs/next/api/components/num) for numbers that should follow locale formatting rules:
 
-Thus, you should use variable components with `<T>` components.
+```jsx
+// Basic number formatting
+<T>
+  You have <Num>{itemCount}</Num> items in your cart.
+</T>
 
-The `<T>` component will not only handle the translation of the surrounding content, but also pass the correct locale to its child variable components.
+// Standalone usage (equivalent to number.toLocaleString())
+<Badge><Num>{totalItems}</Num></Badge>
 
-```tsx
+// Custom formatting options
 <T>
-  The current time is <DateTime>{time}</DateTime>.
+  Distance: <Num options={{ maximumFractionDigits: 2 }}>{distance}</Num> km
 </T>
 ```
 
+### `<Currency>` - Money Values
 
-### Variable localization [#localization]
-
-The `<Num>`, `<Currency>`, and `<DateTime>` components include built-in localization support.
-These components automatically format their content based on your user's selected locale, or based on additional options passed as props.
+Use [`<Currency>`](/docs/next/api/components/currency) for monetary amounts:
 
-For example:
-* [`<Num>`](/docs/next/api/components/num) displays numbers with localized decimal separators.
-* [`<Currency>`](/docs/next/api/components/currency) displays values with localized currency symbols and positioning.
-* [`<DateTime>`](/docs/next/api/components/datetime) displays dates and times according to locale-specific rules.
-
-You can also override the default locale and formatting options by passing props directly to these components.
+```jsx
+// Basic currency formatting (defaults to "USD")
+<T>
+  Your total is <Currency>{total}</Currency>.
+</T>
 
-### Data Privacy [#privacy]
+// Different currencies
+<T>
+  Price: <Currency currency="EUR">{price}</Currency>
+</T>
 
-Variable components handle all formatting locally; therefore, none of their children are sent to the General Translation APIs for translation (when used with `<T>` components).
-This is perfect for keeping sensitive data, such as user names or account numbers, private and secure.
+// Custom formatting
+<Currency 
+  currency="USD" 
+  options={{ minimumFractionDigits: 0 }}
+>
+  {roundedAmount}
+</Currency>
+```
 
-Each variable component handles formatting differently and should be used for specific types of content:
+### `<DateTime>` - Dates and Times
 
-* [`<Var>`](/docs/next/api/components/var): Anything private that does not require formatting
-  - User names, account numbers, etc.
-* [`<Num>`](/docs/next/api/components/num): Private numerical values that should be formatted according to locale
-  - Order quantities, age, distance, etc.
-* [`<Currency>`](/docs/next/api/components/currency): Private currency values that should be formatted according to locale
-  - Transaction amounts, account balances, etc.
-* [`<DateTime>`](/docs/next/api/components/datetime): Private date and time values that should be formatted according to locale
-  - Account creation dates, order timestamps, etc.
+Use [`<DateTime>`](/docs/next/api/components/datetime) for dates and times:
 
-<Callout type="warn">
-  [Branching Components](/docs/next/guides/branches)
-  and [`<T>` components](/docs/next/guides/jsx)
-  do send data to the General Translation APIs for translation.
+```jsx
+// Basic date formatting
+<T>
+  Order placed on <DateTime>{orderDate}</DateTime>
+</T>
 
-  Additionally, nesting a `<T>` inside a `<Var>` component will send the content to the General Translation APIs for translation.
-  ```tsx
-  <T>
-    <Var>
-      <T>Hello, world!</T>
-      Goodbye, World!
-    </Var>
-  </T>
-  ```
-  In the example above, "Hello, world!" will be sent to the General Translation APIs for translation,
-  while "Goodbye, World!" will not.
-</Callout>
+// Time formatting
+<T>
+  Last updated: <DateTime options={{ timeStyle: 'short' }}>{timestamp}</DateTime>
+</T>
 
----
+// Custom date format
+<DateTime options={{ 
+  year: 'numeric', 
+  month: 'long', 
+  day: 'numeric' 
+}}>
+  {eventDate}
+</DateTime>
+```
 
-## Examples
+## Privacy and Security
 
-### `<Var>`
+### Data Stays Local
+Variable components handle all formatting locally using the browser's [Intl APIs](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl). **No dynamic content is sent to the translation API**, making them perfect for:
 
-Because the `<Var>` component does not do any formatting, it should always be used in conjunction with a `<T>` component.
+- User names and personal information
+- Account numbers and IDs
+- Financial data and balances
+- Private timestamps and dates
 
 ```jsx
-import { T, Var } from 'gt-next';
-
-export default function UserGreeting({ user }) {
-  return (
-    <T>
-      Hello, <Var>{user.name}</Var>!
-      Your address is <Var>{user.addr}</Var>
-    </T>
-  );
-}
+// Safe - sensitive data stays local
+<T>
+  Account balance: <Currency currency="USD">{balance}</Currency>
+  Last login: <DateTime>{lastLoginTime}</DateTime>
+</T>
 ```
 
-Variable components also isolate data, so they can be used to render dynamic content that is not part of a translation.
+### Important Exception
+Be careful with nested [`<T>`](/docs/next/api/components/t) components inside variable components:
 
 ```jsx
-import { T, Var } from 'gt-next';
-
-export default function Dashboard({ isAdmin }) {
-  return (
-    <T>
-      Your Dashboard:
-      <Var>{isAdmin ? <AdminDashboard /> : <UserDashboard />}</Var>
-    </T>
-  );
-}
+// ⚠️ The inner <T> content WILL be sent for translation
+<T>
+  <Var>
+    <T>Hello, world!</T>  {/* This gets translated */}
+    {privateData}         {/* This stays local */}
+  </Var>
+</T>
 ```
 
-In the example above, the `isAdmin` ternary operator makes the `Dashboard` component dynamic.
-
-Without the `<Var>`, component, this would be an invalid use of the `<T>` component.
-
-<Callout type="info">
-  When using `<T>` components with dynamic content, use `<Var>` to wrap anything dynamic!
-</Callout>
+## Standalone Usage
 
-
-### `<Num>`
-
-The `<Num>` component can be used as a child of a `<T>` component or as a standalone component.
+Variable components can be used outside of [`<T>`](/docs/next/api/components/t) for pure formatting:
 
 ```jsx
-import { T, Num } from 'gt-next';
-import { Badge } from '@components/custom/cart/Badge';
-
-export default function OrderSummary() {
-  const quantity = 10;
-  return (
-    <>
-      <T>
-        You have <Num>{quantity}</Num> items in your cart.
-      </T>
-      <Badge>
-        <Num>{quantity}</Num> // This is the same as using quantity.toLocaleString()
-      </Badge>
-    </>
-  );
-}
+// These work like their respective .toLocale*() methods
+<span><Num>{count}</Num></span>                    // count.toLocaleString()
+<span><Currency currency="USD">{price}</Currency></span>  // price formatting
+<span><DateTime>{date}</DateTime></span>           // date.toLocaleDateString()
 ```
 
-### `<Currency>`
-
-The `<Currency>` component can be used as a child of a `<T>` component or as a standalone component.
-
-```jsx
-import { T, Currency } from 'gt-next';
-import { Badge } from '@components/custom/cart/Badge';
-
-export default function OrderSummary() {
-  const total = 1000;
-  return (
-    <>
-      <T>
-        Your total is <Currency currency={"USD"}>{total}</Currency>.
-      </T>
-      <Badge>
-        <Currency currency={"USD"}>{total}</Currency> // This will be formatted as $1,000
-      </Badge>
-    </>
-  );
-}
-
-```
+## Common Issues
 
-### `<DateTime>`
+### Ignoring Localization Options
 
-The `<DateTime>` component can be used as a child of a `<T>` component or as a standalone component.
+For [`<Currency>`](/docs/next/api/components/currency), make sure to pass the `currency` prop to specify the currency type. This ensures that the correct currency symbol and formatting are used when displaying the value:
 
 ```jsx
-import { T, DateTime } from 'gt-next';
+// ❌ Defaults to USD - may not be what users expect
+<T>
+  The item costs <Currency>{price}</Currency>
+</T>
 
-export default function OrderSummary() {
-  const date = new Date();
-  return (
-    <T>
-      Your order was placed on <DateTime>{date}</DateTime>.
-    </T>
-    <DateTime>{date}</DateTime> // This is the same as using date.toLocaleDateString() or date.toLocaleTimeString()
-  );
-}
+// ✅ Explicitly specify the currency
+<T>
+  The item costs <Currency currency="EUR">{price}</Currency>
+</T>
 ```
 
----
-
-## Common Pitfalls
-
-### Ignoring Localization Options [#localization-options]
+Other components also have optional props that allow you to customize the formatting:
 
-For `<Currency>`, make sure to pass the `currency` prop to specify the currency type.
-This ensures that the correct currency symbol and formatting are used when displaying the value.
-
-Other components, such as `<Num>` and `<DateTime>`, also have optional props that allow you to customize the formatting as well.
+```jsx
+// Basic formatting
+<T>
+  <Num>{count}</Num> items in stock
+</T>
 
----
+// Custom formatting
+<T>
+  <Num options={{ style: 'percent' }}>{percentage}</Num> completion rate
+</T>
 
-## Notes
- * Variable components isolate data, so they can be used to render dynamic content that is not part of a translation.
- * Variable components do not send data to the General Translation APIs, so they are perfect for keeping sensitive data private and secure.
- * Variable components can be used either as a child of a [`<T>`](/docs/next/guides/jsx) component or as a standalone component.
+// Date formatting
+<T>
+  Last updated: <DateTime options={{ dateStyle: 'short' }}>{lastUpdate}</DateTime>
+</T>
+```
 
 ## Next Steps
- * Explore conditional logic in [Branching Components](/docs/next/guides/branches).
- * Learn more about formatting options for specific variable components in the API Reference:
-   - [`<Num>`](/docs/next/api/components/num)
-   - [`<Currency>`](/docs/next/api/components/currency)
-   - [`<DateTime>`](/docs/next/api/components/datetime)
-   - [`<Var>`](/docs/next/api/components/var)
\ No newline at end of file
+
+- [Branching Components Guide](/docs/next/guides/branches) - Add conditional logic to your translations
+- [String Translation Guide](/docs/next/guides/strings) - Translate plain text without JSX
+- API References:
+  - [`<Var>` Component](/docs/next/api/components/var)
+  - [`<Num>` Component](/docs/next/api/components/num) 
+  - [`<Currency>` Component](/docs/next/api/components/currency)
+  - [`<DateTime>` Component](/docs/next/api/components/datetime)
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/next/introduction.mdx b/apps/docs/content/docs/en/next/introduction.mdx
index d2a3687d3..21d190456 100644
--- a/apps/docs/content/docs/en/next/introduction.mdx
+++ b/apps/docs/content/docs/en/next/introduction.mdx
@@ -5,15 +5,13 @@ description: Overview of General Translation's Next.js SDK
 
 ## Introduction
 
-The General Translation Next.js SDK is an open-source internationalization (i18n) library for Next.js.
+The General Translation Next.js SDK is an open-source internationalization (i18n) library for Next.js applications.
 
-It offers a set of tools to help you internationalize your Next.js application in a easy and maintainable way,
-with feature parity to other popular i18n libraries. 
-It is built on top of the [React SDK](/docs/react), and offers additional features specific to Next.js.
+It provides a comprehensive set of tools to internationalize your Next.js application in an easy and maintainable way, with feature parity to other popular i18n libraries. Built on top of the [React SDK](/docs/react), it offers additional Next.js-specific features.
 
-The Next.js SDK can be used without the General Translation platform, and will act very similarly to other i18n libraries.
+The SDK can be used standalone without the General Translation platform and behaves similarly to other i18n libraries.
 
-However, it also integrates with our platform, offering additional features such as:
+However, it also integrates with our platform for enhanced features:
 
 - Translation Hot Reloading in Development
 - Automatic AI translations
@@ -23,31 +21,34 @@ However, it also integrates with our platform, offering additional features such
 
 ## Concepts
 
-There are 5 main concepts to understand about the SDK.
+There are 6 main concepts to understand about the SDK.
 
 <Steps>
   <Step>
-    Initialization with `withGTConfig`
+    Initialization with [`withGTConfig`](/docs/next/api/config/withGTConfig)
   </Step>
   <Step>
-    The `<GTProvider>` component
+    The [`<GTProvider>`](/docs/next/api/components/gtprovider) component
   </Step>
   <Step>
-    The `<T>` component
+    The [`<T>`](/docs/next/api/components/t) component
   </Step>
   <Step>
-    The `useGT` hook
+    The [`useGT`](/docs/next/api/strings/useGT) hook
   </Step>
   <Step>
-    (Optional) The `useTranslations` hook
+    The [`msg()`](/docs/next/api/strings/msg) function for shared strings
+  </Step>
+  <Step>
+    (Optional) The [`useTranslations`](/docs/next/api/dictionary/useTranslations) hook
   </Step>
 </Steps>
 
 ## Initialization with `withGTConfig`
 
-The `withGTConfig` function is a function that is used to initialize the SDK in a Next.js application.
+The [`withGTConfig`](/docs/next/api/config/withGTConfig) function initializes the SDK in your Next.js application.
 
-It should be placed in your `next.config.[js|ts]` file, and is used to configure the SDK.
+Add it to your `next.config.[js|ts]` file to configure the SDK:
 
 ```tsx title="next.config.ts"
 import { withGTConfig } from 'gt-next/config';
@@ -65,36 +66,40 @@ See the [withGTConfig API Reference](/docs/next/api/config/withGTConfig) for mor
 
 ## The `<GTProvider>` component
 
+The [`<GTProvider>`](/docs/next/api/components/gtprovider) component provides translation context to your application, including the current language and relevant translations.
+
 ```tsx
 import { GTProvider } from 'gt-next';
-```
-
-The `<GTProvider>` component is the main component that you need to add to your application.
-
-It is used to provide the rest of your application with context. 
 
-This context includes the current language and the relevant translations for that language.
-
-The provider is only required if you are using any client-side features. 
-If you are only using server-side features, the provider is not required, but can still be included.
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        <GTProvider>
+          {children}
+        </GTProvider>
+      </body>
+    </html>
+  );
+}
+```
 
-### Important Considerations
+**Important:** The provider should wrap your entire application and be placed as high in the component tree as possible, such as in your root layout.
 
-- The provider should wrap your entire application.
-- Ideally, it should be placed as high in the tree as possible, such as in your root layout.
+The provider is only required for client-side features. Server-side only applications don't require it, but it can still be included.
 
-See the [GTProvider](/docs/next/api/components/gtprovider) page for more information.
+See the [`GTProvider`](/docs/next/api/components/gtprovider) API reference for more information.
 
 ## The `<T>` component
 
-The `<T>` component is the recommended way to translate content in your application.
+The [`<T>`](/docs/next/api/components/t) component is the recommended way to translate content in your application.
 
 It is a React component that can be used to wrap any JSX element, and will automatically render the content of the element into a supported language.
 
 <Callout type="info">
-We recommend using the `<T>` component wherever possible, since it allows for the most flexibility in translations.
+We recommend using the [`<T>`](/docs/next/api/components/t) component wherever possible, since it allows for the most flexibility in translations.
 
-Unlike strings, the `<T>` component can be used to translate HTML content, making it much more powerful than string translations.
+Unlike strings, the [`<T>`](/docs/next/api/components/t) component can be used to translate HTML content, making it much more powerful than string translations.
 </Callout>
 
 ### Examples
@@ -119,29 +124,29 @@ Unlike strings, the `<T>` component can be used to translate HTML content, makin
   Formatting can be done easily with the `<T>` component.
   <Num>{1000}</Num>
   <DateTime>{new Date()}</DateTime>
-  <Currency>{1000}</Currency>
+  <Currency currency="USD">{1000}</Currency>
 </T>
 ```
 
-See the [components](/docs/next/guides/jsx) guide to learn about the different ways to use the `<T>` component.
+The [`<T>`](/docs/next/api/components/t) component works with [variable components](/docs/next/guides/variables) like [`<Num>`](/docs/next/api/components/num), [`<DateTime>`](/docs/next/api/components/datetime), and [`<Currency>`](/docs/next/api/components/currency) for dynamic content formatting.
 
-See the [T API Reference](/docs/next/api/components/t) for the API of the `<T>` component.
+See the [`<T>` component guide](/docs/next/guides/t) to learn about the different ways to use the [`<T>`](/docs/next/api/components/t) component.
 
 ## The `useGT` hook
 
-The `useGT` hook is a React hook that can be used similarly to the `<T>` component, with some trade-offs.
+The [`useGT`](/docs/next/api/strings/useGT) hook is a React hook that can be used similarly to the [`<T>`](/docs/next/api/components/t) component, with some trade-offs.
 
 The hook returns a function that can be used to translate strings.
 
 ```tsx
-const translate = useGT();
+const t = useGT();
 
-translate('Hello, world!');
+t('Hello, world!');
 ```
 
-Compared to the `<T>` component, the `useGT` hook allows for more flexibility in your codebase.
+Compared to the [`<T>`](/docs/next/api/components/t) component, the [`useGT`](/docs/next/api/strings/useGT) hook allows for more flexibility in your codebase.
 
-For example, if you have a complex data structure with nested strings, a `<T>` component would be more difficult to use.
+For example, if you have a complex data structure with nested strings, a [`<T>`](/docs/next/api/components/t) component would be more difficult to use.
 
 ```tsx
 const t = useGT();
@@ -151,13 +156,55 @@ const data = {
 };
 ```
 
-See the [strings](/docs/next/guides/strings) guide to learn more about the `useGT` hook.
+See the [strings](/docs/next/guides/strings) guide to learn more about the [`useGT`](/docs/next/api/strings/useGT) hook.
+
+## The `msg()` function
+
+The [`msg()`](/docs/next/api/strings/msg) function is used to mark strings for translation that are used across multiple components or stored in configuration objects.
+
+This is particularly useful for shared content like navigation labels, form messages, or any text that appears in multiple places throughout your application.
+
+```tsx
+// Mark strings for translation
+import { msg } from 'gt-next';
+
+const navItems = [
+  { label: msg('Home'), href: '/' },
+  { label: msg('About'), href: '/about' },
+  { label: msg('Contact'), href: '/contact' }
+];
+```
+
+```tsx
+// Decode and use the marked strings
+import { useMessages } from 'gt-next';
+
+function Navigation() {
+  const m = useMessages();
+  
+  return (
+    <nav>
+      {navItems.map(item => (
+        <a key={item.href} href={item.href}>
+          {m(item.label)}
+        </a>
+      ))}
+    </nav>
+  );
+}
+```
+
+The [`msg()`](/docs/next/api/strings/msg) function encodes strings with translation metadata, and [`useMessages()`](/docs/next/api/dictionary/useMessages) (or [`getMessages()`](/docs/next/api/dictionary/getMessages) for server components) decodes them.
+
+<Callout type="info">
+Use [`msg()`](/docs/next/api/strings/msg) for shared content that needs to be translated consistently across your application. For component-specific content, prefer [`<T>`](/docs/next/api/components/t) or [`useGT()`](/docs/next/api/strings/useGT).
+</Callout>
 
-See the [useGT API Reference](/docs/next/api/strings/useGT) for more information.
+See the [shared strings](/docs/next/guides/shared-strings) guide to learn more about the `msg()` function.
 
 ## The `useTranslations` hook
 
-The `useTranslations` hook is a React hook that returns a function that can be used to retrieve translations for a given key.
+The [`useTranslations`](/docs/next/api/dictionary/useTranslations) hook is a React hook that returns a function that can be used to retrieve translations for a given key.
 
 ```tsx title="dictionary.ts"
 const dictionary = {
@@ -172,18 +219,18 @@ const translate = useTranslations();
 translate('hello.world');
 ```
 
-This behavior is similar to other translation libraries, such as `react-i18next` and `next-intl`.
+This behavior is similar to other translation libraries, such as [`react-i18next`](https://react.i18next.com/) and [`next-intl`](https://next-intl-docs.vercel.app/).
 
 <Callout type="warn">
-We do not recommend using the `useTranslations` hook in your application. Frequent use of the `useTranslations` hook will make your codebase more difficult to maintain, 
+We do not recommend using the [`useTranslations`](/docs/next/api/dictionary/useTranslations) hook in your application. Frequent use of the [`useTranslations`](/docs/next/api/dictionary/useTranslations) hook will make your codebase more difficult to maintain, 
 and will lead to large tech debt.
 
-Instead, we recommend using the `<T>` component or the `useGT` hook.
+Instead, we recommend using the [`<T>`](/docs/next/api/components/t) component or the [`useGT`](/docs/next/api/strings/useGT) hook.
 
-If you are migrating from another i18n library, the `useTranslations` hook is a drop-in replacement and can useful for incrementally migrating your codebase.
+If you are migrating from another i18n library, the [`useTranslations`](/docs/next/api/dictionary/useTranslations) hook is a drop-in replacement and can useful for incrementally migrating your codebase.
 </Callout>
 
-See the [dictionaries](/docs/next/guides/dictionaries) guide to learn more about the `useTranslations` hook.
+See the [dictionaries](/docs/next/guides/dictionaries) guide to learn more about the [`useTranslations`](/docs/next/api/dictionary/useTranslations) hook.
 
 See the [useTranslations API Reference](/docs/next/api/dictionary/useTranslations) for more information.
 
@@ -191,6 +238,7 @@ See the [useTranslations API Reference](/docs/next/api/dictionary/useTranslation
 
 ## Next Steps
 
-- Learn about how to setup your Next.js project with the SDK: [Quickstart](/docs/next)
-- Learn about how to translate strings with the `useGT` hook: [Translating Strings](/docs/next/guides/hooks)
-- Learn about how to translate JSX content with the `<T>` component: [Translating JSX](/docs/next/guides/jsx)
+- Learn about how to setup your Next.js project with the SDK: [Quickstart](/docs/next/tutorials/quickstart)
+- Learn about how to translate JSX content with the [`<T>`](/docs/next/api/components/t) component: [JSX Translation Guide](/docs/next/guides/t)
+- Learn about how to translate strings with the [`useGT`](/docs/next/api/strings/useGT) hook: [String Translation Guide](/docs/next/guides/strings)
+- Learn about shared strings with the [`msg()`](/docs/next/api/strings/msg) function: [Shared Strings Guide](/docs/next/guides/shared-strings)
diff --git a/apps/docs/content/docs/en/next/meta.json b/apps/docs/content/docs/en/next/meta.json
index 0f2a080bd..fefd3786a 100644
--- a/apps/docs/content/docs/en/next/meta.json
+++ b/apps/docs/content/docs/en/next/meta.json
@@ -3,22 +3,24 @@
   "icon": "Triangle",
   "pages": [
     "---Getting Started---",
-    "index",
     "introduction",
-    "---Guides---",
-    "guides/jsx",
-    "guides/strings",
-    "guides/shared-strings",
+    "index",
+    "config",
+    "---Core Translation---",
+    "guides/t",
     "guides/variables",
     "guides/branches",
+    "guides/strings",
+    "guides/shared-strings",
+    "guides/dynamic-content",
+    "guides/dictionaries",
     "guides/languages",
+    "---Advanced Integration---",
     "guides/local-tx",
-    "guides/dictionaries",
-    "guides/migration",
-    "guides/dynamic-content",
     "guides/middleware",
     "guides/ssg",
     "guides/rtl",
+    "guides/migration",
     "---Technical Concepts---",
     "concepts/environments",
     "concepts/stand-alone",
@@ -34,7 +36,6 @@
     "---Tutorials---",
     "tutorials/quickstart",
     "tutorials/quickdeploy",
-    "tutorials/examples/next-speedrun",
     "tutorials/examples/currency-converter"
   ],
   "root": true,
diff --git a/apps/docs/content/docs/en/next/tutorials/examples/meta.json b/apps/docs/content/docs/en/next/tutorials/examples/meta.json
index 29df04997..dc76315fc 100644
--- a/apps/docs/content/docs/en/next/tutorials/examples/meta.json
+++ b/apps/docs/content/docs/en/next/tutorials/examples/meta.json
@@ -1,4 +1,4 @@
 {
-    "title": "Build an App",
-    "pages": ["next-speedrun", "currency-converter"]
-}
\ No newline at end of file
+  "title": "Build an App",
+  "pages": ["currency-converter"]
+}
diff --git a/apps/docs/content/docs/en/next/tutorials/examples/next-speedrun.mdx b/apps/docs/content/docs/en/next/tutorials/examples/next-speedrun.mdx
index ae59d36e9..d32052419 100644
--- a/apps/docs/content/docs/en/next/tutorials/examples/next-speedrun.mdx
+++ b/apps/docs/content/docs/en/next/tutorials/examples/next-speedrun.mdx
@@ -36,7 +36,7 @@ Navigate to your Next.js project's root directory and run:
 ```bash copy
 cd next-quickstart
 npm i gt-next
-npm i gtx-cli --save-dev
+npm i gtx-cli
 ```
 
 ## Step 3: Add your environment variables.
diff --git a/apps/docs/content/docs/en/next/tutorials/quickstart.mdx b/apps/docs/content/docs/en/next/tutorials/quickstart.mdx
index ebbc6227d..0dc0990ad 100644
--- a/apps/docs/content/docs/en/next/tutorials/quickstart.mdx
+++ b/apps/docs/content/docs/en/next/tutorials/quickstart.mdx
@@ -3,36 +3,7 @@ title: Next.js Quickstart
 description: Easily internationalize your Next.js App with gt-next
 ---
 
-## Overview
-
-This quickstart guide will walk you through how to setup your Next.js application with `gt-next`.
-
-By the end of this guide, you will have a Next.js app that is ready to start translating content.
-
-In this guide, we will cover the following:
-
-<Steps>
-  <Step>
-    Installation
-  </Step>
-  <Step>
-    Configuration
-  </Step>
-  <Step>
-    Usage
-  </Step>
-  <Step>
-    Testing Your App
-  </Step>
-  <Step>
-    Deployment
-  </Step>
-</Steps>
-
-### Prerequisites
-
-- A Next.js application using the App Router
-- Basic knowledge of Next.js and JavaScript
+**Prerequisites:** Next.js App Router, basic JavaScript knowledge
 
 ## Installation
 
@@ -41,8 +12,7 @@ Install the `gt-next` and `gtx-cli` packages:
 <Tabs items={['npm', 'yarn', 'bun', 'pnpm']}>
   <Tab value="npm">
   ```bash 
-  npm i gt-next
-  npm i --save-dev gtx-cli
+  npm i gt-next gtx-cli
   ``` 
   </Tab>
   <Tab value="yarn">
@@ -66,17 +36,8 @@ Install the `gt-next` and `gtx-cli` packages:
   </Tab>
 </Tabs>
 
----
-
 <Callout type="info">
-  **Automatic Setup:** We have an experimental Setup Wizard that can help you setup your project with `gt-next`.
-
-  Try it out by running `npx gtx-cli@latest`. You'll still need to manually internationalize content, but it will help you get started.
-
-  See the [Setup Wizard](/docs/cli/init) reference guide for more information. 
-
-  Alternatively, if you would like your AI tool like Claude Code, Cursor, or Windsurf to automatically setup your project, 
-  you can use our [mcp server](/docs/platform/ai-tools).
+  **Quick Setup:** Try `npx gtx-cli@latest` for automatic configuration. See the [Setup Wizard](/docs/cli/init) guide or use our [AI tools integration](/docs/platform/ai-tools).
 </Callout>
 
 
@@ -84,93 +45,72 @@ Install the `gt-next` and `gtx-cli` packages:
 
 ### `withGTConfig`
 
-The `withGTConfig` function is a function that is used to initialize the SDK in a Next.js application.
-
-Place this in your `next.config.[js|ts]` file.
+The [`withGTConfig`](/docs/next/api/config/withGTConfig) function initializes the SDK in your Next.js application. Add it to your `next.config.[js|ts]` file:
 
 ```tsx title="next.config.ts"
 import { withGTConfig } from 'gt-next/config';
 
 const nextConfig = {
-  // Your next.config.ts options
+  // Your existing Next.js config
 };
 
-export default withGTConfig(nextConfig, {
+export default withGTConfig(nextConfig. {
   // Additional GT configuration options
 });
 ```
 
-See the [withGTConfig API Reference](/docs/next/api/config/withGTConfig) for more information.
-
 ### `GTProvider`
 
-`gt-next` also exports a `GTProvider` component. This component is used to provide context to client-side components in your Next.js application.
-
-The `GTProvider` and `withGTConfig` work together to provide context to your application.
+The [`GTProvider`](/docs/next/api/components/gtprovider) component provides translation context to client-side components. It manages locale state, translations, and enables the [`useGT`](/docs/next/api/strings/useGT) and [`useTranslations`](/docs/next/api/dictionary/useTranslations) hooks.
 
-This context includes:
 
-- Managing the user's current locale
-- The relevant translations for that locale
-- Context for the `useGT` hook
-- Context for the `useTranslations` hook
+Add the [`GTProvider`](/docs/next/api/components/gtprovider) to your root layout(s):
 
+```tsx title="app/layout.tsx"
+import { GTProvider } from 'gt-next';
 
-<Steps>
-  <Step>
-    First, add the `GTProvider` component to the root layout of your application. It should be placed as high up in your component tree as possible.
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        <GTProvider>
+          {children}
+        </GTProvider>
+      </body>
+    </html>
+  );
+}
+```
 
-    ```tsx copy title="src/layout.tsx"
-    import { GTProvider } from 'gt-next';
+Create a [`gt.config.json`](/docs/cli/reference/config) file in your project root:
 
-    export default function RootLayout({ children }) {
-      return (
-        <html>
-          <body>
-            <GTProvider>
-              {children}
-            </GTProvider>
-          </body>
-        </html>
-      );
-    }
-    ```
-    If you have multiple root layouts, place the `GTProvider` in each one.
-  </Step>
-  <Step>
-    Next, create a [`gt.config.json`](/docs/cli/reference/config) file in the root of your project.
-    This file is used to configure both the `gtx-cli` tool and the `gt-next` library.
-
-    ```json title="gt.config.json" copy
-    {
-      "defaultLocale": "en",
-      "locales": ["fr", "es"]
-    }
-    ```
-    You should customize the `defaultLocale` and `locales` to match your project. See the list of [supported locales](/docs/platform/locale-strings) for more information.
+```json title="gt.config.json"
+{
+  "defaultLocale": "en",
+  "locales": ["fr", "es", "de"]
+}
+```
 
-    `withGTConfig` will automatically detect the `gt.config.json` file in your project, and use it to configure the SDK.
-  </Step>
-</Steps>
+Customize the locales for your project. See [supported locales](/docs/platform/locale-strings) for options.
 
 ### Environment Variables
 
-Set the following environment variables:
+Add to your `.env.local` file for development hot-reloading:
 
-```bash copy
-GT_API_KEY="" # Your General Translation Developer API key
-GT_PROJECT_ID="" # Your General Translation project ID
+```bash title=".env.local"
+GT_API_KEY="your-dev-api-key"
+GT_PROJECT_ID="your-project-id"
 ```
 
 <Callout type="warn">
-  **Make sure your API key variable is only set in your development environment! It should not be set in production.**
+  **Development only:** Don't set `GT_API_KEY` in production - it's only for development hot-reloading.
 </Callout>
 
-You can get a free API key and project ID by creating a [General Translation account](https://dash.generaltranslation.com/signup).
-
-After creating an account, navigate to the [Development API Keys](https://dash.generaltranslation.com/settings/dev-api-keys) page to get your Dev API key and project ID.
+Get your free API keys at [dash.generaltranslation.com](https://dash.generaltranslation.com/signup) or run:
 
-Alternatively, you can also use the CLI tool command [`npx gtx-cli auth`](/docs/cli/auth) to generate an API key and project ID for your project, saved to your `.env.local` file.
+```bash
+npx gtx-cli auth
+```
 
 <Accordions>
   <Accordion title="What if I don't want to use the General Translation platform?">
@@ -195,84 +135,81 @@ Alternatively, you can also use the CLI tool command [`npx gtx-cli auth`](/docs/
 
 ## Usage
 
-Great! If you've followed the steps above, your Next.js app is now setup to use `gt-next`.
-
-The next step is to internationalize your content. 
-Here, we'll give a brief overview of the different ways to translate content in your application.
-
-### `<T>` Component
+Now you can start internationalizing your content. There are two main approaches:
 
-The `<T>` component is the main component for translating JSX content in your application.
+### JSX Content with `<T>`
 
-To use it, simply wrap the JSX you want to translate in the `<T>` component.
+Wrap JSX elements to translate them using the [`<T>`](/docs/next/api/components/t) component:
 
 ```tsx
 import { T } from 'gt-next';
-<T>
-  <div>Your content</div>
-</T>
+
+function Welcome() {
+  return (
+    <T>
+      <h1>Welcome to our app!</h1>
+    </T>
+  );
+}
 ```
 
-If you have dynamic content, you'll need to use [variable components](/docs/next/guides/variables) to pass in the dynamic values.
+For dynamic content, use [variable components](/docs/next/guides/variables) like [`<Var>`](/docs/next/api/components/var):
 
 ```tsx
 import { T, Var } from 'gt-next';
 
-<T>
-  <div>Hello, <Var>{name}</Var>!</div>
-</T>
+function Greeting({ user }) {
+  return (
+    <T>
+      <p>Hello, <Var>{user.name}</Var>!</p>
+    </T>
+  );
+}
 ```
 
-See the [Translating JSX](/docs/next/guides/jsx) guide for more information.
-
+See the guide on [using the `<T>` component](/docs/next/guides/t) for more information.
 
-### `useGT` Hook
+### Plain Strings with `useGT`
 
-The `useGT` hook is a React hook that returns a function that can be used to translate strings.
+For attributes, labels, and plain text using the [`useGT`](/docs/next/api/strings/useGT) hook:
 
 ```tsx
-import { useGT } from 'gt-next'
-
-const translate = useGT();
-translate('Hello, world!');
+import { useGT } from 'gt-next';
+
+function ContactForm() {
+  const t = useGT();
+  
+  return (
+    <input 
+      placeholder={t('Enter your email')}
+      aria-label={t('Email input field')}
+    />
+  );
+}
 ```
 
-The `useGT` hook can be used in both client-side and server-side components.
-For async components, use the async `getGT()` function instead.
-
-
-See the [Translating Strings](/docs/next/guides/strings) guide for more information.
-
-
-<Callout type="info">
-  Utilizing the hot-reload translation functionality will be helpful for internationalizing your application.
-
-  To enable this, make sure you have the `GT_API_KEY` and `GT_PROJECT_ID` environment variables set in your development environment.
-</Callout>
+For server components, use [`getGT()`](/docs/next/api/strings/getGT) instead of [`useGT()`](/docs/next/api/strings/useGT).
 
+See the guide on [translating strings](/docs/next/guides/strings) for more information.
 
 ---
 
 
 ## Testing Your App
 
-Congratulations! 🥳 If you've followed the steps above, your app is now multilingual! Let's see it in action.
-
-
-### See Your App in a Different Language
-
-<Steps>
-  <Step>
-    Add the [`<LocaleSelector>`](/docs/next/api/components/localeSelector) component to your app.
-    This will allow you to select a different language for your app.
-    <Callout>
-      **Tip:**
-      You can also skip this step and just change your language in your browser settings.
-    </Callout>
-  </Step>
-  <Step>
-    Start your Next.js app in development mode.
-    <Tabs items={["npm", "yarn", "bun", "pnpm"]}>
+Test your translations by switching languages:
+
+1. **Add a locale selection dropdown** using [`<LocaleSelector>`](/docs/next/api/components/localeSelector):
+   ```tsx
+   import { LocaleSelector } from 'gt-next';
+   
+   function App() {
+     return <LocaleSelector />;
+   }
+   ```
+   
+2. **Start your dev server**:
+   <Tabs items={["npm", "yarn", "bun", "pnpm"]}>
       <Tab value="npm">
       ```bash
       npm run dev 
@@ -294,12 +231,10 @@ Congratulations! 🥳 If you've followed the steps above, your app is now multil
       ```
       </Tab>
     </Tabs>
-  </Step>
-  <Step>
-    Open up your app in your preferred browser (usually at
-    [http://localhost:3000](http://localhost:3000)).
-  </Step>
-</Steps>
+
+3. **Visit [localhost:3000](http://localhost:3000)** and change languages via the locale selection dropdown.
+
+In development, translations happen on-demand (you'll see a brief loading time). In production, everything is pre-translated.
 
 ### Troubleshooting
 
@@ -349,58 +284,38 @@ Congratulations! 🥳 If you've followed the steps above, your app is now multil
 
 ## Deployment
 
-Great! If you're satisfied with your translations and the functionality of your app, you can now deploy your application.
-
-The behavior of `gt-next` in production is slightly different from development. Specifically, no translations will be performed at runtime (with the exception of the `<Tx>` component & `tx` function).
-
-This means that you'll need to translate your content before deploying your application, in the build process.
-
-Luckily, the `gtx-cli` tool has a `translate` command that can be used to automatically translate your content.
-
-<Steps>
-  <Step>
-    First, you'll need to get a Production API key from the [General Translation platform](https://dash.generaltranslation.com).
-
-    Please note that this key is different from your Development API key, and begins with `gtx-api-`, instead of `gtx-dev-`.
-
-    Read about the difference between Development and Production keys [here](/docs/next/concepts/environments).
-  </Step>
-  <Step>
-    Add this environment variable to your CI/CD pipeline.
-
-    ```bash
-    GT_PROJECT_ID=<your-project-id>
-    GT_API_KEY=<your-production-api-key>
-    ```
-    <Callout type='warn'>
-      Make sure that `GT_API_KEY` is **NOT** prefixed with `NEXT_PUBLIC_`!
-
-      If it is, you'll risk exposing your API key to the public.
-    </Callout>
-  </Step>
-  <Step>
-    Run the `translate` command to translate your content.
-
-    ```bash
-    npx gtx-cli translate
-    ```
-    You can configure the behavior of the `translate` command with the [`gt.config.json`](/docs/cli/reference/config) file.
-
-    See the [CLI Tool](/docs/cli/translate) reference guide for more information.
-    
-  </Step>
-  <Step>
-    Add the `translate` command to your build process.
-
-    ```json title="package.json" copy
-    {
-      "scripts": {
-        "build": "npx gtx-cli translate && <...YOUR_BUILD_COMMAND...>"
-      }
-    }
-    ```
-  </Step>
-</Steps>
+For production, you need to pre-translate content since runtime translation is disabled (except for [`<Tx>`](/docs/next/api/components/tx) and [`tx()`](/docs/next/api/strings/tx) functions).
+
+1. **Get a production API key** from [dash.generaltranslation.com](https://dash.generaltranslation.com). 
+   
+   Production keys begin with `gtx-api-` (different from dev keys which start with `gtx-dev-`). Learn more about [environment differences](/docs/next/concepts/environments).
+
+2. **Add to your CI/CD environment**:
+   ```bash
+   GT_PROJECT_ID=your-project-id
+   GT_API_KEY=gtx-api-your-production-key
+   ```
+   <Callout type="warn">
+     **Never** prefix production keys with `NEXT_PUBLIC_` - they should remain server-side only.
+   </Callout>
+
+3. **Run the translate command** to translate your content:
+   ```bash
+   npx gtx-cli translate
+   ```
+   
+   You can configure the behavior of the translate command with the [`gt.config.json`](/docs/cli/reference/config) file.
+   
+   See the [CLI Tool](/docs/cli/translate) reference guide for more information.
+
+4. **Update your build script** to translate before building:
+   ```json title="package.json"
+   {
+     "scripts": {
+       "build": "npx gtx-cli translate && <...YOUR_BUILD_COMMAND...>"
+     }
+   }
+   ```
 
 <Accordions>
   <Accordion title="What if I'm not using the General Translation platform?">
@@ -418,17 +333,9 @@ Luckily, the `gtx-cli` tool has a `translate` command that can be used to automa
   </Accordion>
 </Accordions>
 
----
-
-## Summary
-
- * In this guide, we covered how to setup your Next.js app with `gt-next`
- * We briefly covered the different ways to translate content in your application.
- * We also covered how to deploy your application after you've internationalized your content.
-
-
 ## Next Steps
 
-- Learn about how to translate JSX content with the `<T>` component: [Translating JSX](/docs/next/guides/jsx)
-- Learn about how to translate strings with the `useGT` hook: [Translating Strings](/docs/next/guides/strings)
-- Learn how to use local translations: [Local Translations](/docs/next/guides/local-tx)
\ No newline at end of file
+- [`<T>` Component Guide](/docs/next/guides/t) - Deep dive into the [`<T>`](/docs/next/api/components/t) component and JSX translation
+- [String Translation Guide](/docs/next/guides/strings) - Using [`useGT()`](/docs/next/api/strings/useGT) and [`getGT()`](/docs/next/api/strings/getGT)  
+- [Variable Components](/docs/next/guides/variables) - Handle dynamic content with [`<Var>`](/docs/next/api/components/var), [`<Num>`](/docs/next/api/components/num), etc.
+- [Language Switching](/docs/next/guides/languages) - Let users change languages with [`<LocaleSelector>`](/docs/next/api/components/localeSelector)
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/platform/index.mdx b/apps/docs/content/docs/en/platform/index.mdx
index 241779ca7..5416cc48b 100644
--- a/apps/docs/content/docs/en/platform/index.mdx
+++ b/apps/docs/content/docs/en/platform/index.mdx
@@ -15,7 +15,7 @@ npx gtx-cli@latest
 
 General Translation is an entire internationalization (i18n) stack that allows you to ship multilingual apps quickly and easily.
 
-![Live translations in action](/live_translations.gif)
+<Video src="/demo.mp4" />
 
 General Translation includes the following:
 
diff --git a/apps/docs/content/docs/en/platform/locadex/deployment/editing-locales.mdx b/apps/docs/content/docs/en/platform/locadex/deployment/editing-locales.mdx
new file mode 100644
index 000000000..4e613ac53
--- /dev/null
+++ b/apps/docs/content/docs/en/platform/locadex/deployment/editing-locales.mdx
@@ -0,0 +1,16 @@
+---
+title: Editing Locales
+description: How to use Locadex to edit your project's locales
+---
+
+## Overview
+
+Navigate to the [Locadex](https://dash.generaltranslation.com/project/locadex) tab in your dashboard.
+
+If you haven't already, you'll need to have completed the locadex setup process, including merging the setup PR.
+
+Find the Deployment section, and press the "Edit" button as shown below:
+
+![Deployment section](/locadex-screenshots/deployment/deployment-section-edit-button.png)
+
+A modal will open, allowing you edit the locales. 
diff --git a/apps/docs/content/docs/en/platform/locadex/guides/mintlify.mdx b/apps/docs/content/docs/en/platform/locadex/guides/mintlify.mdx
new file mode 100644
index 000000000..e57b44819
--- /dev/null
+++ b/apps/docs/content/docs/en/platform/locadex/guides/mintlify.mdx
@@ -0,0 +1,94 @@
+---
+title: Locadex for Mintlify
+description: Automate translation for your Mintlify docs
+---
+
+<div style={{ position: 'relative', width: '100%', paddingBottom: '56.25%', height: 0 }}>
+  <iframe
+    src="https://www.youtube.com/embed/kfxH4AP3AmI"
+    title="Locadex on Mintlify Demo"
+    style={{
+      position: 'absolute',
+      top: 0,
+      left: 0,
+      width: '100%',
+      height: '100%',
+      border: 0
+    }}
+    allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
+    allowFullScreen
+  ></iframe>
+</div>
+
+**Locadex is an AI agent built to handle 100% of internationalization (i18n) and translation work for you.**
+
+It takes 5 minutes to install, after which your Mintlify docs will be configured and translated into all the languages you choose automatically.
+
+Locadex:
+* Sets up i18n routing and redirects in your docs
+* Translates markdown files, code blocks, and snippets in context
+* Continuously translates as you push new content
+
+### Step 1: Sign into the General Translation Dashboard
+
+Sign into the General Translation [Dashboard](https://dash.generaltranslation.com).
+
+![Installation screen for Locadex](/locadex-screenshots/mintlify/1.png)
+
+### Step 2: Connect GitHub
+
+Navigate to the [Locadex](https://dash.generaltranslation.com) section in your dashboard and click "Connect GitHub".
+
+You'll be redirected to GitHub to authorize the connection.
+
+![Installation screen for Locadex](/locadex-screenshots/mintlify/2.png)
+
+### Step 3: Install the GitHub App
+
+Choose which repositories to give Locadex access to:
+
+![Installation screen for Locadex](/locadex-screenshots/mintlify/3.png)
+
+Click "Install" to complete the GitHub app installation.
+
+### Step 4: Link Repository to Project
+
+You'll be directed back to your General Translation project, where you can select the repository with your Mintlify docs.
+
+![Installation screen for Locadex](/locadex-screenshots/mintlify/4.png)
+
+### Step 5: Configure Settings
+
+On the configuration screen, set up:
+
+- **Which languages do you need?**: The languages you want the docs to be available in
+
+- **Default locale**: The language you originally wrote the docs in
+
+![Installation screen for Locadex](/locadex-screenshots/mintlify/5.png)
+
+### Step 6: Complete Installation
+
+Click "Install" to activate Locadex for your repository:
+
+![Installation screen for Locadex](/locadex-screenshots/mintlify/6.png)
+
+### Step 7: Review the PR
+
+Locadex will create a pull request on your main branch. This may take a few minutes to complete.
+
+![Installation screen for Locadex](/locadex-screenshots/mintlify/7.png)
+
+Review the PR and merge it to complete your i18n setup.
+
+### Step 8: Continuous internationalization
+
+After the initial setup PR is merged, Locadex monitors your main branch for commits and updates translations as needed.
+
+![Installation screen for Locadex](/locadex-screenshots/mintlify/8.png)
+
+### Supported frameworks
+
+Currently, Locadex only supports Mintlify and [Next.js App router](/docs/locadex) apps. 
+
+[Get in touch](mailto:founders@generaltranslation.com) to request support for other frameworks.
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/platform/locadex/guides/next.mdx b/apps/docs/content/docs/en/platform/locadex/guides/next.mdx
new file mode 100644
index 000000000..82a94c699
--- /dev/null
+++ b/apps/docs/content/docs/en/platform/locadex/guides/next.mdx
@@ -0,0 +1,117 @@
+---
+title: Locadex for Next.js App Router
+description: Automate translation for your Next.js app
+---
+
+Translating your Next.js app into French 🇫🇷, Spanish 🇪🇸, Japanese 🇯🇵, or any other language is painful and time-consuming.
+
+**Locadex is an AI agent built to handle 100% of the internationalization (i18n) work for you.**
+It takes 5 minutes to install.
+
+![Installation screen for Locadex](/screenshots/locadex-install.png)
+
+Locadex:
+* Configures your project to use the gt-next i18n library
+* Modifies your React components and strings to support multilingual content
+* Translates your app into as many languages as you need
+* Continuously internationalizes and translates as you push new content
+
+## Setup Process
+
+### Step 1: Sign into the General Translation Dashboard
+
+Go to your [Dashboard](https://dash.generaltranslation.com) and sign in to your account.
+
+### Step 2: Connect GitHub
+
+1. Navigate to the GitHub integration section in your dashboard
+2. Click "Connect GitHub" to link your GitHub account
+3. You'll be redirected to GitHub to authorize the connection
+
+### Step 3: Install the GitHub App
+
+1. After connecting GitHub, you'll be redirected to install the Locadex GitHub app
+2. Choose which repositories to give Locadex access to:
+   - Install on all repositories, or
+   - Select specific repositories
+3. Click "Install" to complete the GitHub app installation
+
+### Step 4: Link Repository to Project
+
+1. Back in your GT dashboard, select the repository you want to internationalize
+2. This connects your repo to your translation settings and target languages
+3. Only one repository can be linked to a project, but you can create multiple projects, each with a different repository
+
+### Step 5: Configure Settings
+
+On the configuration screen, set up:
+
+- **Target Languages**: Choose which locales to translate into
+
+![Locadex installation screen](/locadex-screenshots/locadex-installation.png)
+
+### Step 6: Complete Installation
+
+1. Review your configuration settings
+2. Click "Install" to activate Locadex for your repository
+3. You'll be taken to an overview page showing your connected GitHub repository
+
+## What Happens Next
+
+### Initial Setup
+
+Once you complete the installation:
+
+1. **Immediate PR Creation**: Locadex will create a pull request on your main branch
+2. **Full Setup**: This PR runs the complete Locadex setup command that:
+   - Installs the GT libraries
+   - Configures your project for internationalization
+   - Sets up the translation infrastructure
+3. **Review & Merge**: Review the PR and merge it to complete your i18n setup
+
+### Continuous internationalization
+
+After the initial setup is merged:
+
+1. Locadex monitors your main or specified branch for pull requests
+2. When you push new code with translatable content, wait for Locadex to add its commit to the PR
+3. Once Locadex commits to the PR, it is safe to merge -- your new code is internationalized
+4. Your app stays translated without manual intervention
+
+## Monitoring Your Repository
+
+![Locadex GitHub connection panel](/locadex-screenshots/locadex-github-connection.png)
+
+![Locadex config panel](/locadex-screenshots/locadex-config.png)
+
+
+### Dashboard Status
+
+In the dashboard, you can monitor:
+
+- **Repository Status**: Active monitoring indicator
+- **Configuration**: Current settings and target languages
+
+### GitHub Integration
+
+- **Status Checks**: Locadex adds status updates to pull requests
+- **Check Runs**: GitHub shows Locadex processing status
+
+
+## Troubleshooting
+
+### Common Issues
+
+**Locadex not creating PRs**
+- Verify the GitHub app has repository access
+- Check that commits contain translatable content
+
+**Configuration changes needed**
+- Update branch settings in your GT dashboard
+- Changes apply to new commits after the update
+
+## Supported frameworks
+
+Currently, Locadex only supports Next.js App router apps. 
+
+Request support for other frameworks [here](https://github.com/generaltranslation/gt/issues/new?assignees=&labels=enhancement&projects=&template=feature_request.md&title=Locadex+Feature+Request%3A+%5BFramework%5D).
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/platform/locadex/index.mdx b/apps/docs/content/docs/en/platform/locadex/index.mdx
new file mode 100644
index 000000000..e5f544faf
--- /dev/null
+++ b/apps/docs/content/docs/en/platform/locadex/index.mdx
@@ -0,0 +1,12 @@
+---
+title: Locadex — AI i18n engineer
+description: Get started with Locadex, an automated internationalization engineer
+---
+
+**Locadex is an AI agent built to handle 100% of internationalization (i18n) and translation work for you.**
+
+It takes 5 minutes to install, after which your project will be configured and translated into all the languages you choose automatically.
+
+See guides for:
+- [Mintlify](/docs/locadex/mintlify)
+- [Next.js App Router](/docs/locadex/next)
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/platform/locadex/monorepos.mdx b/apps/docs/content/docs/en/platform/locadex/monorepos.mdx
new file mode 100644
index 000000000..7fbe46881
--- /dev/null
+++ b/apps/docs/content/docs/en/platform/locadex/monorepos.mdx
@@ -0,0 +1,14 @@
+---
+title: Monorepo Support
+description: How to use Locadex on a Next.js app within a monorepo
+---
+
+To use Locadex with a monorepo, specify your app directory on the dashboard in the Locadex settings.
+
+### On initial installation
+
+![Locadex installation screen with the App Root Directory input highlighted](/locadex-screenshots/locadex-installation-highlight-filepath.png)
+
+### For continuous internationalization
+
+![Locadex config screen with the App Root Directory input highlighted](/locadex-screenshots/locadex-config-highlight-filepath.png)
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/platform/meta.json b/apps/docs/content/docs/en/platform/meta.json
index a0dfab111..1d7f31cd6 100644
--- a/apps/docs/content/docs/en/platform/meta.json
+++ b/apps/docs/content/docs/en/platform/meta.json
@@ -1,7 +1,7 @@
 {
   "title": "General Translation",
   "description": "Platform",
-  "icon": "House",
+  "icon": "Globe",
   "root": true,
   "pages": [
     "---Getting Started---",
diff --git a/apps/docs/content/docs/en/react/concepts/stand-alone.mdx b/apps/docs/content/docs/en/react/concepts/stand-alone.mdx
index 9678fc0d8..02a8b7374 100644
--- a/apps/docs/content/docs/en/react/concepts/stand-alone.mdx
+++ b/apps/docs/content/docs/en/react/concepts/stand-alone.mdx
@@ -27,6 +27,8 @@ Make sure you load your translated dictionaries with the [`loadDictionary()`](/d
 
 ---
 
+### Manual string translation
+
 If your project is using inline translations with the [`<T>`](/docs/react/guides/jsx) component
 or the [`useGT()`](/docs/react/guides/strings) functions,
 you'll also need to manually translate your strings.
diff --git a/apps/docs/content/docs/en/react/config.mdx b/apps/docs/content/docs/en/react/config.mdx
new file mode 100644
index 000000000..24498011d
--- /dev/null
+++ b/apps/docs/content/docs/en/react/config.mdx
@@ -0,0 +1,59 @@
+---
+title: Configuration
+description: A guide on the gt.config.json file
+---
+
+## Overview
+
+The `gt.config.json` file is used to configure your project's GT settings. It should be placed in the root of your project.
+
+The CLI setup wizard [`npx gtx-cli init`](/docs/cli/init) will create a `gt.config.json` file for you in your project.
+
+## Configuration
+
+The three most important properties are:
+
+- `defaultLocale`: The default locale for your project. This is the locale that your source content is written in. This is also the fallback locale for your project.
+
+- `locales`: An array of locales for your project. These are the locales that you want to translate your project into. See the [supported locales](/docs/platform/locale-strings#supported-locales) for more information. 
+If you are using `gt-next` or `gt-react`, these are also the locales that your app supports.
+
+- `files`: While optional for react component translation, this field contains information about the files you want to translate. See the [files](/docs/cli/reference/config#files) section for more information.
+
+## Examples
+
+Here is an example of a `gt.config.json` file:
+
+```json title="gt.config.json"
+{
+  "defaultLocale": "en",
+  "locales": ["fr", "es"],
+  "files": {
+    "json": {
+      "include": ["public/locales/[locale].json"]
+    }
+  }
+}
+```
+
+This will translate the `public/locales/en.json` file to `public/locales/fr.json` and `public/locales/es.json`.
+
+<Files>
+  <Folder name="app">
+    <File name="layout.js" />
+    <File name="page.js" />
+  </Folder>
+  <Folder name="public" defaultOpen={true}>
+    <Folder name="locales" defaultOpen={true}>
+      <File name="en.json" />
+      <File name="fr.json" />
+      <File name="es.json" />
+    </Folder>
+  </Folder>
+  <File name="gt.config.json" />
+  <File name="package.json" />
+</Files>
+
+## Next Steps
+
+Learn how to use the [init command](/docs/cli/init) to generate this configuration file.
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/react/guides/branches.mdx b/apps/docs/content/docs/en/react/guides/branches.mdx
index 58789059e..d4f87b948 100644
--- a/apps/docs/content/docs/en/react/guides/branches.mdx
+++ b/apps/docs/content/docs/en/react/guides/branches.mdx
@@ -1,341 +1,329 @@
 ---
-title: Using Branches
-description: How to use branch components
+title: Branching Components
+description: How to use branching components for conditional content within translations
 ---
 
-## Overview
-
-Branching components in `gt-react` enable dynamic content rendering based on specific conditions. These components include:
-
-- [`<Branch>`](/docs/react/api/components/branch): Renders content based on a matching `branch` prop.
-- [`<Plural>`](/docs/react/api/components/plural): Renders content based on pluralization rules for a given number.
-
-Both components provide powerful tools for managing conditional logic and dynamic content in localized applications.
-
-In this guide, we will cover:
-<Steps>
-  <Step>
-    What are branch components?
-  </Step>
-  <Step>
-    How to use branch components
-  </Step>
-  <Step>
-    When to use branch components
-  </Step>
-  <Step>
-    Examples
-  </Step>
-  <Step>
-    Common pitfalls
-  </Step>
-</Steps>
+Branching components enable conditional content rendering within [`<T>`](/docs/react/api/components/t) components. They handle dynamic logic like if/else statements and pluralization rules while ensuring all content variations can be properly translated.
 
----
-
-## What are branch components?
-
-Branch components dynamically choose which content to render based on a specific condition or value.
-
-### `<Branch>`
+## Available Components
 
-The `<Branch>` component allows you to render different content based on a provided `branch` value.
-If no matching branch is found, the fallback `children` content is rendered.
+- [`<Branch>`](/docs/react/api/components/branch): Conditional content based on values or states
+- [`<Plural>`](/docs/react/api/components/plural): Automatic pluralization using locale-specific rules
 
-For example, the `<Branch>` component is perfect for conditional rendering based on application state, user preferences, or any dynamic data.
+## Quick Start
 
-The most common use case is to use it to replace a ternary or conditional operator.
+Branching components work inside [`<T>`](/docs/react/api/components/t) to handle conditional logic:
 
-### `<Plural>`
+```jsx
+import { T, Branch, Plural, Num, Var } from 'gt-react';
 
-The `<Plural>` component extends the functionality of `<Branch>` by handling pluralization and number agreement automatically.
-It uses the provided `n` value to determine which plural form to display, based on locale-specific rules.
-
-For example, the `<Plural>` component is ideal for rendering singular and plural text dynamically, such as "1 item" vs. "2 items."
-
-Plural components are often combined with `<Num>` components to localize a number and its corresponding text.
-
-### Use with `<T>`
+function NotificationPanel({ user, messageCount }) {
+  return (
+    <T>
+      <Branch 
+        branch={user.status}
+        online={<p><Var>{user.name}</Var> is currently online</p>}
+        away={<p><Var>{user.name}</Var> is away</p>}
+      >
+        <p><Var>{user.name}</Var> status unknown</p>
+      </Branch>
+      
+      <Plural
+        n={messageCount}
+        one={<p>You have <Num>{messageCount}</Num> message</p>}
+        other={<p>You have <Num>{messageCount}</Num> messages</p>}
+      />
+    </T>
+  );
+}
+```
 
-The `<Branch>` and `<Plural>` components should be used within a [`<T>`](/docs/react/guides/jsx) component to sanitize dynamic content for translation.
+## How Branching Components Work
 
-When used within a `<T>` component, the content is automatically translated and rendered in your user's selected language.
+Branching components solve conditional rendering within translations by:
 
-When used standalone, they will just render the content as-is, without translating it.
+1. **Replacing ternary operators** and conditional logic inside [`<T>`](/docs/react/api/components/t)
+2. **Providing fallback content** when conditions don't match expected values
+3. **Enabling translation** of all possible content variations
+4. **Following locale rules** for pluralization automatically
 
----
+```jsx
+// ❌ This breaks - conditional logic in <T>
+<T><p>{isActive ? 'User is active' : 'User is inactive'}</p></T>
 
-## How to use branch components
+// ✅ This works - conditional logic with branching
+<T>
+  <Branch 
+    branch={isActive} 
+    true={<p>User is active</p>}
+    false={<p>User is inactive</p>}
+  />
+</T>
+```
 
-### Branching logic with `<Branch>`
+## Component Guide
 
-The `<Branch>` component is used for flexible content switching based on a `branch` value.
+### `<Branch>` - Conditional Content
 
-You can define multiple possible branches, and the component will render the content corresponding to the matching branch key.
+Use [`<Branch>`](/docs/react/api/components/branch) for any conditional rendering based on values or states:
 
-Additionally, you can use other variable components in combination with the `<Branch>` component.
+```jsx
+// User status display
+<T>
+  <Branch 
+    branch={user.role}
+    admin={<p>Administrator Dashboard</p>}
+    user={<p>User Dashboard</p>}
+    guest={<p>Guest Access</p>}
+  >
+    <p>Access level unknown</p>
+  </Branch>
+</T>
 
-```tsx 
-const branch: 'option1' | 'option2' = 'option1';
+// Boolean conditions
 <T>
   <Branch 
-    branch={branch}
-    option1={<p>Option 1</p>}
-    option2={<p>Option 2</p>}
+    branch={isLoggedIn}
+    true={<p>Welcome back!</p>}
+    false={<p>Please log in</p>}
+  />
+</T>
+
+// Subscription tiers
+<T>
+  <Branch
+    branch={subscription.tier}
+    free={<p>Upgrade to unlock premium features</p>}
+    premium={<p>Enjoy your premium experience</p>}
+    enterprise={<p>Contact support for enterprise solutions</p>}
   >
-    Fallback content
+    <p>Subscription status unavailable</p>
   </Branch>
 </T>
 ```
 
-The `<Branch>` component should be used within a `<T>` component. This allows for the content to be automatically translated.
+### `<Plural>` - Smart Pluralization
 
-See the [API Reference](/docs/react/api/components/branch) for more details.
+Use [`<Plural>`](/docs/react/api/components/plural) for content that changes based on quantity:
 
-### Pluralization with `<Plural>` [#plural-logic]
+```jsx
+// Basic pluralization
+<T>
+  <Plural
+    n={itemCount}
+    one={<p><Num>{itemCount}</Num> item in cart</p>}
+    other={<p><Num>{itemCount}</Num> items in cart</p>}
+  />
+</T>
 
-The `<Plural>` component automates pluralization logic based on the value of `n`.
-The component dynamically chooses the appropriate plural form for the given number and locale.
+// Zero handling
+<T>
+  <Plural
+    n={notifications}
+    zero={<p>No new notifications</p>}
+    one={<p><Num>{notifications}</Num> notification</p>}
+    other={<p><Num>{notifications}</Num> notifications</p>}
+  />
+</T>
 
-```tsx copy
-const count: number = 1;
+// Complex pluralization (follows Unicode CLDR rules)
 <T>
   <Plural
-    n={count}
-    singular={<><Num>{1}</Num> item.</>}
-    plural={<><Num>{count}</Num> items.</>}
-    // Additional options
-    zero={<><Num>{count}</Num> items.</>}
-    one={<><Num>{count}</Num> item.</>}
-    two={<><Num>{count}</Num> items.</>}
-    few={<><Num>{count}</Num> items.</>}
-    many={<><Num>{count}</Num> items.</>}
-    other={<><Num>{count}</Num> items.</>}
-    dual={<><Num>{count}</Num> items.</>}
+    n={days}
+    zero={<p>Due today</p>}
+    one={<p>Due in <Num>{days}</Num> day</p>}
+    few={<p>Due in <Num>{days}</Num> days</p>}
+    many={<p>Due in <Num>{days}</Num> days</p>}
+    other={<p>Due in <Num>{days}</Num> days</p>}
   />
 </T>
 ```
 
-The available plural forms depend on the locale and follow [Unicode CLDR pluralization rules](https://cldr.unicode.org/index/cldr-spec/plural-rules).
-
-See the [API Reference](/docs/react/api/components/plural) for more details.
-
----
+### Combining with Variable Components
 
-## When to use branch components
-
-Branch components are important for managing dynamic content in your application.
-
-When you need to display different content based on a condition, use `<Branch>`.
-
-These conditions can be based on a variable component, a boolean, or a function.
-
-For example, if your code has a ternary operator or conditional rendering, you can use `<Branch>` to replace it.
-
-<Tabs items={["Result", "Original"]}>
-  <Tab value="Result">
-    ```tsx
-    const isActive = true;
-    // Ternary operator
-    <Branch branch={isActive} true={<p>The user is active.</p>} false={<p>The user is inactive.</p>}>
-      <p>Status unknown.</p>
-    </Branch>
-
-    // Conditional rendering
-    <Branch branch={isActive} true={<p>The user is active.</p>}>
-      <></>
-    </Branch>
-    ```
-  </Tab>
-  <Tab value="Original">
-    ```tsx
-    // Ternary operator
-    const isActive = true;
-    {isActive ? <p>The user is active.</p> : <p>The user is inactive.</p>}
-
-    // Conditional rendering
-    {isActive && <p>The user is active.</p>}
-    ```
-  </Tab>
-</Tabs>
-
-If you want to render content with correct pluralization, use `<Plural>`.
-
-<Tabs items={["Result", "Original"]}>
-  <Tab value="Result">
-    ```tsx
-    const count = 1;
-    <Plural n={count} one={<p>1 item</p>} other={<p>{count} items</p>} />
-    ```
-  </Tab>
-  <Tab value="Original">
-    ```tsx
-    const count = 1;
-    {count === 1 ? <p>1 item</p> : <p>{count} items</p>}
-    ```
-  </Tab>
-</Tabs>
+Branching and variable components work together seamlessly:
 
-<Callout>
-  The `<Branch>` and `<Plural>` components can be used standalone, without a `<T>` component.
-  When used standalone, they will just render the content as-is, without translating it.
-
-  However, they are often used within a [`<T>`](/docs/react/guides/jsx) component to sanitize dynamic content for translation.
-</Callout>
-
-
----
+```jsx
+<T>
+  <Branch
+    branch={order.status}
+    pending={
+      <p>
+        Order <Var>{order.id}</Var> is pending. 
+        Total: <Currency currency="USD">{order.total}</Currency>
+      </p>
+    }
+    shipped={
+      <p>
+        Order <Var>{order.id}</Var> shipped on <DateTime>{order.shippedDate}</DateTime>
+      </p>
+    }
+    delivered={
+      <p>Order <Var>{order.id}</Var> was delivered successfully</p>
+    }
+  >
+    <p>Order status unknown</p>
+  </Branch>
+</T>
+```
 
-## Examples
+## When to Use Branching Components
 
-### `<Branch>`
+### Replace Ternary Operators
+Convert conditional logic for use within [`<T>`](/docs/react/api/components/t):
 
-```tsx copy
-import { T, Branch, Var } from 'gt-react';
+```jsx
+// ❌ Can't use ternary in <T>
+<T>{isActive ? <p>Active user</p> : <p>Inactive user</p>}</T>
 
-export default function UserStatus() {
-  const [status, setStatus] = useState<'active' | 'inactive' | undefined>(undefined);
-  const [name, setName] = useState<string>('John Doe');
-  return (
-    <T>
-      <Branch
-        branch={status}
-        active={<p>The user <Var>{name}</Var> is active.</p>}
-        inactive={<p>The user <Var>{name}</Var> is inactive.</p>}
-      >
-        <p>Status unknown.</p>
-      </Branch>
-    </T>
-  );
-}
+// ✅ Use Branch instead
+<T>
+  <Branch 
+    branch={isActive}
+    true={<p>Active user</p>}
+    false={<p>Inactive user</p>}
+  />
+</T>
 ```
-In the example above, the `<Branch>` component dynamically switches between 3 rendered contents based on the value of `status`.
 
-When `status` is `"active"`, the component renders:
-```tsx
-<p>The user <Var>{name}</Var> is active.</p>
-```
+### Handle Multiple Conditions
+Replace switch statements or multiple if/else conditions:
 
-When `status` is `"inactive"`, the component renders:
-```tsx
-<p>The user <Var>{name}</Var> is inactive.</p>
-```
+```jsx
+// ❌ Complex conditional logic
+<T>
+  {status === 'loading' ? <p>Loading...</p> : 
+   status === 'error' ? <p>Error occurred</p> : 
+   status === 'success' ? <p>Success!</p> : 
+   <p>Unknown status</p>}
+</T>
 
-When `status` is neither `"active"` nor `"inactive"`, the component renders the fallback content:
-```tsx
-<p>Status unknown.</p>
+// ✅ Clean branching logic
+<T>
+  <Branch
+    branch={status}
+    loading={<p>Loading...</p>}
+    error={<p>Error occurred</p>}
+    success={<p>Success!</p>}
+  >
+    <p>Unknown status</p>
+  </Branch>
+</T>
 ```
 
-Since the `<Branch>` component is wrapped in a `<T>` component, the rendered content is automatically translated in context.
-
+### Pluralization Rules
+Replace manual plural handling:
 
-In this example, it displays different descriptions based on the user's subscription plan.
-```tsx copy
-import { Branch } from 'gt-react';
+```jsx
+// ❌ Manual pluralization
+<T>{count === 1 ? <p>1 item</p> : <p>{count} items</p>}</T>
 
-export default function SubscriptionDetails() {
-  const [plan, setPlan] = useState<'free' | 'premium' | 'enterprise' | undefined>(undefined);
-  return (
-    <Branch
-      branch={plan}
-      free={<p>You are on the Free plan. Upgrade to unlock more features!</p>}
-      premium={<p>You are enjoying the Premium plan with full access to features.</p>}
-      enterprise={<p>You are on the Enterprise plan. Contact support for tailored solutions.</p>}
-    >
-      <p>No subscription plan detected.</p>
-    </Branch>
-  );
-}
+// ✅ Automatic pluralization
+<T>
+  <Plural
+    n={count}
+    one={<p><Num>{count}</Num> item</p>}
+    other={<p><Num>{count}</Num> items</p>}
+  />
+</T>
 ```
 
- * The `branch` prop determines which plan message to display.
- * If `plan` is `"free"`, `"premium"`, or `"enterprise"`, the corresponding message is shown.
- * If `plan` doesn't match any of these values, the fallback content (`"No subscription plan detected."`) is displayed.
-
+## Standalone Usage
 
-### `<Plural>`
+Branching components can be used outside [`<T>`](/docs/react/api/components/t) for pure logic without translation:
 
-The `<Plural>` component dynamically handles singular and plural content based on the value of `n`.
-This example displays the number of unread messages in a user's inbox.
+```jsx
+// Pure conditional rendering
+<Branch
+  branch={theme}
+  dark={<DarkModeIcon />}
+  light={<LightModeIcon />}
+>
+  <DefaultIcon />
+</Branch>
 
-```tsx copy
-import { T, Plural, Num } from 'gt-react';
-
-export default function UnreadMessages() {
-  const [unreadCount, setUnreadCount] = useState<number>(1);
-  return (
-    <T>
-      <Plural
-        n={unreadCount}
-        one={<>You have <Num>{unreadCount}</Num> unread message.</>}
-        other={<>You have <Num>{unreadCount}</Num> unread messages.</>}
-      />
-    </T>
-  );
-}
+// Pure pluralization
+<Plural
+  n={count}
+  one={<SingleItemComponent />}
+  other={<MultipleItemsComponent />}
+/>
 ```
- * The `n` prop specifies the number of unread messages.
- * If `unreadCount` is `1`, the component renders: `"You have 1 unread message."`
- * For any other value, it renders: `"You have X unread messages."` where `X` is the value of `unreadCount` formatted by `<Num>`.
 
----
-
-## Common Pitfalls
+## Common Issues
 
-### Missing Branch Values [#missing-branch]
+### Missing Branch Keys
+Always provide fallback content for unmatched values:
 
-If a branch value is not provided or does not match any keys, the `<Branch>` component will render the fallback children content.
-Always ensure that the possible branch keys match the values passed to the branch prop.
-
-```tsx copy
-import { Branch } from 'gt-react';
+```jsx
+// ❌ No fallback for unexpected values
+<Branch
+  branch={userRole}
+  admin={<AdminPanel />}
+  user={<UserPanel />}
+  // What if userRole is "moderator"?
+/>
 
-export default function StatusMessage({ status }) {
-  return (
-    <Branch
-      branch={status}
-      active={<p>The user is active.</p>}
-      inactive={<p>The user is inactive.</p>}
-    >
-      <p>Status unknown.</p>
-    </Branch>
-  );
-}
+// ✅ Always include fallback
+<Branch
+  branch={userRole}
+  admin={<AdminPanel />}
+  user={<UserPanel />}
+>
+  <DefaultPanel /> {/* Fallback for any other value */}
+</Branch>
 ```
-If `status` is `undefined` or a value other than `active` or `inactive`, the fallback content `“Status unknown.”` will be displayed.
 
+### Incomplete Plural Forms
+Provide necessary plural forms for your default locale:
 
-### Missing Plural Forms [#plural-locale]
-
-Remember to specify all necessary plural forms in your default language.
-This is how `gt-react` ensures that your application always has fallback content to display.
-
-For example, if English is your default language, you should provide all plural forms for English.
-
-```tsx copy
-import { Plural, Num } from 'gt-react';
+```jsx
+// ❌ Missing "other" form
+<Plural
+  n={count}
+  one={<p>1 item</p>}
+  // What about 0, 2, 3, etc.?
+/>
 
+// ✅ Include required forms
 <Plural
   n={count}
-  one={<>You have <Num>{count}</Num> unread message.</>}
-  other={<>You have <Num>{count}</Num> unread messages.</>}
+  zero={<p>No items</p>}
+  one={<p>1 item</p>}
+  other={<p>{count} items</p>}
 />
 ```
 
-Here, we have provided `one` and `other` plural forms for English.
-
-Alternatively, you can also provide `singular` and `plural` for English.
+### Complex Nested Logic
+Although this works, we recommend keeping branching logic simple and avoid deep nesting:
 
+```jsx
+// ❌ Complex nested branching
+<Branch branch={status}>
+  <Branch branch={subStatus}>
+    {/* Hard to read and maintain */}
+  </Branch>
+</Branch>
+
+// ✅ Flatten logic or use multiple components
+<Branch
+  branch={`${status}-${subStatus}`}
+  active-online={<ActiveOnline />}
+  active-offline={<ActiveOffline />}
+  inactive-online={<InactiveOnline />}
+>
+  <DefaultState />
+</Branch>
+```
 
----
-
-## Notes
- * Branch components are essential for managing dynamic and localized content in applications.
- * The `<Branch>` component is highly flexible and can adapt to various conditions and states.
- * The `<Plural>` component simplifies pluralization by adhering to locale-specific rules automatically.
- * Always include a fallback `children` prop for better error handling and user experience.
+<Callout>
+  Learn more about pluralization rules in the [Unicode CLDR documentation](https://cldr.unicode.org/index/cldr-spec/plural-rules).
+</Callout>
 
 ## Next Steps
- * Check out [`<Branch>`](/docs/react/api/components/branch) and [`<Plural>`](/docs/react/api/components/plural) in the API Reference for more details.
- * Learn more about pluralization rules and branching logic in [Unicode CLDR Pluralization Rules](https://cldr.unicode.org/index/cldr-spec/plural-rules).
- * Explore how to use [Variable Components](/docs/react/guides/variables).
\ No newline at end of file
+
+- [String Translation Guide](/docs/react/guides/strings) - Translate plain text without JSX
+- [Dynamic Content Guide](/docs/react/guides/dynamic-content) - Handle runtime translation
+- API References:
+  - [`<Branch>` Component](/docs/react/api/components/branch)
+  - [`<Plural>` Component](/docs/react/api/components/plural)
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/react/guides/dictionaries.mdx b/apps/docs/content/docs/en/react/guides/dictionaries.mdx
index 0225bfef3..a63fde778 100644
--- a/apps/docs/content/docs/en/react/guides/dictionaries.mdx
+++ b/apps/docs/content/docs/en/react/guides/dictionaries.mdx
@@ -1,120 +1,91 @@
 ---
 title: Dictionaries
-description: How to use dictionaries
+description: How to use traditional dictionary-based translation patterns
 ---
 
-## Overview
-
-In this guide, we will introduce you to dictionaries.
-Please feel free to skip around this page as needed.
-We will cover the following:
-
-<Steps>
-  <Step>
-    What is a dictionary?
-  </Step>
-  <Step>
-    How to use dictionaries
-  </Step>
-  <Step>
-    Loading dictionaries for other languages
-  </Step>
-  <Step>
-    Using dictionaries
-  </Step>
-  <Step>
-    Production considerations
-  </Step>
-</Steps>
+Dictionaries provide a traditional approach to organizing translations in nested objects with key-value pairs. While [`<T>` components](/docs/react/guides/t) are the recommended approach, dictionaries can be useful for migration from other i18n libraries or when you prefer centralized translation storage.
 
 <Callout>
-  **Note:** We do not recommend using dictionaries if you are using `gt-react`. Instead, please check out the [`<T>`](/docs/react/api/components/t) component.
-
-  This guide is intended for those who are already familiar with dictionaries and want to learn how to use them with `gt-react`, or those who are 
-  trying to migrate from another i18n library to `gt-react`.
+  **Recommendation:** Use [`<T>` components](/docs/react/guides/t) for new projects. Dictionaries are supported primarily for migration and compatibility with existing translation workflows.
 </Callout>
 
----
-
-## What is a dictionary?
-
-A dictionary is a nested object with string values that can be used to store translatable content.
-They can be stored in a `.ts`, `.js`, or `.json` file.
-
-`gt-react` allows you to use dictionaries standalone, or in conjunction with [`<T>`](/docs/react/api/components/t) components.
-
-### Dictionary vs `<T>` Components
-
-The dictionary pattern has a few advantages over the [`<T>`](/docs/react/api/components/t) component:
+## Dictionary vs Component Translation
 
-1. **Centralized Storage**: Dictionaries store all translatable content in a single file.
-2. **Historical Precedent**: The dictionary pattern is a common design pattern in the industry and is used by many other i18n libraries.
-
-At the same time, it has several major disadvantages:
-
-1. **Complexity**: Dictionaries are more complex to set up and use than the `<T>` component.
-2. **Readability**: Dictionaries are less readable than the `<T>` component because the content is not inline.
-3. **Maintainability**: Dictionaries are more difficult to maintain than the `<T>` component because the content is not inline, and is instead stored separately. 
-This makes maintaining and updating translations much more difficult.
-4. **Debuggability**: For the same reason, dictionaries are more difficult to debug than the `<T>` component.
-When trying to debug a React component, you will have to track down where the content in the dictionary is being used, rather than just directly searching your codebase.
-
-Both design patterns are supported by our library and are not mutually exclusive.
-You can use a dictionary alongside `<T>` components.
-
-### Our advice
-
-We recommend using the [`<T>`](/docs/react/api/components/t) component because of its simplicity especially if you are new to internationalization (i18n).
-We offer dictionary support for those who prefer this design pattern from past experiences or for ease of integration with existing code bases.
+### Dictionary Pattern
+```tsx
+// dictionary.ts
+export default {
+  greetings: {
+    hello: 'Hello, world!',
+    welcome: 'Welcome, {name}!'
+  }
+};
 
----
+// Component usage
+function MyComponent() {
+  const d = useTranslations();
+  return <div>{d('greetings.hello')}</div>;
+}
+```
 
-## How to use dictionaries
+### Component Pattern  
+```tsx
+// Direct component usage - recommended
+function MyComponent() {
+  return <T><div>Hello, world!</div></T>;
+}
+```
 
-In this section, we will show you how to set up a bare-bones dictionary implementation in your React application.
-We will walk through the following steps:
+## Trade-offs
 
-<Steps>
-    <Step>
-        Create a dictionary
-    </Step>
-    <Step>
-        Reference the dictionary
-    </Step>
-</Steps>
+### Dictionary Advantages
+- **Centralized storage** - All translations in one place
+- **Industry standard** - Familiar pattern from other i18n libraries
+- **Migration friendly** - Easy to port existing translations
 
-### Step 1: Create a dictionary
+### Dictionary Disadvantages  
+- **Complexity** - More setup and configuration required
+- **Maintainability** - Content separated from usage makes updates harder
+- **Debuggability** - Harder to trace translations back to components
+- **Readability** - Keys don't show actual content
 
-The first step is to create a dictionary.
-This is a `dictionary.[js|ts|json]` file that contains all the content you want to translate.
+## Quick Start
 
-Add the following content to your `dictionary` file:
+### Step 1: Create Dictionary
+Create a dictionary file in your project root or `src` directory:
 
-```ts title="src/dictionary.ts" copy
+```ts title="dictionary.ts"
 const dictionary = {
   greetings: {
-    hello: 'Hello, world!'
+    hello: 'Hello, world!',
+    welcome: 'Welcome to our app!'
   },
-}
+  navigation: {
+    home: 'Home',
+    about: 'About',
+    contact: 'Contact'
+  }
+};
 
 export default dictionary;
 ```
 
-<Callout>
-  You can also use a `dictionary.json` file to store your dictionary. This is useful if you are migrating from a different library or if you prefer to use JSON files.
-  Here is an example of a `dictionary.json` file:
-
-```json title="src/dictionary.json" copy
+Or use JSON format:
+```json title="dictionary.json"
 {
   "greetings": {
-    "hello": "Hello, world!"
+    "hello": "Hello, world!",
+    "welcome": "Welcome to our app!"
+  },
+  "navigation": {
+    "home": "Home", 
+    "about": "About",
+    "contact": "Contact"
   }
 }
-``` 
-
-</Callout>
+```
 
-Then you pass it to your `<GTProvider>` component:
+Then you pass it to your [`<GTProvider>`](/docs/react/api/components/gtprovider) component:
 
 ```jsx title="index.js" copy
 import dictionary from "./dictionary.js";
@@ -130,150 +101,226 @@ createRoot(document.getElementById("root")!).render(
 );
 ```
 
-### Step 2: Reference the dictionary
+### Step 2: Use in Components
 
-You can access dictionary entries with the [`useTranslations()`](/docs/react/api/dictionary/useTranslations) hook.
-Just use the function returned by the hook to access the dictionary entries by key.
+The [`useTranslations()`](/docs/react/api/dictionary/useTranslations) hook lets you access dictionary entries:
 
-```tsx title="src/components/MyComponent.tsx" copy
+```tsx
 import { useTranslations } from 'gt-react';
 
-export default function MyComponent() {
+function MyComponent() {
   const d = useTranslations();
+  
   return (
     <div>
-      {d('greetings.hello')}
+      <h1>{d('greetings.hello')}</h1>
+      <p>{d('greetings.welcome')}</p>
     </div>
   );
 }
 ```
 
----
-
-## Loading dictionaries for other languages [#other-languages]
-
-By default, developers only provide a dictionary for the default language.
-
-General Translation automatically generates dictionaries for other languages and loads them with the [`loadTranslations`](/docs/react/api/config/load-translations) function.
-
-However, if you are migrating from another i18n library or already have dictionaries for other languages, you can pass them to the [`loadDictionary`](/docs/react/api/config/load-dictionary) function.
-
-`gt-react` will automatically load the corresponding dictionary for the requested locale when using the `useTranslations()` hook or `getDict()` function.
-
-See the [API Reference](/docs/react/api/config/load-dictionary) for more information.
-
----
-
-## Using dictionaries [#usage]
+## Using Variables
 
-### Variables
+Add variables to dictionary entries using `{variable}` syntax:
 
-You can add variables to your dictionary by using the `{variable}` syntax:
-
-```ts title="src/dictionary.ts" copy
+```ts title="dictionary.ts"
 const dictionary = {
-  greetings: {
-    hello: 'Hello, {name}!',    // -> Hello, Alice!
-    goodbye: 'Goodbye, {name}!' // -> Goodbye, Bob!
-  },
-}
-export default dictionary;
+  user: {
+    greeting: 'Hello, {name}!',
+    itemCount: 'You have {count} items',
+    orderTotal: 'Total: ${amount}'
+  }
+};
 ```
-```tsx title="src/components/MyComponent.tsx" copy
-import { useTranslations } from 'gt-react';
 
-export default async function MyComponent() {
+```tsx
+function UserDashboard() {
   const d = useTranslations();
+  
   return (
     <div>
-      {d('greetings.hello', { name: 'Alice' })}
-      {d('greetings.goodbye', { name: 'Bob' })}
+      <h1>{d('user.greeting', { name: 'Alice' })}</h1>
+      <p>{d('user.itemCount', { count: 5 })}</p>
+      <p>{d('user.orderTotal', { amount: 99.99 })}</p>
     </div>
   );
 }
 ```
 
-Read more about adding variables to your dictionary in the [`DictionaryTranslationOptions` type](/docs/react/api/types/DictionaryTranslationOptions).
-
-Dictionary strings in `gt-react` support ICU message format, which allows you to also format your variables.
-
+## Using Prefixes
 
+Scope dictionary access to specific sections using prefixes:
 
-### Prefixes
-
-Additionally, with [`useTranslations()`](/docs/react/api/dictionary/useTranslations), you can pass in a prefix to the function to specify a shared path in the dictionary.
-This is useful if you have a shared path in your dictionary that you want to use in multiple components.
-
-```jsx title="src/dictionary.js" copy
+```ts title="dictionary.ts"
 const dictionary = {
-  greetings: {
-    common: {
-      hello: 'Hello, world!',
-      goodbye: 'Goodbye, world!'
+  dashboard: {
+    header: {
+      welcome: 'Welcome back!',
+      lastLogin: 'Last login: {date}'
     },
-  },
-}
-export default dictionary;
+    stats: {
+      totalUsers: 'Total Users: {count}',
+      activeUsers: 'Active Users: {count}'
+    }
+  }
+};
 ```
 
-```jsx title="src/components/MyComponent.js" copy
-import { useTranslations } from 'gt-react';
-
-export default async function MyComponent() {
-  // All translation paths such as 'hello' will be prefixed with 'greetings.common.'
-  const d = useTranslations('greetings.common'); // [!code highlight]
+```tsx
+function DashboardHeader() {
+  // Prefix limits access to 'dashboard.header'
+  const d = useTranslations('dashboard.header');
+  
+  return (
+    <header>
+      <h1>{d('welcome')}</h1> {/* -> dashboard.header.welcome */}
+      <p>{d('lastLogin', { date: 'Today' })}</p> {/* -> dashboard.header.lastLogin */}
+    </header>
+  );
+}
 
+function DashboardStats() {
+  // Different prefix for stats section
+  const d = useTranslations('dashboard.stats');
+  
   return (
     <div>
-      {d('hello')} {/* hello -> greetings.common.hello */}
-      {d('goodbye')} {/* goodbye -> greetings.common.goodbye */}
+      <p>{d('totalUsers', { count: 1000 })}</p> {/* -> dashboard.stats.totalUsers */}
+      <p>{d('activeUsers', { count: 150 })}</p> {/* -> dashboard.stats.activeUsers */}
     </div>
   );
 }
 ```
 
----
-
-## Production considerations
+## Multiple Language Support
 
-### Deploying to production
+### Automatic Translation (Recommended)
+Most users should use [`loadTranslations()`](/docs/react/api/config/load-translations) to automatically generate translations from your base dictionary:
 
-Make sure to run the translate command before deploying to production, so that all translations are available at runtime.
-We recommend adding it to your in your CD pipeline or as a part of your build script.
-```json title="package.json" copy
-{
-  "scripts": {
-    "build": "npx gtx-cli translate && <YOUR_BUILD_COMMAND>",
+```ts title="dictionary.ts"  
+const dictionary = {
+  common: {
+    save: 'Save',
+    cancel: 'Cancel',
+    delete: 'Delete'
+  },
+  forms: {
+    required: 'This field is required',
+    email: 'Please enter a valid email'
   }
+};
+
+export default dictionary;
+```
+
+Then create a `loadTranslations()` function to load generated translation files:
+
+```ts title="src/loadTranslations.ts"
+export default async function loadTranslations(locale: string) {
+  const translations = await import(`./_gt/${locale}.json`);
+  return translations.default;
 }
 ```
 
-For a more detailed guide on deploying your application, please refer to the [Deployment](/docs/react/tutorials/quickdeploy) guide.
-For more information on the command, please refer to the [CLI Tool](/docs/cli/translate) reference guide.
+Pass it to your `<GTProvider>`:
+
+```tsx title="src/index.tsx"
+import loadTranslations from './loadTranslations';
+import dictionary from './dictionary';
+
+createRoot(document.getElementById("root")!).render(
+  <StrictMode>
+    <GTProvider 
+      {...config} 
+      dictionary={dictionary}
+      loadTranslations={loadTranslations}
+    >
+      <App />
+    </GTProvider>
+  </StrictMode>
+);
+```
 
-### Behavior: Development vs Production
+GT automatically generates translations for other languages based on your base dictionary. Run `npx gtx-cli translate` to generate translations for all configured languages.
 
-In development, the function returned by the `useTranslations()` hook will translate dictionary entries on-demand.
-This means that when the component is rendered, it will perform a translation immediately.
-We do this for convenience to make development with other languages easier.
+### Manual Translation Files (Migration)
+For migration from other i18n libraries or manual translation management, use [`loadDictionary`](/docs/react/api/config/load-dictionary):
 
-To enable this behavior, just add a [Dev API key](/docs/react/concepts/environments) to your environment.
+```ts title="src/loadDictionary.ts"
+export default async function loadDictionary(locale: string) {
+  const translations = await import(`../public/locales/${locale}.json`);
+  return translations.default;
+}
+```
 
-In production, the `d()` function will translate content at build time.
-This means that you have to run the translation command before deploying your application.
+This loads JSON translation files from your `public/locales/` directory:
+
+<Files>
+  <Folder name="my-app" defaultOpen={true}>
+    <Folder name="public" defaultOpen={true}>
+      <Folder name="locales" defaultOpen={true}>
+        <File name="es.json" />
+        <File name="fr.json" />
+        <File name="de.json" />
+      </Folder>
+    </Folder>
+    <Folder name="src">
+      <File name="loadDictionary.ts" />
+    </Folder>
+  </Folder>
+</Files>
 
 <Callout>
-  **Tip:**
-  If you want to simulate production behavior in development, just use a production API key in your development build.
+  **Choose the right approach:** Use [`loadTranslations()`](/docs/react/api/config/load-translations) for new projects with automatic translation generation, or [`loadDictionary()`](/docs/react/api/config/load-dictionary) when migrating existing translation files.
 </Callout>
 
----
+## Production Setup
+
+### Build Process
+Add translation to your build pipeline:
+
+```json title="package.json"
+{
+  "scripts": {
+    "build": "npx gtx-cli translate && <...YOUR_BUILD_COMMAND...>"
+  }
+}
+```
+
+### Development vs Production Behavior
+- **Development**: Dictionary entries translated on-demand with dev API key
+- **Production**: All dictionary translations pre-built during build step
+
+## Combining with Components
+
+Dictionaries and [`<T>` components](/docs/react/guides/t) can work together:
+
+```tsx
+function MixedApproach() {
+  const d = useTranslations();
+  
+  return (
+    <div>
+      {/* Dictionary for simple strings */}
+      <h1>{d('page.title')}</h1>
+      
+      {/* T component for complex JSX */}
+      <T>
+        <p>This is a <strong>complex message</strong> with <a href="/link">links</a>.</p>
+      </T>
+      
+      {/* Dictionary for form labels */}
+      <label>{d('forms.email')}</label>
+    </div>
+  );
+}
+```
 
-## Notes
- * Dictionaries are an alternative to the `<T>` component. They can be used in conjunction with `<T>` components or standalone.
- * Dictionary translations occur at build time, so you have to add the [`translate`](/docs/cli/translate) command to your build process.
- * Dictionaries can be used with prefixes to specify a subset of the dictionary.
+## Next Steps
 
-## Next steps
- * Learn about the [`<T>` component](/docs/react/api/components/t) and how to use it in your React application.
- * Learn how to ship to production with our [deployment guide](/docs/react/tutorials/quickdeploy).
\ No newline at end of file
+- [Languages Guide](/docs/react/guides/languages) - Configure supported languages and locale settings
+- [Dynamic Content Guide](/docs/react/guides/dynamic-content) - Handle runtime translation needs
+- API References:
+  - [`useTranslations()` Hook](/docs/react/api/dictionary/useTranslations)
+  - [`loadDictionary()` Function](/docs/react/api/config/load-dictionary)
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/react/guides/jsx.mdx b/apps/docs/content/docs/en/react/guides/jsx.mdx
deleted file mode 100644
index acf856683..000000000
--- a/apps/docs/content/docs/en/react/guides/jsx.mdx
+++ /dev/null
@@ -1,423 +0,0 @@
----
-title: Translating JSX
-description: How to internationalize JSX components
----
-
-## Overview
-
-This guide will walk you through how to use the [`<T>` component](/docs/react/api/components/t) to internationalize JSX content.
-
-By the end of this guide, you will know the correct syntax for using the `<T>` component and what to avoid.
-
-We will cover the following:
-<Steps>
-  <Step>
-    How to use the `<T>` component
-  </Step>
-  <Step>
-    Additional options
-  </Step>
-  <Step>
-    When to use the `<T>` component
-  </Step>
-  <Step>
-    Examples
-  </Step>
-  <Step>
-    Production considerations
-  </Step>
-  <Step>
-    Common pitfalls
-  </Step>
-</Steps>
-
-
-If you are looking for how to use [Variable Components](/docs/react/guides/variables) or [Branching Components](/docs/react/guides/branches), please refer to their respective guides.
-
----
-
-## How to use the `<T>` component
-
-Let's say you have some HTML content that you want to translate. 
-
-```jsx
-function Greeting() {
-  return <p>Hello, world!</p>;
-}
-```
-
-All you have to do is wrap the content in a `<T>` component.
-
-```jsx
-import { T } from 'gt-react';
-
-function Greeting() {
-  return <T><p>Hello, world!</p></T>;
-}
-```
-
-Depending on the current language your user has selected, this will render the appropriate translation. 
-See [switching languages](/docs/react/guides/languages) for more information on how to allow your users to switch languages.
-
----
-
-## Additional Options
-
-### Context
-
-In some cases, you may want to provide additional context to the translation.
-This can be done by passing a `context` prop to the `<T>` component.
-
-```jsx
-<T context="toast, as in a pop-up notification">
-  Click on the toast to dismiss it.
-</T>
-```
-
-This is useful in cases where words may have multiple meanings depending on the context.
-For example, "toast" can refer to the food or a pop-up notification.
-
-The context prop is helpful for the AI to understand the intent of the translation.
-
-### `id`
-
-You can also pass an `id` prop to the `<T>` component.
-This is useful for debugging purposes and makes editing the translation easier.
-
-```jsx
-<T id="toast">
-  Click on the toast to dismiss it.
-</T>
-```
-
----
-
-## When to use the `<T>` component
-
-While the `<T>` component is very flexible, it is not always the best solution.
-
-You should always try to use the `<T>` component when you have any **static HTML or JSX content.**
-
-### When not to use the `<T>` component
-
-**DO NOT** use the `<T>` component when you have any unsafe **dynamic** content.
-
-Here, dynamic content means any content that could change at runtime. 
-This rule does not apply if you are using [Variable Components](/docs/react/guides/variables) or [Branching Components](/docs/react/guides/branches).
-
-<Callout>
-  **Note:**
-  
-  Variable components are a special case where the content is dynamic, but the content has been wrapped and sanitized, so it is safe to use the `<T>` component.
-
-  Content wrapped in variable components are never translated directly by the `<T>` component.
-</Callout>
-
-
-The following examples show invalid usage of the `<T>` component:
-
-```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>
-```
-
-<Callout>
-  In the above examples, the content can be safely internationalized using [variable components](/docs/react/guides/variables) and [branching components](/docs/react/guides/branches).
-</Callout>
-
-```jsx
-const chatMessage = getChatMessageFromServer();
-<T>
-  <p>{chatMessage}</p>
-</T>
-```
-
-<Callout>
-  In this example, the content is fully dynamic, so it should be translated on the server side before being passed to the client.
-
-  See the [core](/docs/core) library for more information on how to dynamically translate content via our API.
-</Callout>
-
----
-
-## Examples
-
-Here are some examples of how to use the `<T>` component. These are all correct.
-
-1. HTML content
-<Tabs items={['Result', 'Original']}>
-  <Tab value="Result">
-```jsx
-<T>
-  <p>Hello, world!</p>
-</T>
-```
-  </Tab>
-  <Tab value="Original">
-    ```jsx
-    <p>Hello, world!</p>
-    ```
-  </Tab>
-</Tabs>
-
-2. Simple JSX content
-<Tabs items={['Result', 'Original']}>
-  <Tab value="Result">
-```jsx
-<T>
-  <Button>Click me!</Button>
-</T>
-```
-  </Tab>
-  <Tab value="Original">
-    ```jsx
-    <Button>Click me!</Button>
-    ```
-  </Tab>
-</Tabs>
-
-3. Complex JSX content
-<Tabs items={['Result', 'Original']}>
-  <Tab value="Result">
-```jsx
-<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>
-```
-  </Tab>
-  <Tab value="Original">
-    ```jsx
-    <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>
-    ```
-  </Tab>
-  </Tabs>
-
-
-
-
-
-
-<Callout>
-  The `<T>` component can handle any nested content in the same component.
-</Callout>
-
----
-
-## Production Considerations [#production]
-
-
-### Deploying to production
-
-Make sure to run the translate command before deploying to production, so that all translations are available at runtime.
-We recommend adding it to your CD pipeline or as a part of your build script.
-```json title="package.json" copy
-{
-  "scripts": {
-    "build": "npx gtx-cli translate && <YOUR_BUILD_COMMAND>",
-  }
-}
-```
-
-For a more detailed guide on deploying your application, please refer to the [Deployment](/docs/react/tutorials/quickdeploy) tutorial.
-For more information on the command, please refer to the [CLI Tool](/docs/cli/translate) reference guide.
-
-### Behavior: Development vs Production
-
-In development, the `<T>` component will translate content on-demand.
-This means that when the component is rendered, it will perform a translation immediately.
-The library does this for convenience to make development with other languages easier.
-
-To enable this behavior, just add a Dev API key to your environment.
-
-In production, all translations that the `<T>` component uses are completed at build time.
-This means that you have to run the translation command before deploying your application.
-
-<Callout>
-  **Tip:**
-  If you want to simulate production behavior in development, just use a production API key in your development build.
-</Callout>
-
-### Privacy Concerns
-
-With some exceptions, all content wrapped in a `<T>` component is sent to the General Translation API for translation.
-This might not be desirable for rendering sensitive data, such as usernames, account numbers, etc.
-
-To circumvent this issue, use [Variable Components](/docs/react/guides/variables#privacy) to handle private information.
-This ensures that no sensitive data is sent to the General Translation API for translation.
-Localization of any content wrapped in a variable component is handled locally.
-
----
-
-## Common Pitfalls
-
-
-### Direct descendants only [#direct-text]
-
-The `<T>` component only translates text passed directly as a child.
-This means that if you have content inside a component that is not directly passed to `<T>`, it will not be translated.
-
-Let's illustrate this with an example:
-
-```jsx copy
-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>
-  );
-}
-```
-
-In this example, the content inside `<UntranslatedContent>` will not be translated.
-Only the content directly inside `<T>` will be translated, like the `<h1>` tag and its children.
-
-<Accordions>
-  <Accordion title="Why does this happen?">
-    This occurs because of how React renders components.
-    It is a bit complicated, but the gist is that React does not know the content of a component until it has rendered.
-    Therefore, the contents of components like `<UntranslatedContent>` are not translated.
-    However, any text directly between the two `<T>` tags will be translated.
-  </Accordion>
-</Accordions>
-<Callout>
-  **Note:** A good rule of thumb is that any content that is *literally* between the two `<T>` tags in the file will be translated.
-  You can always add another `<T>` to translate the content that is not being translated, though nesting `<T>` components is not recommended.
-</Callout>
-
-#### What's the fix?
-
-Wrap the text in the `<T>` component directly, like so:
-
-```jsx copy
-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 [#nested-t]
-
-Nesting `<T>` components is not allowed.
-Because of React's rendering system, this can lead to unexpected behavior and performance issues.
-
-Here is an example of **what not to do**:
-
-```jsx copy
-function SomeComponent() {
-  return (
-    <T>
-      Hello, friend!
-    </T>
-  );
-}
-
-export default function NestedTranslation() {
-  return (
-    <T>
-      <T> {/* Don't do this! */} 
-        Hello, world! 
-      </T>
-      <SomeComponent /> {/* This still counts. Don't do this! */}
-    </T>
-  );
-}
-```
-
-The solution here is to remove the outtermost `<T>` component.
-
-### Translating dynamic content
-
-If you attempt to wrap dynamic content with the `<T>` component, the CLI tool will error.
-
-For example, the following will error:
-
-```jsx
-const username = 'John Doe';
-<T>
-  <p>Your username is {username}</p>
-</T>
-```
-
-To get around this, try to use [Variable Components](/docs/react/guides/variables) or [Branching Components](/docs/react/guides/branches) to wrap the dynamic content.
-
----
-
-## Summary
- * `<T>` components are used to internationalize arbitrary JSX Content.
- * `<T>` components should not be used for dynamic content, without using variable components or branching components.
- * In development, the `<T>` component will translate content on-demand.
- * In production, all translations that the `<T>` component uses are completed at build time.
-
-## Next Steps
- * Read about the [API](/docs/react/api/components/t) for the `<T>` component.
- * Explore [Variable Components](/docs/react/guides/variables) and [Branching Components](/docs/react/guides/branches).
- * Learn about [translating strings](/docs/react/guides/strings).
-
diff --git a/apps/docs/content/docs/en/react/guides/languages.mdx b/apps/docs/content/docs/en/react/guides/languages.mdx
index 6910aa5f9..b7c285f51 100644
--- a/apps/docs/content/docs/en/react/guides/languages.mdx
+++ b/apps/docs/content/docs/en/react/guides/languages.mdx
@@ -1,28 +1,23 @@
 ---
 title: Changing Languages
-description: How to change the language of your React app
+description: How to configure and switch between languages in your React app
 ---
 
-## Overview
+Language switching allows users to change their preferred locale for your application's content. GT React provides several approaches from simple programmatic switching to pre-built UI components for custom language selectors.
 
-In this guide, we'll show you how to change the language of your React app.
+## Available Methods
 
-If you have not yet setup your app with `gt-react`, please refer to the [quickstart guide](/docs/react) before continuing.
+- **Programmatic**: [`useSetLocale()`](/docs/react/api/helpers/useSetLocale) hook for custom controls
+- **Pre-built UI**: [`<LocaleSelector>`](/docs/react/api/components/localeSelector) component with dropdown
+- **Custom UI**: [`useLocaleSelector()`](/docs/react/api/helpers/useLocaleSelector) hook for building custom selectors
 
-There are three ways to change the language of your app using `gt-react`.
+## Using the `useSetLocale()` hook
 
-1. Using the [`useSetLocale()`](/docs/react/api/helpers/useSetLocale) hook
-2. Using the [`<LocaleSelector>`](/docs/react/api/components/localeSelector) component
-3. Using the [`useLocaleSelector()`](/docs/react/api/helpers/useLocaleSelector) hook
-
-We'll cover all three methods in this guide.
-
-## Using the `useSetLocale` hook
-
-The `useSetLocale` hook is a client-side hook that allows you to change the language of your app. It must be used within a `GTProvider` component.
+The [`useSetLocale`](/docs/react/api/helpers/useSetLocale) hook allows you to change the language of your app:
 
 ```tsx
 import { useSetLocale } from 'gt-react';
+
 export default function MyComponent() {
   const setLocale = useSetLocale();
 
@@ -30,13 +25,11 @@ export default function MyComponent() {
 }
 ```
 
-Simply provide the locale you want to change to as the argument to the callback function returned by the `useSetLocale` hook.
+Simply provide the locale you want to change to as the argument to the function returned by the hook.
 
 ## Using the `<LocaleSelector>` component
 
-The `<LocaleSelector>` component is a client-side component that allows you to change the language of your app. It must be used within a `GTProvider` component.
-
-This is a bare-bones UI dropdown that displays all the locales you have enabled in your project, and allows users to select a different locale.
+The [`<LocaleSelector>`](/docs/react/api/components/localeSelector) component provides a ready-to-use dropdown that automatically shows all configured locales:
 
 ```tsx
 import { LocaleSelector } from 'gt-react';
@@ -46,66 +39,66 @@ export default function MyComponent() {
 }
 ```
 
-## Using the `useLocaleSelector` hook
-
-Alternatively, if you would like to create your own locale selector component, you can use the `useLocaleSelector` hook.
+This component automatically:
+- Shows all configured locales for your project
+- Displays locales in their native language names
+- Handles the switching logic
+- Maintains current selection state
 
-This hook returns the current locale, the list of locales your project supports, and the `useSetLocale` hook.
+## Using the `useLocaleSelector()` hook
 
-Here is an example of how to use the `useLocaleSelector` hook to create a custom locale selector component.
+If you want to build your own custom locale selector component, use [`useLocaleSelector()`](/docs/react/api/helpers/useLocaleSelector):
 
-```tsx copy
+```tsx
 import { useLocaleSelector } from 'gt-react';
 
-function capitalizeLanguageName(language: string): string {
-  if (!language) return '';
+function CustomLocaleSelector() {
+  const { 
+    locale,              // Current active locale (e.g., 'en', 'es')
+    locales,             // Array of locales your project supports ['en', 'es', 'fr']
+    setLocale,           // Function to change the locale: setLocale('es')
+    getLocaleProperties  // Function to get display info for a locale
+  } = useLocaleSelector();
+  
+  if (!locales?.length) return null;
+  
   return (
-    language.charAt(0).toUpperCase() +
-    (language.length > 1 ? language.slice(1) : '')
+    <select 
+      value={locale || ''} 
+      onChange={(e) => setLocale(e.target.value)}
+    >
+      {locales.map((loc) => {
+        const props = getLocaleProperties(loc);
+        return (
+          <option key={loc} value={loc}>
+            {props.nativeNameWithRegionCode} {/* e.g., "English (US)", "Español (ES)" */}
+          </option>
+        );
+      })}
+    </select>
   );
 }
+```
 
-export default function LocaleDropdown({ className }: { className?: string }) {
-  // Retrieve the locale, locales, and setLocale function
-  const { locale, locales, setLocale, getLocaleProperties } = useLocaleSelector();
+## Important Notes
 
-  // Helper function to get the display name of a locale
-  const getDisplayName = (locale: string) => {
-    return capitalizeLanguageName(
-      getLocaleProperties(locale).nativeNameWithRegionCode
-    );
-  };
+### GTProvider Requirement
+Language switching components must be used within a [`<GTProvider>`](/docs/react/api/components/gtprovider):
 
-  // If no locales are returned, just render nothing or handle gracefully
-  if (!locales || locales.length === 0 || !setLocale) {
-    return null;
-  }
+```tsx
+// ✅ Correct
+<GTProvider>
+  <LanguageSwitcher />
+</GTProvider>
 
-  return (
-    <Select onValueChange={setLocale} defaultValue={locale}>
-      <SelectTrigger>
-        <SelectValue placeholder='Select language' />
-      </SelectTrigger>
-      <SelectContent className='z-[200!important]' position='popper'>
-        <SelectGroup>
-          {!locale && <SelectItem value='' />}
-
-          {locales.map((locale) => (
-            <SelectItem key={locale} value={locale} suppressHydrationWarning>
-              {getDisplayName(locale)}
-            </SelectItem>
-          ))}
-        </SelectGroup>
-      </SelectContent>
-    </Select>
-  );
-}
+// ❌ Wrong - outside provider
+<LanguageSwitcher />
 ```
 
-See the [API reference](/docs/react/api/helpers/useLocaleSelector) for more information.
-
-## Next steps
+## Next Steps
 
-- Learn more about the [`useSetLocale`](/docs/react/api/helpers/useSetLocale) hook.
-- Learn more about the [`<LocaleSelector>`](/docs/react/api/components/localeSelector) component.
-- Learn more about the [`useLocaleSelector`](/docs/react/api/helpers/useLocaleSelector) hook.
+- [Dynamic Content Guide](/docs/react/guides/dynamic-content) - Runtime content translation  
+- API References:
+  - [`useSetLocale()` Hook](/docs/react/api/helpers/useSetLocale)
+  - [`<LocaleSelector>` Component](/docs/react/api/components/localeSelector)
+  - [`useLocaleSelector()` Hook](/docs/react/api/helpers/useLocaleSelector)
diff --git a/apps/docs/content/docs/en/react/guides/local-tx.mdx b/apps/docs/content/docs/en/react/guides/local-tx.mdx
index a10544c83..b40b33012 100644
--- a/apps/docs/content/docs/en/react/guides/local-tx.mdx
+++ b/apps/docs/content/docs/en/react/guides/local-tx.mdx
@@ -1,150 +1,153 @@
 ---
-title: Local Translations
-description: How to set up local translations for your React app
+title: Local Translation Storage
+description: Store translations in your app bundle instead of using a CDN
 ---
 
 ## What are local translations?
 
-Local translations are stored in your app's bundle, as opposed to being fetched from a CDN (Content Distribution Network).
-
-Let's say that you have added the [`gtx-cli translate`](/docs/cli/translate) command to your CD process.
-This will generate translations in JSON format for your app.
-The final step is to get these translations out of our API and into your app, where they can be used.
+Local translations are stored in your app's bundle, as opposed to being fetched from a CDN (Content Distribution Network). When you add the `gtx-cli translate` command to your build process, this generates translations in JSON format. The final step is getting these translations into your app where they can be used.
 
 There are two ways to do this:
- * **In your app's bundle:** After translations are generated, save them to your app's bundle.
- * **In a CDN (default):** Fetch translations from a CDN at runtime.
 
-By default, `gt-react` will fetch translations from the General Translation CDN, and when translating your app using our API, translations will be automatically saved to our CDN.
+1. **In your app's bundle** (local): Save translations to your app's bundle after generation
+2. **In a CDN** (default): Fetch translations from a CDN at runtime
+
+By default, `gt-react` fetches translations from the General Translation CDN. When translating your app using our API, translations are automatically saved to our CDN.
 
 <Callout>
-  In React, we especially recommend using the CDN option. Using a CDN will minimize the size of your app bundle.
+  **Default behavior:** GT uses CDN storage by default. Only switch to local storage if you need the specific benefits it provides.
 </Callout>
 
-## Overview
-
-This guide will show you how to store translations in your React app bundle, rather than using an external CDN, such as ours.
-This means that translations will live in your app bundle and avoids reliance on external infrastructure.
-
-In this guide, we will walk you through:
-
-<Steps>
-  <Step>
-    The trade-offs of using local translations.
-  </Step>
-  <Step>
-    How to set up local translations for your React app.
-  </Step>
-</Steps>
-
-
-
----
-
 ## Trade-offs
 
-### What are the benefits?
-
-1. **Faster load times:** Local translations are served directly from your app,
-meaning that they will load faster than translations served from a CDN.
-
-2. **No reliance on external services:** Your app's ability to load translations is not dependent on CDN uptime. 
-With `gt-react`, if translations are not found for a given locale, the app will automatically fall back to the default language and display the original content.
+### Benefits of Local Translations
+- **Faster load times**: Local translations are served directly from your app, loading faster than translations served from a CDN
+- **No reliance on external services**: Your app's ability to load translations isn't dependent on CDN uptime. If translations aren't found for a locale, the app automatically falls back to the default language
+- **Works offline**: Translations are bundled with your app
 
-### What are the drawbacks?
+### Drawbacks of Local Translations  
+- **Increased bundle size**: Local translations increase your app's bundle size, potentially making the app slower to load initially
+- **Content management**: To edit a translation, you must redeploy your app with the new translation every time you make changes
 
-1. **Increased bundle size:** Local translations will increase your app's bundle size as they will be served alongside your app.
-This means that your app may take longer to load on the client.
-
-2. **Content management:** If you want to edit a translation (i.e., you do not like how your content has been phrased in a different language),
-you must redeploy your app with the new translation every time you make changes.
-
----
 
 ## Setup
 
-### Prerequisites
-
-Make sure that you have already setup your React app with GT. 
-If not, please complete the [Quick Start Guide](/docs/react/tutorials/quickstart) or [Project Setup](/docs/react/guides/project-setup) first.
-
-
-### Steps
-<Steps>
-  <Step>
-    Add a `loadTranslations.[js|ts]` file under `./src` with the following content:
-
-    <Tabs items={['ts', 'js']}>
-      <Tab value="ts">
-        ```ts title="src/loadTranslations.ts" copy
-        export default async function loadTranslations(locale: string) {
-          const t = await import(`./_gt/${locale}.json`);
-          return t.default;
-        }
-        ```
-      </Tab>
-      <Tab value="js">
-        ```js title="src/loadTranslations.js" copy
-        export default async function loadTranslations(locale) {
-          const t = await import(`./_gt/${locale}.json`);
-          return t.default;
-        }
-        ```
-      </Tab>
-    </Tabs>
-  </Step>
-
-  <Step>
-    Pass `loadTranslations` as a prop to the `<GTProvider>` component.
-
-    ```tsx title="src/App.tsx" copy
-    import { GTProvider } from 'gt-react';
-    import loadTranslations from './loadTranslations'; // [!code highlight]
-
-    export default function App() {
-      return (
-        {/* [!code highlight] */}
-        <GTProvider loadTranslations={loadTranslations} locales={['es', 'fr']}>
-          <YourApp />
-        </GTProvider>
-      );
-    }
-    ```
-  </Step>
-
-  <Step>
-    Run the following command, and when asked if you want to save translations on the GT CDN, select the "No" option.
-    ```bash
-    npx gtx-cli configure
-    ```
-    Alternatively, you can manually configure the `gt.config.json` file to use local translations.
-    See the [CLI Configuration](/docs/cli/reference/config#gt) docs for more information.
-
-    Now, when you run the translate command, translations will be automatically downloaded and included in your codebase.
-    ```bash
-    npx gtx-cli translate
-    ```
-    The `loadTranslations` function will then be used to load these translations into your app.
-
-    <Callout type="warn">
-      Depending on the specific framework you are using, translation JSONs may not be automatically included in the
-      final bundle. Please refer to the documentation for your specific framework to ensure that the JSONs are included.
-    </Callout>
-  </Step>
-</Steps>
-
-That's it! Your app will now only load translations from your local files.
-
-### Further customization
-
-You can further customize the `loadTranslations` function to load translations from other sources, such as your database or your own CDN.
-See the [`loadTranslations()`](/docs/react/api/config/load-translations) docs for more information.
+### Step 1: Create Load Function
+Add a `loadTranslations.[js|ts]` file under `./src` with the following content:
+
+```ts title="src/loadTranslations.ts"
+export default async function loadTranslations(locale: string) {
+  const t = await import(`./_gt/${locale}.json`);
+  return t.default;
+}
+```
+
+### Step 2: Configure GTProvider
+Pass `loadTranslations` as a prop to the [`<GTProvider>`](/docs/react/api/config/provider) component:
+
+```tsx title="src/App.tsx"
+import { GTProvider } from 'gt-react';
+import loadTranslations from './loadTranslations';
+
+export default function App() {
+  return (
+    <GTProvider loadTranslations={loadTranslations} locales={['es', 'fr']}>
+      <YourApp />
+    </GTProvider>
+  );
+}
+```
+
+### Step 3: Configure CLI
+Run the configuration command and select local storage:
+
+```bash
+npx gtx-cli configure
+```
+
+When prompted:
+- **Save to CDN?** Select "No"  
+- **Translation directory:** The CLI will automatically use `./src/_gt`
+
+Alternatively, you can manually configure the `gt.config.json` file to use local translations. See the [CLI Configuration docs](/docs/cli/configuration) for more information.
+
+### Step 4: Generate Translations
+Now when you run the translate command, translations will be automatically downloaded and included in your codebase:
+
+```bash
+npx gtx-cli translate
+```
+
+Translations will be stored in `src/_gt/` and bundled with your app.
+
+## Build Integration
+
+### React Build Process
+Add translation generation to your build script:
+
+```json
+{
+  "scripts": {
+    "build": "npx gtx-cli translate && <...YOUR_BUILD_COMMAND...>"
+  }
+}
+```
+
+### CI/CD Pipeline
+```yaml
+# .github/workflows/deploy.yml
+- name: Generate Translations
+  run: npx gtx-cli translate
+  
+- name: Build Application  
+  run: npm run build
+```
+
+## Common Issues
+
+### Missing Translation Files
+Ensure translations are generated before building:
+
+```bash
+# ❌ Build without translations
+<...YOUR_BUILD_COMMAND...>
+
+# ✅ Generate translations first
+npx gtx-cli translate && <...YOUR_BUILD_COMMAND...>
+```
+
+### Import Path Errors
+Match your directory structure in the load function:
+
+```ts
+// ❌ Wrong path
+const t = await import(`../translations/${locale}.json`);
+
+// ✅ Correct path for src/_gt
+const t = await import(`./_gt/${locale}.json`);
+```
+
+### Large Bundle Size
+Consider code splitting for apps with many languages:
+
+```ts
+// Load translations only when needed
+export default async function loadTranslations(locale: string) {
+  // Only load if locale is active
+  if (locale === getCurrentLocale()) {
+    const translations = await import(`./_gt/${locale}.json`);
+    return translations.default;
+  }
+  return {};
+}
+```
 
----
+<Callout>
+  Local storage works best for apps with stable translations that don't need frequent updates.
+</Callout>
 
-## Notes
- * Local translations are an alternative to fetching translations from a CDN.
- * There are benefits and drawbacks to using local translations, which are discussed in the [Trade-offs](#trade-offs) section.
+## Next Steps
 
-## Next steps
- * See [`loadTranslations()`](/docs/react/api/config/load-translations) for more information on writing a custom translation loader.
\ No newline at end of file
+- [Languages Guide](/docs/react/guides/languages) - Configure supported languages
+- API References:
+  - [`loadTranslations()` Function](/docs/react/api/config/load-translations)
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/react/guides/migration.mdx b/apps/docs/content/docs/en/react/guides/migration.mdx
index 4dd09edf7..91d34700c 100644
--- a/apps/docs/content/docs/en/react/guides/migration.mdx
+++ b/apps/docs/content/docs/en/react/guides/migration.mdx
@@ -37,7 +37,7 @@ You'll never have to wait for translations again.
   <Tab value="npm">
   ```bash 
   npm i gt-react
-  npm i --save-dev gtx-cli
+  npm i gtx-cli
   ``` 
   </Tab>
   <Tab value="yarn">
diff --git a/apps/docs/content/docs/en/react/guides/shared-strings.mdx b/apps/docs/content/docs/en/react/guides/shared-strings.mdx
index d7993492e..d98cca058 100644
--- a/apps/docs/content/docs/en/react/guides/shared-strings.mdx
+++ b/apps/docs/content/docs/en/react/guides/shared-strings.mdx
@@ -1,443 +1,419 @@
 ---
-title: Translating Shared Strings
-description: How to internationalize shared strings
+title: Shared Strings
+description: How to internationalize strings used across multiple components and files
 ---
 
-## Overview
+Shared strings are text values used in multiple places throughout your application - like navigation labels, form messages, or configuration data. Instead of duplicating translation logic everywhere, use [`msg()`](/docs/react/api/strings/msg) to mark strings for translation and [`useMessages()`](/docs/react/api/strings/useMessages) to decode them.
 
-Shared strings are strings or constants that are used in multiple places in your app.
+## The Problem with Shared Content
 
-For example, you may have a string that is used in multiple components, or a constant that is used in multiple files.
+Consider this navigation configuration used across your app:
 
-In traditional i18n libraries, you would need to create a dictionary for each shared string.
-
-This guide will walk you through how to easily internationalize shared strings in your React app using the [`msg()`](/docs/react/api/strings/msg) function & [`useMessages()`](/docs/react/api/dictionary/useMessages) hook.
-
-We will cover the following:
-<Steps>
-  <Step>
-    When to use the `msg()` function
-  </Step>
-  <Step>
-    How to use the `msg()` function and `useMessages()` hook
-  </Step>
-  <Step>
-    Using variables
-  </Step>
-  <Step>
-    Examples
-  </Step>
-  <Step>
-    Common pitfalls
-  </Step>
-</Steps>
-
---- 
-
-## When to use the `msg()` function
-
-The `msg()` function is a simple function that is used to mark strings for translation.
-
-Let's look at an example of a shared object containing strings:
-
-```tsx title="src/navData.ts"
-export const navData = {
-  home: {
+```tsx
+// navData.ts
+export const navData = [
+  {
     label: 'Home',
     description: 'The home page',
-    icon: 'home',
-    href: '/',
+    href: '/'
   },
-  about: {
-    label: 'About',
+  {
+    label: 'About', 
     description: 'Information about the company',
-    icon: 'info',
-    href: '/about',
-  },
-}
-```
-
-Normally, to internationalize this object, you would need to either create a dictionary entry for each string, or refactor your object into a function that returns the data with translations.
-
-For example, you might have:
-```tsx title="src/navData.ts"
-export const getNavData = (t: (content: string) => string) => ({
-  home: {
-    label: t('Home'),
-    description: t('The home page'),
-    icon: 'home',
-    href: '/',
-  },
-  about: {
-    label: t('About'),
-    description: t('Information about the company'),
-    icon: 'info',
-    href: '/about',
-  },
-})
-```
-Everywhere else in your app where `navData` was imported, you would need to call `getNavData(t)` instead.
-
-```tsx title="src/app/page.tsx"
-import { getNavData } from '@/navData';
-
-export default function Home() {
-  const t = useGT();
-  const navData = getNavData(t);
-  return <div>{navData.home.label}</div>;
-}
+    href: '/about'
+  }
+];
 ```
 
-This can lead to a lot of work. The solution is to use the `msg()` function.
+To internationalize this, you'd typically need to:
+1. Convert it to a function that accepts a translation function
+2. Update every usage to call the function with `t`
+3. Manage the complexity across your codebase
 
----
+This creates maintenance overhead and makes your code harder to read. The [`msg()`](/docs/react/api/strings/msg) function solves this by letting you mark strings for translation in-place, then decode them when needed.
 
-## How to use the `msg()` function
+## Quick Start
 
-To use the `msg()` function, pass the string directly to the function.
-The function returns a special, encoded string that can be used for translations.
+Use [`msg()`](/docs/react/api/strings/msg) to mark strings and [`useMessages()`](/docs/react/api/strings/useMessages) to decode them:
 
-```tsx title="src/navData.ts"
+```tsx
+// navData.ts - Mark strings for translation
 import { msg } from 'gt-react';
 
 export const navData = [
   {
-    label: msg('Home'), // Output has type `string`
-    description: msg('The home page'),
-    icon: 'home',
-    href: '/',
+    label: msg('Home'),
+    description: msg('The home page'), 
+    href: '/'
   },
   {
     label: msg('About'),
     description: msg('Information about the company'),
-    icon: 'info',
-    href: '/about',
-  },
-]
+    href: '/about'
+  }
+];
 ```
 
-Then, simply pass the encoded string to the `useMessages()` hook.
-
-```tsx title="src/app/page.tsx"
+```tsx
+// Component usage - Decode marked strings
 import { useMessages } from 'gt-react';
-import { navData } from '@/navData';
+import { navData } from './navData';
 
-export default function Home() {
+function Navigation() {
   const m = useMessages();
+  
   return (
-    <div>
+    <nav>
       {navData.map((item) => (
-        <div key={item.label}>{m(item.label)}</div>
+        <a key={item.href} href={item.href} title={m(item.description)}>
+          {m(item.label)}
+        </a>
       ))}
-    </div>
+    </nav>
   );
 }
 ```
 
-<Callout type='warn'>
-  Beware! The string returned by the `msg()` function is encoded and will be different from the original input string.
-  If want to get back the original string, you need to decode it with [`decodeMsg()`](/docs/react/api/strings/msg#decodemsg)
+## How Shared Strings Work
+
+The shared string system works in two phases:
+
+1. **Mark Phase**: [`msg()`](/docs/react/api/strings/msg) encodes strings with translation metadata
+2. **Decode Phase**: [`useMessages()`](/docs/react/api/strings/useMessages) decodes and translates the strings
+
+```tsx
+// msg() encodes the string with metadata
+const encoded = msg('Hello, world!');
+console.log(encoded); // "Hello, world!:eyIkX2hhc2giOiJkMjA3MDliZGExNjNlZmM2In0="
+
+// useMessages() decodes and translates
+const m = useMessages();
+const translated = m(encoded); // "Hello, world!" in user's language
+```
+
+<Callout type="warn">
+  Encoded strings from [`msg()`](/docs/react/api/strings/msg) cannot be used directly - they must be decoded with [`useMessages()`](/docs/react/api/strings/useMessages).
 </Callout>
 
----
-## Using variables
+## Components
 
-If your string is a template string and contains variables, you can pass the variables to the `msg()` function.
+Use [`useMessages()`](/docs/react/api/strings/useMessages) hook:
 
-Simply change the `${}` notation in the template string to `{variable}`, and pass an object as the second argument to `msg()` with the variable name as the key.
+```tsx
+import { useMessages } from 'gt-react';
 
-```tsx title="src/navData.ts"
-const items = 100;
-export const pricing = [
-  {
-    name: 'Basic',
-    price: 100,
-    description: `The basic plan includes ${items} items`
-  },
-]
+const encodedString = msg('Hello, world!');
+
+function MyComponent() {
+  const m = useMessages();
+  return <div>{m(encodedString)}</div>;
+}
 ```
 
-Should be turned into:
+## Getting Original Strings with `decodeMsg()`
 
-```tsx title="src/navData.ts"
-import { msg } from 'gt-react';
+Sometimes you need to access the original string without translation, such as for logging, debugging, or comparisons. Use [`decodeMsg()`](/docs/react/api/strings/msg#decodemsg) to extract the original text:
+
+```tsx
+import { decodeMsg } from 'gt-react';
+
+const encoded = msg('Hello, world!');
+const original = decodeMsg(encoded); // "Hello, world!" (original)
+const translated = m(encoded); // "Hello, world!" (in user's language)
 
+// Useful for logging or debugging
+console.log('Original string:', decodeMsg(encoded));
+console.log('Translated string:', m(encoded));
+```
+
+### Use Cases for `decodeMsg()`
+
+- **Development & Debugging**: Log original strings for troubleshooting
+- **Fallback Handling**: Use original text when translations fail
+- **String Comparisons**: Compare against known original values
+- **Analytics**: Track original string usage
+
+```tsx
+// Example: Fallback handling
+function getDisplayText(encodedStr) {
+  const m = useMessages();
+  try {
+    return m(encodedStr);
+  } catch (error) {
+    console.warn('Translation failed, using original:', decodeMsg(encodedStr));
+    return decodeMsg(encodedStr);
+  }
+}
+```
+
+## Using Variables
+
+For strings with dynamic content, use placeholders and pass variables:
+
+```tsx
+// Mark string with variables
 const items = 100;
 export const pricing = [
   {
     name: 'Basic',
     price: 100,
     description: msg('The basic plan includes {items} items', { items })
-  },
-]
+  }
+];
 ```
 
-The `{items}` placeholder will be replaced with the value of the `items` variable.
-
-This allows you to display dynamic values in your translations.
-
-For more information on the API, see the [API reference](/docs/react/api/strings/msg).
+```tsx
+// Use in component
+function PricingCard() {
+  const m = useMessages();
+  
+  return (
+    <div>
+      <h3>{pricing[0].name}</h3>
+      <p>{m(pricing[0].description)}</p>
+    </div>
+  );
+}
+```
 
-`gt-react` supports ICU message format, which allows you to also format your variables.
+### ICU Message Format
+For advanced formatting, use ICU syntax:
 
-```jsx copy
-const price = 100;
-msg('There are {count, plural, =0 {no items} =1 {one item} other {{count} items}} in the cart', { count: 10 });
+```tsx
+const count = 10;
+const message = msg('There are {count, plural, =0 {no items} =1 {one item} other {{count} items}} in the cart', { count });
 ```
 
 <Callout>
-  ICU message format is a powerful way to format your variables.
-  For more information, see the [ICU message format documentation](https://unicode-org.github.io/icu/userguide/format_parse/messages/).
+  Learn more about ICU Message Format in the [Unicode documentation](https://unicode-org.github.io/icu/userguide/format_parse/messages/).
 </Callout>
 
-
----
-
 ## Examples
 
-1. Translating a shared global object
-
-<Tabs items={['Result', 'Original']}>
-  <Tab value="Result">
-```jsx copy title="src/llms.ts"
+### Navigation Configuration
+```tsx
+// config/navigation.ts
 import { msg } from 'gt-react';
 
-export const llmData = [
+export const mainNav = [
   {
-    name: 'GPT-4.1',
-    id: 'gpt-4.1',
-    description: msg('GPT-4.1 is a large language model developed by OpenAI'),
+    label: msg('Home'),
+    href: '/',
+    icon: 'home'
   },
   {
-    name: 'Claude 3.7 Sonnet',
-    id: 'claude-3-7-sonnet',
-    description: msg('Claude 3.7 Sonnet is a large language model developed by Anthropic'),
+    label: msg('Products'),
+    href: '/products', 
+    icon: 'package'
   },
+  {
+    label: msg('About Us'),
+    href: '/about',
+    icon: 'info'
+  }
 ];
-```
-
-```jsx copy title="src/app/page.tsx"
-import { llmData } from '@/llms';
-import { useMessages } from 'gt-react';
 
-export default function MyComponent() {
-  const m = useMessages();
-  return (
-    <div>
-      {llmData.map((llm) => (
-        <div key={llm.id}>
-          <h1>{llm.name}</h1>
-          <p>{m(llm.description)}</p>
-        </div>
-      ))}
-    </div>
-  )
-}
-```
-  </Tab>
-
-<Tab value="Original">
-```jsx copy title="src/llms.ts"
-export const llms = [
+export const footerLinks = [
   {
-    name: 'GPT-4.1',
-    id: 'gpt-4.1',
-    description: 'GPT-4.1 is a large language model developed by OpenAI',
+    title: msg('Company'),
+    links: [
+      { label: msg('About'), href: '/about' },
+      { label: msg('Careers'), href: '/careers' },
+      { label: msg('Contact'), href: '/contact' }
+    ]
   },
   {
-    name: 'Claude 3.7 Sonnet',
-    id: 'claude-3-7-sonnet',
-    description: 'Claude 3.7 Sonnet is a large language model developed by Anthropic',
-  },
-]
+    title: msg('Support'), 
+    links: [
+      { label: msg('Help Center'), href: '/help' },
+      { label: msg('Documentation'), href: '/docs' },
+      { label: msg('API Reference'), href: '/api' }
+    ]
+  }
+];
 ```
 
-```jsx copy title="src/app/page.tsx"
-import { llms } from '@/llms';
+```tsx
+// components/Navigation.tsx
+import { useMessages } from 'gt-react';
+import { mainNav } from '../config/navigation';
 
-export default function MyComponent() {
+function Navigation() {
+  const m = useMessages();
+  
   return (
-    <div>
-      {llms.map((llm) => (
-        <div key={llm.id}>
-          <h1>{llm.name}</h1>
-          <p>{llm.description}</p>
-        </div>
+    <nav>
+      {mainNav.map((item) => (
+        <a key={item.href} href={item.href}>
+          <Icon name={item.icon} />
+          {m(item.label)}
+        </a>
       ))}
-    </div>
-  )
+    </nav>
+  );
 }
 ```
-</Tab>
-</Tabs>
-
-2. Translating a function's return value
 
-<Tabs items={['Result', 'Original']}>
-  <Tab value="Result">
-```jsx copy title="src/llms.ts"
+### Form Configuration
+```tsx
+// config/forms.ts
 import { msg } from 'gt-react';
 
-function mockData() {
-  return [
-    {
-      name: 'GPT-4.1',
-      id: 'gpt-4.1',
-      company: 'OpenAI',
-    },
-    {
-      name: 'Claude 3.7 Sonnet',
-      id: 'claude-3-7-sonnet',
-      company: 'Anthropic',
-    },
-  ];
-}
-
-export function getData() {
-  const data = mockData();
-  const modifiedData = data.map((item) => ({
-    ...item,
-    description: msg('{name} is a large language model developed by {company}', {
-      name: item.name,
-      company: item.company,
-    }),
-  }));
-  return modifiedData;
-}
+export const formMessages = {
+  placeholders: {
+    email: msg('Enter your email address'),
+    password: msg('Enter your password'),
+    message: msg('Type your message here...')
+  },
+  actions: {
+    send: msg('Send Message'),
+    save: msg('Save Changes'),
+    cancel: msg('Cancel')
+  },
+  validation: {
+    required: msg('This field is required'),
+    email: msg('Please enter a valid email address'),
+    minLength: msg('Must be at least {min} characters', { min: 8 }),
+    maxLength: msg('Cannot exceed {max} characters', { max: 100 })
+  },
+  success: {
+    saved: msg('Changes saved successfully'),
+    sent: msg('Message sent successfully'),
+    updated: msg('Profile updated')
+  },
+  errors: {
+    network: msg('Network error - please try again'),
+    server: msg('Server error - please contact support'),
+    timeout: msg('Request timed out - please try again')
+  }
+};
 ```
 
-```jsx copy title="src/app/page.tsx"
-import { getData } from '@/llms';
+```tsx
+// components/ContactForm.tsx
 import { useMessages } from 'gt-react';
+import { formMessages } from '../config/forms';
 
-export default function MyComponent() {
+function ContactForm() {
   const m = useMessages();
-  const data = getData();
+  const [errors, setErrors] = useState({});
+  
   return (
-    <div>
-      {data.map((item) => (
-        <div key={item.id}>
-          <h1>{item.name}</h1>
-          <p>{m(item.description)}</p>
-        </div>
-      ))}
-    </div>
-  )
+    <form>
+      <input 
+        type="email"
+        placeholder={m(formMessages.placeholders.email)}
+        required
+      />
+      {errors.email && <span>{m(formMessages.validation.email)}</span>}
+      
+      <button type="submit">
+        {m(formMessages.actions.send)}
+      </button>
+    </form>
+  );
 }
 ```
-  </Tab>
 
-<Tab value="Original">
-```jsx copy title="src/llms.ts"
+### Dynamic Content Generation
+```tsx
+// utils/productData.ts
 import { msg } from 'gt-react';
 
-function mockData() {
+function mockProducts() {
   return [
-    {
-      name: 'GPT-4.1',
-      id: 'gpt-4.1',
-      company: 'OpenAI',
-    },
-    {
-      name: 'Claude 3.7 Sonnet',
-      id: 'claude-3-7-sonnet',
-      company: 'Anthropic',
-    },
+    { name: 'iPhone 15', company: 'Apple', category: 'Electronics' },
+    { name: 'Galaxy S24', company: 'Samsung', category: 'Electronics' }
   ];
 }
 
-export function getData() {
-  const data = mockData();
-  const modifiedData = data.map((item) => ({
-    ...item,
-    description: `${item.name} is a large language model developed by ${item.company}`,
+export function getProductData() {
+  const products = mockProducts();
+  
+  return products.map(product => ({
+    ...product,
+    description: msg('{name} is a {category} product by {company}', {
+      name: product.name,
+      category: product.category,
+      company: product.company
+    })
   }));
-  return modifiedData;
 }
 ```
 
-```jsx copy title="src/app/page.tsx"
-import { getData } from '@/llms';
+```tsx
+// components/ProductList.tsx
+import { useMessages } from 'gt-react';
+import { getProductData } from '../utils/productData';
 
-export default function MyComponent() {
-  const data = getData();
+function ProductList() {
+  const m = useMessages();
+  const products = getProductData();
+  
   return (
     <div>
-      {data.map((item) => (
-        <div key={item.id}>
-          <h1>{item.name}</h1>
-          <p>{item.description}</p>
+      {products.map(product => (
+        <div key={product.name}>
+          <h3>{product.name}</h3>
+          <p>{m(product.description)}</p>
         </div>
       ))}
     </div>
-  )
+  );
 }
 ```
-</Tab>
-</Tabs>
-
----
-
-## Common Pitfalls
 
-### Forgetting to call `useMessages()`
+## Common Issues
 
-`msg()` encodes the input string, so you cannot use it directly in JSX or elsewhere. 
+### Using Encoded Strings Directly
+Never use the output of [`msg()`](/docs/react/api/strings/msg) directly:
 
-If you attempt to use the encoded string directly, you will get a weird string that looks something like this:
+```tsx
+// ❌ Wrong - encoded string used directly
+const encoded = msg('Hello, world!');
+return <div>{encoded}</div>; // Shows encoded string, not translation
 
-```jsx
-const encodedString = msg('Hello, world!');
-console.log(encodedString); // "Hello, world!:eyIkX2hhc2giOiJkMjA3MDliZGExNjNlZmM2In0="
+// ✅ Correct - decode the string first  
+const encoded = msg('Hello, world!');
+const m = useMessages();
+return <div>{m(encoded)}</div>; // Shows proper translation
 ```
 
-To fix this, you need to use the `useMessages()` hook to get the translated string.
-
-```jsx
-import { useMessages } from 'gt-react';
+### Dynamic Content in msg()
+Strings must be known at build time:
 
-const encodedString = msg('Hello, world!');
+```tsx
+// ❌ Wrong - dynamic template literal
+const name = 'John';
+const message = msg(`Hello, ${name}`); // Build time error
 
-export default function MyComponent() {
-  const m = useMessages();
-  return <div>{m(encodedString)}</div>; // 'Hello, world!' in the current language
-}
+// ✅ Correct - use variables  
+const name = 'John';
+const message = msg('Hello, {name}', { name });
 ```
 
-Alternatively, if you want to recover the original string, you can use the `decodeMsg()` function.
-
-```jsx
-import { decodeMsg } from 'gt-react';
-
-const encodedString = msg('Hello, world!');
-const decodedString = decodeMsg(encodedString);
-console.log(decodedString); // "Hello, world!"
-```
-
-### Wrapping dynamic content in `msg()`
-
-All strings must be known at build time. This means that you cannot wrap dynamic content in `msg()`.
+### Forgetting to Decode
+Every [`msg()`](/docs/react/api/strings/msg) string needs to be decoded:
 
-For example, this is invalid:
+```tsx
+// ❌ Missing decoding
+const config = {
+  title: msg('Dashboard'),
+  subtitle: msg('Welcome back')
+};
 
-```jsx
-const dynamicContent = msg(`Hello, ${name}`);
-```
-
-To fix this, provide the dynamic content as a variable, and then pass it to `msg()`.
+// Later in component - forgot to decode
+return <h1>{config.title}</h1>; // Shows encoded string
 
-```jsx
-const dynamicContent = msg('Hello, {name}', { name });
+// ✅ Correct - decode when using
+const m = useMessages();
+return <h1>{m(config.title)}</h1>; // Shows translated title
 ```
 
-<Callout type="warn">
-  The CLI tool will warn you if you try to wrap dynamic content with `msg()`.
-</Callout>
-
-
----
-
 ## Next Steps
- * See the [API reference for `msg()`](/docs/react/api/strings/msg).
- * See the [API reference for `useMessages()`](/docs/react/api/dictionary/useMessages).
- * Learn more about the [`<T>` component](/docs/react/guides/jsx).
\ No newline at end of file
+
+- [Dictionaries Guide](/docs/react/guides/dictionaries) - Organize translations with structured data
+- [Languages Guide](/docs/react/guides/languages) - Configure supported languages
+- API References:
+  - [`msg()` Function](/docs/react/api/strings/msg)
+  - [`useMessages()` Hook](/docs/react/api/strings/useMessages)
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/react/guides/strings.mdx b/apps/docs/content/docs/en/react/guides/strings.mdx
index 447eb0d6a..9c8f44f0f 100644
--- a/apps/docs/content/docs/en/react/guides/strings.mdx
+++ b/apps/docs/content/docs/en/react/guides/strings.mdx
@@ -1,380 +1,297 @@
 ---
-title: Translating Strings
-description: How to internationalize strings
+title: Strings
+description: How to internationalize plain text strings using useGT
 ---
 
-## Overview
+String translation provides direct access to text translations without JSX, perfect for attributes, object properties, and plain text values. Use [`useGT()`](/docs/react/api/strings/useGT) in React components for string translation.
 
-This guide will walk you through how to internationalize strings in your React app using the `useGT()` hook.
+## Quick Start
 
-We will cover the following:
-<Steps>
-  <Step>
-    When to use the `useGT()` hook
-  </Step>
-  <Step>
-    How to use the `useGT()` hook
-  </Step>
-  <Step>
-    Using variables
-  </Step>
-  <Step>
-    Examples
-  </Step>
-  <Step>
-    Common pitfalls
-  </Step>
-</Steps>
+```jsx
+import { useGT } from 'gt-react';
+
+function MyComponent() {
+  const t = useGT();
+  return (
+    <input 
+      placeholder={t('Enter your email')}
+      title={t('Email address field')}
+    />
+  );
+}
+```
 
---- 
+## When to Use String Translation
 
-## When to use the `useGT()` hook
+String translation is ideal when you need plain text rather than JSX:
 
-The `useGT()` hook is a React hook that can be used to translate strings.
+### HTML Attributes
+```jsx
+const t = useGT();
 
-In most cases, you can use the [`<T>` component](/docs/react/guides/jsx).
-However, in cases where JSX is not appropriate, the `useGT()` hook can be used. 
+<input 
+  placeholder={t('Search products...')}
+  aria-label={t('Product search input')}
+  title={t('Type to search our catalog')}
+/>
+```
 
-Some cases where the `useGT()` hook could be more appropriate are:
-- In properties that expect strictly strings, such as `placeholder` or `title` attributes.
-- When the string is part of a larger object, for example:
+### Object Properties
+```jsx
+const t = useGT();
 
-```jsx copy
 const user = {
-  title: 'Mr.',
   name: 'John',
-  description: 'John is a software engineer at General Translation',
-}
+  role: 'admin',
+  bio: t('Experienced software developer with 5 years in React'),
+  status: t('Currently available for projects')
+};
 ```
-Here, only the `description` property should be translated.
-
-<Callout>
-  Wherever possible, you should use the [`<T>` component](/docs/react/guides/jsx).
-  The `<T>` component allows you to translate JSX content, and is the recommended way to translate strings.
-</Callout>
-
----
-
-## How to use the `useGT()` hook
-
-The `useGT()` hook has to be called within the [`<GTProvider>`](/docs/react/api/components/gtprovider).
-
-To translate a string, simply pass the string directly to the function returned by the hook.
 
+### Configuration & Constants
+```jsx
+const t = useGT();
 
-```jsx copy
-const translate = useGT();
-translate('Hello, world!');
+const navigationItems = [
+  { label: t('Home'), href: '/' },
+  { label: t('Products'), href: '/products' },
+  { label: t('Contact'), href: '/contact' }
+];
 ```
 
-<Callout>
-  Unlike traditional i18n libraries, the `useGT()` hook does not require you to pass a `key` to the function.
-  Instead, the string is passed directly to the function.
+### When to Use [`<T>`](/docs/react/api/components/t) Instead
+Use the [`<T>` component](/docs/react/guides/jsx) for JSX content:
 
-  This means that you don't need to use dictionaries!
-</Callout>
+```jsx
+// ✅ Use <T> for JSX content
+<T><p>Welcome to <strong>our store</strong>!</p></T>
 
-## Using variables
+// ✅ Use string translation for plain text
+<input placeholder={t('Search products')} />
+```
 
-Often, you will need to translate strings that contain variables.
+## Using Variables
 
-For example, you may need to translate a string that contains numerical values. 
+### Basic Variables
+Replace placeholders with dynamic values:
 
-To add variables, simply add the variable to the string as a placeholder with `{variable}`, 
-and pass an object as the second argument to the function returned by the hook.
+```jsx
+const t = useGT();
+const itemCount = 5;
 
-```jsx copy
-const price = 100;
-const translate = useGT();
-translate('There are {count} items in the cart', { count: 10 });
+// String with placeholder
+const message = t('You have {count} items in your cart', { count: itemCount });
+// Result: "You have 5 items in your cart"
 ```
 
-The `{count}` placeholder will be replaced with the value of the `count` variable.
-
-This allows you to display dynamic values in your translations.
-
-For more information on the API, see the [API reference](/docs/react/api/strings/useGT).
+### Multiple Variables
+```jsx
+const t = useGT();
+const order = { id: 'ORD-123', total: 99.99, date: '2024-01-15' };
+
+const confirmation = t(
+  'Order {orderId} for ${total} was placed on {date}',
+  { 
+    orderId: order.id, 
+    total: order.total, 
+    date: order.date 
+  }
+);
+```
 
-`gt-react` supports ICU message format, which allows you to also format your variables.
+### ICU Message Format
+For advanced formatting, use ICU syntax:
 
-```jsx copy
-const translate = useGT();
-translate('There are {count, plural, =0 {no items} =1 {one item} other {{count} items}} in the cart');
+```jsx
+const t = useGT();
+translate('There are {count, plural, =0 {no items} =1 {one item} other {{count} items}} in the cart', { count: 10 });
 ```
 
 <Callout>
-  ICU message format is a powerful way to format your variables.
-  For more information, see the [ICU message format documentation](https://unicode-org.github.io/icu/userguide/format_parse/messages/).
+  Learn more about ICU Message Format in the [Unicode documentation](https://unicode-org.github.io/icu/userguide/format_parse/messages/).
 </Callout>
 
-
----
-
 ## Examples
 
-1. Translating a string in a component
-
-<Tabs items={['Result', 'Original']}>
-  <Tab value="Result">
+### Form Inputs
 ```jsx
 import { useGT } from 'gt-react';
 
-export default function MyComponent() {
+function ContactForm() {
   const t = useGT();
+  
   return (
-    <div>
-      <h1>{t('Hello, world!')}</h1>
-    </div>
-  )
-}
-```
-  </Tab>
-  <Tab value="Original">
-```jsx
-export default function MyComponent() {
-  return (
-    <div>
-      <h1>Hello, world!</h1>
-    </div>
-  )
+    <form>
+      <input 
+        type="email"
+        placeholder={t('Enter your email address')}
+        aria-label={t('Email input field')}
+      />
+      <textarea 
+        placeholder={t('Tell us about your project...')}
+        aria-label={t('Project description')}
+      />
+      <button type="submit">
+        {t('Send Message')}
+      </button>
+    </form>
+  );
 }
 ```
-  </Tab>
-</Tabs>
 
-2. Translating a string with variables
-
-<Tabs items={['Result', 'Original']}>
-  <Tab value="Result">
+### Navigation Menu
 ```jsx
 import { useGT } from 'gt-react';
 
-export default function MyComponent() {
+function Navigation() {
   const t = useGT();
-  const count = 10;
-  return (
-    <div>
-      <h1>{t('There are {count} items in the cart', { count })}</h1>
-    </div>
-  )
-}
-```
-  </Tab>
-  <Tab value="Original">
-```jsx
-export default function MyComponent() {
-  const count = 10;
-  return (
-    <div>
-      <h1>There are {count} items in the cart</h1>
-    </div>
-  )
-}
-```
-  </Tab>
-</Tabs>
-
-
-
-3. Translating parts of an object
-
-<Tabs items={['Result', 'Original']}>
-  <Tab value="Result">
-```jsx
-import { useGT } from 'gt-react';
+  
+  const menuItems = [
+    { label: t('Home'), href: '/', icon: 'home' },
+    { label: t('About Us'), href: '/about', icon: 'info' },
+    { label: t('Services'), href: '/services', icon: 'briefcase' },
+    { label: t('Contact'), href: '/contact', icon: 'mail' }
+  ];
 
-export default function MyComponent() {
-  const t = useGT();
-  const users = [
-    {
-      name: 'John',
-      description: t('John is a software engineer at General Translation'),
-    },
-    {
-      name: 'Jane',
-      description: t('Jane is a software engineer at Google'),
-    },
-  ]
-  return (
-    <div>
-      {users.map((user) => (
-        <div key={user.name}>
-          <h1>{user.name}</h1>
-          <p>{user.description}</p>
-        </div>
-      ))}
-    </div>
-  )
-}
-```
-  </Tab>
-  <Tab value="Original">
-```jsx
-export default function MyComponent() {
-  const users = [
-    {
-      name: 'John',
-      description: 'John is a software engineer at General Translation',
-    },
-    {
-      name: 'Jane',
-      description: 'Jane is a software engineer at Google',
-    },
-  ]
   return (
-    <div>
-      {users.map((user) => (
-        <div key={user.name}>
-          <h1>{user.name}</h1>
-          <p>{user.description}</p>
-        </div>
+    <nav>
+      {menuItems.map((item) => (
+        <a key={item.href} href={item.href} title={item.label}>
+          <Icon name={item.icon} />
+          {item.label}
+        </a>
       ))}
-    </div>
-  )
+    </nav>
+  );
 }
 ```
-  </Tab>
-</Tabs>
-
-
 
-4. Translating shared constants
-
-<Tabs items={['Result', 'Original']}>
-  <Tab value="Result">
-```jsx copy title="src/llms.ts"
-// Custom function to get LLM data with translations
-export function getLLMData(t: (content: string) => string) {
-  return [
-    {
-      name: 'GPT-4.1',
-      id: 'gpt-4.1',
-      description: t('GPT-4.1 is a large language model developed by OpenAI'),
-    },
-    {
-      name: 'Claude 3.7 Sonnet',
-      id: 'claude-3-7-sonnet',
-      description: t('Claude 3.7 Sonnet is a large language model developed by Anthropic'),
+### Dynamic Content Factory
+```jsx
+// utils/productData.js
+export function getProductMessages(t) {
+  return {
+    categories: [
+      { id: 'electronics', name: t('Electronics') },
+      { id: 'clothing', name: t('Clothing') },
+      { id: 'books', name: t('Books') }
+    ],
+    statusMessages: {
+      available: t('In stock and ready to ship'),
+      backordered: t('Currently backordered - ships in 2-3 weeks'),  
+      discontinued: t('This item has been discontinued')
     },
-  ]
+    errors: {
+      notFound: t('Product not found'),
+      outOfStock: t('Sorry, this item is currently out of stock')
+    }
+  };
 }
-```
 
-```jsx
-import { getLLMData } from './llms';
+// components/ProductCard.jsx
 import { useGT } from 'gt-react';
+import { getProductMessages } from '../utils/productData';
 
-export default function MyComponent() {
+function ProductCard({ product }) {
   const t = useGT();
-  const llms = getLLMData(t);
+  const messages = getProductMessages(t);
+  
   return (
     <div>
-      {llms.map((llm) => (
-        <div key={llm.id}>
-          <h1>{llm.name}</h1>
-          <p>{llm.description}</p>
-        </div>
-      ))}
+      <h3>{product.name}</h3>
+      <p>{messages.statusMessages[product.status]}</p>
+      <span>{messages.categories.find(c => c.id === product.categoryId)?.name}</span>
     </div>
-  )
+  );
 }
-```
-  </Tab>
-
-<Tab value="Original">
-```jsx copy title="src/llms.ts"
-export const llms = [
-  {
-    name: 'GPT-4.1',
-    id: 'gpt-4.1',
-    description: 'GPT-4.1 is a large language model developed by OpenAI',
-  },
-  {
-    name: 'Claude 3.7 Sonnet',
-    id: 'claude-3-7-sonnet',
-    description: 'Claude 3.7 Sonnet is a large language model developed by Anthropic',
-  },
-]
 ```
 
+### Component with Document Title
 ```jsx
-import { llms } from './llms';
+import { useGT } from 'gt-react';
+import { useEffect } from 'react';
 
-export default function MyComponent() {
+function ProductPage() {
+  const t = useGT();
+  
+  useEffect(() => {
+    document.title = t('Product Catalog - Find What You Need');
+    
+    // Update meta description
+    const metaDescription = document.querySelector('meta[name="description"]');
+    if (metaDescription) {
+      metaDescription.setAttribute('content', t('Browse our extensive collection of high-quality products'));
+    }
+  }, [t]);
+  
   return (
     <div>
-      {llms.map((llm) => (
-        <div key={llm.id}>
-          <h1>{llm.name}</h1>
-          <p>{llm.description}</p>
-        </div>
-      ))}
+      <h1>{t('Featured Products')}</h1>
+      <p>{t('Check out our latest and most popular items')}</p>
     </div>
-  )
+  );
 }
 ```
-</Tab>
-</Tabs>
-
-<Callout type="info">
-  In this last example, we turned the `llms` array into a function that returns the data with translations.
-  We passed the `t` function to the function that returns the data.
-
-  Alternatively, you could also turn the `llms` array into a custom hook.
-  However, this is not recommended, as you will need to be very careful about how you use the `useGT()` hook,
-  so as to not violate the [rules of React](https://react.dev/reference/rules/rules-of-hooks).
-
-  <Accordions>
-    <Accordion title="Why can't I directly import the `llms` array?">
-      This is because the `useGT()` hook requires access to the React context of the component that is calling it.
-      This context includes information about the current language and the translations for the current language.
-
-      If you try to import the `llms` array directly, without knowing the current language,
-      you will not be able to translate the strings.
-    </Accordion>
-  </Accordions>
-</Callout>
-
----
 
-## Common Pitfalls
+## Common Issues
 
-### Translating Dynamic Content
+### Dynamic Content at Runtime
+Strings must be known at build time - you cannot translate dynamic content:
 
-All strings must be known at build time.
+```jsx
+// ❌ Dynamic content won't work
+function MyComponent() {
+  const [userMessage, setUserMessage] = useState('');
+  const t = useGT();
+  
+  return <p>{t(userMessage)}</p>; // This will fail
+}
 
-This means that you cannot translate dynamic content that is generated or retrieved at runtime.
+// ✅ Use predefined strings
+function MyComponent() {
+  const [messageType, setMessageType] = useState('welcome');
+  const t = useGT();
+  
+  const messages = {
+    welcome: t('Welcome to our app!'),
+    goodbye: t('Thanks for visiting!')
+  };
+  
+  return <p>{messages[messageType]}</p>;
+}
+```
 
-This includes variables, even if they are strings.
+### Hook Rules Violations
+Follow React hook rules when using [`useGT()`](/docs/react/api/strings/useGT):
 
 ```jsx
-export default function MyComponent() {
-  const [dynamicContent, setDynamicContent] = useState('Hello, world!');
+// ❌ Don't call hooks conditionally
+function MyComponent({ showMessage }) {
+  if (showMessage) {
+    const t = useGT(); // Hook rule violation
+    return <p>{t('Hello!')}</p>;
+  }
+  return null;
+}
+
+// ✅ Always call hooks at top level
+function MyComponent({ showMessage }) {
   const t = useGT();
-  return (
-    <div>
-      <h1>{t(dynamicContent)}</h1> // This will not work
-    </div>
-  )
+  
+  if (showMessage) {
+    return <p>{t('Hello!')}</p>;
+  }
+  return null;
 }
 ```
 
-<Accordions>
-  <Accordion title="Why can't I translate dynamic content?">
-    This is because React is client-side rendered, and no translations can ever occur in production
-    due to security vulnerabilities involving exposed API keys. 
-    In development, translations will work because the development server
-    is not exposed to the public internet.
-  </Accordion>
-</Accordions>
-
-<Callout type="warn">
-  The CLI tool will warn you if you try to translate dynamic content
+<Callout>
+  For truly dynamic content that needs runtime translation, see the [Dynamic Content Guide](/docs/react/guides/dynamic-content).
 </Callout>
 
-
----
-
 ## Next Steps
- * Learn more about the [`<T>` component](/docs/react/guides/jsx).
- * See the [API reference for `useGT()`](/docs/react/api/strings/useGT).
\ No newline at end of file
+
+- [Dynamic Content Guide](/docs/react/guides/dynamic-content) - Handle runtime translation
+- [Shared Strings Guide](/docs/react/guides/shared-strings) - Organize reusable translations
+- API References:
+  - [`useGT()` Hook](/docs/react/api/strings/useGT)
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/react/guides/t.mdx b/apps/docs/content/docs/en/react/guides/t.mdx
new file mode 100644
index 000000000..5a97fbc6b
--- /dev/null
+++ b/apps/docs/content/docs/en/react/guides/t.mdx
@@ -0,0 +1,226 @@
+---
+title: The <T> Component
+description: How to internationalize JSX components using the <T> component
+---
+
+The [`<T>` component](/docs/react/api/components/t) is the primary tool for internationalizing JSX content in your React application. It wraps your JSX elements and automatically translates them based on the user's locale.
+
+## Quick Start
+
+Transform any static JSX content by wrapping it with [`<T>`](/docs/react/api/components/t):
+
+```jsx
+import { T } from 'gt-react';
+
+// Before
+function Greeting() {
+  return <p>Hello, world!</p>;
+}
+
+// After
+function Greeting() {
+  return <T><p>Hello, world!</p></T>;
+}
+```
+
+For dynamic content within [`<T>`](/docs/react/api/components/t), use [Variable Components](/docs/react/guides/variables) and [Branching Components](/docs/react/guides/branches).
+
+## Basic Usage
+
+The [`<T>` component](/docs/react/api/components/t) accepts any JSX content as children:
+
+```jsx
+// Simple text
+<T>Welcome to our app</T>
+
+// HTML elements
+<T><h1>Page Title</h1></T>
+
+// Complex nested JSX
+<T>
+  <div className="alert">
+    <span>Important:</span> Please read carefully.
+  </div>
+</T>
+```
+
+## Configuration Options
+
+### Adding Context
+
+Provide translation context for ambiguous terms:
+
+```jsx
+<T context="notification popup, not bread">
+  Click the toast to dismiss
+</T>
+```
+
+### Setting Translation IDs
+
+Use explicit IDs for consistent translations:
+
+```jsx
+<T id="welcome-message">
+  Welcome back, user!
+</T>
+```
+
+## When to Use `<T>`
+
+Use [`<T>`](/docs/react/api/components/t) for **static content only**:
+
+```jsx
+// ✅ Static content works
+<T><button>Click here</button></T>
+<T><h1>Welcome to our site</h1></T>
+
+// ❌ Dynamic content breaks
+<T><p>Hello {username}</p></T>
+<T><p>Today is {new Date()}</p></T>
+
+// ✅ Use Variable components for dynamic content
+<T>
+  <p>Hello <Var>{username}</Var></p>
+</T>
+```
+
+<Callout>
+  Variable and Branching components are designed to work inside [`<T>`](/docs/react/api/components/t) for dynamic content. See [Variable Components](/docs/react/guides/variables) and [Branching Components](/docs/react/guides/branches) guides for details.
+</Callout>
+
+## Examples
+
+### Simple Elements
+```jsx
+// Basic text
+<T>Hello, world!</T>
+
+// Button with text
+<T><Button>Submit Form</Button></T>
+
+// Heading with styling
+<T><h1 className="text-2xl font-bold">Welcome</h1></T>
+```
+
+### Complex Components
+```jsx
+// Navigation menu
+<T>
+  <nav className="navbar">
+    <a href="/about">About Us</a>
+    <a href="/contact">Contact</a>
+  </nav>
+</T>
+
+// Alert message
+<T>
+  <div className="alert alert-warning">
+    <AlertIcon className="w-5 h-5" />
+    <span>Your session expires in 5 minutes</span>
+  </div>
+</T>
+```
+
+### With Variables
+```jsx
+// Combining static text with dynamic values
+<T>
+  <p>Welcome back, <Var>{user.name}</Var>!</p>
+</T>
+
+// Form with mixed content
+<T>
+  <label>
+    Email: <input type="email" placeholder="Enter your email" />
+  </label>
+</T>
+```
+
+<Callout>
+  Learn more about the [`<Var>` component](/docs/react/api/components/var) in the [Variable Components Guide](/docs/react/guides/variables).
+</Callout>
+
+## Production Setup
+
+### Build Process
+Add translation to your build pipeline:
+
+```json title="package.json"
+{
+  "scripts": {
+    "build": "npx gtx-cli translate && <...YOUR_BUILD_COMMAND...>"
+  }
+}
+```
+
+### Development vs Production Behavior
+- **Development**: With a dev API key, translations happen on-demand when components render. You'll see real-time translation as you develop.
+- **Production**: All translations are pre-built during the build stage and will be visible once your application is live.
+
+Set your development API key in your environment to enable live translation during development. You can create one in the Dashboard under [API Keys](https://dash.generaltranslation.com/en-US/project/api-keys).
+
+### Privacy Considerations
+Content in [`<T>`](/docs/react/api/components/t) components is sent to the GT API for translation. For sensitive data, use [Variable Components](/docs/react/guides/variables#privacy) to keep private information local:
+
+```jsx
+// Safe - sensitive data stays local
+<T>
+  Welcome back, <Var>{username}</Var>
+</T>
+```
+
+## Common Issues
+
+### Component Boundaries
+[`<T>`](/docs/react/api/components/t) only translates direct children, not content inside other components:
+
+```jsx
+// ❌ Wrong - content inside components won't be translated
+function MyComponent() {
+  return <p>This won't be translated</p>;
+}
+
+<T>
+  <h1>This will be translated</h1>
+  <MyComponent /> {/* Content inside won't be translated */}
+</T>
+
+// ✅ Correct - wrap each component individually
+function MyComponent() {
+  return <T><p>This will be translated</p></T>;
+}
+
+<T><h1>This will be translated</h1></T>
+<MyComponent />
+```
+
+### Nesting `<T>` Components
+
+```jsx
+// ❌ Don't nest <T> components
+<T>
+  <T>Hello world</T> {/* Don't do this */}
+</T>
+```
+
+### Dynamic Content Errors
+The CLI will error on dynamic content in [`<T>`](/docs/react/api/components/t). Wrap dynamic values with Variable components:
+
+```jsx
+// ❌ Wrong - dynamic content breaks
+<T><p>Hello {username}</p></T>
+
+// ✅ Correct - use Variable components
+<T><p>Hello <Var>{username}</Var></p></T>
+```
+
+<Callout>
+  See the [Variable Components Guide](/docs/react/guides/variables) for handling dynamic values and the [Branching Components Guide](/docs/react/guides/branches) for conditional content.
+</Callout>
+
+## Next Steps
+
+- [Variable Components Guide](/docs/react/guides/variables) - Handle dynamic content within JSX translations
+- [Branching Components Guide](/docs/react/guides/branches) - Add conditional logic to your translations
+- [\<T\> Component API Reference](/docs/react/api/components/t)
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/react/guides/variables.mdx b/apps/docs/content/docs/en/react/guides/variables.mdx
index 6f8744aab..6bc9dbf2c 100644
--- a/apps/docs/content/docs/en/react/guides/variables.mdx
+++ b/apps/docs/content/docs/en/react/guides/variables.mdx
@@ -1,278 +1,225 @@
 ---
-title: Using Variables
-description: How to use variable components
+title: Variable Components
+description: How to use variable components for dynamic content within translations
 ---
 
-## Overview
+Variable components allow you to safely include dynamic content within [`<T>`](/docs/react/api/components/t) components. They handle formatting and localization locally without sending data to the translation API, making them perfect for sensitive information like usernames, account numbers, and financial data.
 
-Variable components in `gt-react` allow you to insert dynamic content into translations.
-These components include:
+## Available Components
 
-- [`<Var>`](/docs/react/api/components/var): For rendering variables.
-- [`<Num>`](/docs/react/api/components/num): For formatting numbers.
-- [`<Currency>`](/docs/react/api/components/currency): For formatting currency values.
-- [`<DateTime>`](/docs/react/api/components/datetime): For formatting dates and times.
+- [`<Var>`](/docs/react/api/components/var): Raw dynamic content without formatting
+- [`<Num>`](/docs/react/api/components/num): Numbers with locale-specific formatting
+- [`<Currency>`](/docs/react/api/components/currency): Currency values with symbols and formatting
+- [`<DateTime>`](/docs/react/api/components/datetime): Dates and times with locale conventions
 
-In this guide, we will cover:
-<Steps>
-  <Step>
-    What are variable components?
-  </Step>
-  <Step>
-    How to use variable components
-  </Step>
-  <Step>
-    Examples
-  </Step>
-  <Step>
-    Common pitfalls
-  </Step>
-</Steps>
+## Quick Start
 
+Variable components work inside [`<T>`](/docs/react/api/components/t) to handle dynamic content:
 
-## What are variable components?
-
-Variable components are used to wrap dynamic content such as user names, numerical values, dates, and currencies.
-
-These components allow you to format and render dynamic values in a way that aligns with your user's locale, without requiring any external translations.
-
-Use variable components in conjunction with the `<T>` component to ensure that dynamic content is displayed accurately and consistently.
+```jsx
+import { T, Var, Num, Currency, DateTime } from 'gt-react';
 
-Each variable component has different behavior:
+function UserProfile({ user }) {
+  return (
+    <T>
+      <p>Welcome back, <Var>{user.name}</Var>!</p>
+      <p>You have <Num>{user.itemCount}</Num> items.</p>
+      <p>Balance: <Currency currency="USD">{user.balance}</Currency></p>
+      <p>Last login: <DateTime>{user.lastLogin}</DateTime></p>
+    </T>
+  );
+}
+```
 
-- [`<Var>`](/docs/react/api/components/var): Renders any content dynamically, such as user names or identifiers.
-- [`<Num>`](/docs/react/api/components/num): Formats numerical values according to locale-specific rules.
-- [`<Currency>`](/docs/react/api/components/currency): Formats currency values with symbols and localization rules.
-- [`<DateTime>`](/docs/react/api/components/datetime): Formats dates and times using locale-specific conventions.
+## How Variable Components Work
 
-While JSX content and strings are translated via the General Translation API, variable components are completely handled locally.
+Variable components solve the dynamic content problem by:
 
-The `<Num>`, `<Currency>`, and `<DateTime>` components use the [JS i18n API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl) to format the content according to the user's locale.
+1. **Wrapping dynamic values** so they can be used inside [`<T>`](/docs/react/api/components/t)
+2. **Handling formatting locally** using the browser's built-in i18n APIs  
+3. **Keeping data private** - content is never sent to the translation API
+4. **Providing localization** based on the user's current locale
 
-<Callout type="info">
-  Content wrapped in variable components is never sent to the General Translation API, ensuring data privacy and security.
+```jsx
+// ❌ This breaks - dynamic content in <T>
+<T><p>Hello {username}</p></T>
 
-  See the section on [Data Privacy](#privacy) for more information.
-</Callout>
+// ✅ This works - dynamic content wrapped
+<T><p>Hello <Var>{username}</Var></p></T>
+```
 
----
+## Component Guide
 
-## How to use variable components
+### `<Var>` - Raw Dynamic Content
 
-### Basic Usage
+Use [`<Var>`](/docs/react/api/components/var) for any dynamic content that doesn't need special formatting:
 
-The usage for all variable components is the same.
+```jsx
+// User information
+<T>
+  <p>Hello, <Var>{user.name}</Var>!</p>
+  <p>Your account ID is <Var>{user.accountId}</Var></p>
+</T>
 
-```tsx
-const user = {
-  name: 'John',
-  age: 30,
-  balance: 1000,
-  birthday: new Date('1990-01-01'),
-}
-<div>
-  <Var>{user.name}</Var>
-  <Num>{user.age}</Num>
-  <Currency>{user.balance}</Currency>
-  <DateTime>{user.birthday}</DateTime>
-</div>
+// Conditional rendering
+<T>
+  Dashboard: <Var>{isAdmin ? <AdminPanel /> : <UserPanel />}</Var>
+</T>
 ```
 
-Simply wrap the variable component around the content you want to display.
-
-### Using Variable Components in `<T>` [#variable-in-t]
+### `<Num>` - Formatted Numbers
 
-By themselves, variable components don't do much, since they require knowledge of the user's locale to format the content.
+Use [`<Num>`](/docs/react/api/components/num) for numbers that should follow locale formatting rules:
 
-Thus, you should use variable components with `<T>` components.
+```jsx
+// Basic number formatting
+<T>
+  You have <Num>{itemCount}</Num> items in your cart.
+</T>
 
-The `<T>` component will not only handle the translation of the surrounding content, but also pass the correct locale to its child variable components.
+// Standalone usage (equivalent to number.toLocaleString())
+<Badge><Num>{totalItems}</Num></Badge>
 
-```tsx
+// Custom formatting options
 <T>
-  The current time is <DateTime>{time}</DateTime>.
+  Distance: <Num options={{ maximumFractionDigits: 2 }}>{distance}</Num> km
 </T>
 ```
 
+### `<Currency>` - Money Values
 
-### Variable localization [#localization]
-
-The `<Num>`, `<Currency>`, and `<DateTime>` components include built-in localization support.
-These components automatically format their content based on your user's selected locale, or based on additional options passed as props.
+Use [`<Currency>`](/docs/react/api/components/currency) for monetary amounts:
 
-For example:
-* [`<Num>`](/docs/react/api/components/num) displays numbers with localized decimal separators.
-* [`<Currency>`](/docs/react/api/components/currency) displays values with localized currency symbols and positioning.
-* [`<DateTime>`](/docs/react/api/components/datetime) displays dates and times according to locale-specific rules.
-
-You can also override the default locale and formatting options by passing props directly to these components.
+```jsx
+// Basic currency formatting (defaults to "USD")
+<T>
+  Your total is <Currency>{total}</Currency>.
+</T>
 
-### Data Privacy [#privacy]
+// Different currencies
+<T>
+  Price: <Currency currency="EUR">{price}</Currency>
+</T>
 
-Variable components handle all formatting locally; therefore, none of their children are sent to the General Translation APIs for translation (when used with `<T>` components).
-This is perfect for keeping sensitive data, such as user names or account numbers, private and secure.
+// Custom formatting
+<Currency 
+  currency="USD" 
+  options={{ minimumFractionDigits: 0 }}
+>
+  {roundedAmount}
+</Currency>
+```
 
-Each variable component handles formatting differently and should be used for specific types of content:
+### `<DateTime>` - Dates and Times
 
-* [`<Var>`](/docs/react/api/components/var): Anything private that does not require formatting
-  - User names, account numbers, etc.
-* [`<Num>`](/docs/react/api/components/num): Private numerical values that should be formatted according to locale
-  - Order quantities, age, distance, etc.
-* [`<Currency>`](/docs/react/api/components/currency): Private currency values that should be formatted according to locale
-  - Transaction amounts, account balances, etc.
-* [`<DateTime>`](/docs/react/api/components/datetime): Private date and time values that should be formatted according to locale
-  - Account creation dates, order timestamps, etc.
+Use [`<DateTime>`](/docs/react/api/components/datetime) for dates and times:
 
-<Callout type="warn">
-  [Branching Components](/docs/react/guides/branches)
-  and [`<T>` components](/docs/react/guides/jsx)
-  do send data to the General Translation APIs for translation.
+```jsx
+// Basic date formatting
+<T>
+  Order placed on <DateTime>{orderDate}</DateTime>
+</T>
 
-  Additionally, nesting a `<T>` inside a `<Var>` component will send the content to the General Translation APIs for translation.
-  ```tsx
-  <T>
-    <Var>
-      <T>Hello, world!</T>
-      Goodbye, World!
-    </Var>
-  </T>
-  ```
-  In the example above, "Hello, world!" will be sent to the General Translation APIs for translation,
-  while "Goodbye, World!" will not.
-</Callout>
+// Time formatting
+<T>
+  Last updated: <DateTime options={{ timeStyle: 'short' }}>{timestamp}</DateTime>
+</T>
 
----
+// Custom date format
+<DateTime options={{ 
+  year: 'numeric', 
+  month: 'long', 
+  day: 'numeric' 
+}}>
+  {eventDate}
+</DateTime>
+```
 
-## Examples
+## Privacy and Security
 
-### `<Var>`
+### Data Stays Local
+Variable components handle all formatting locally using the browser's [Intl APIs](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl). **No dynamic content is sent to the translation API**, making them perfect for:
 
-Because the `<Var>` component does not do any formatting, it should always be used in conjunction with a `<T>` component.
+- User names and personal information
+- Account numbers and IDs
+- Financial data and balances
+- Private timestamps and dates
 
 ```jsx
-import { T, Var } from 'gt-react';
-
-export default function UserGreeting({ user }) {
-  return (
-    <T>
-      Hello, <Var>{user.name}</Var>!
-      Your address is <Var>{user.addr}</Var>
-    </T>
-  );
-}
+// Safe - sensitive data stays local
+<T>
+  Account balance: <Currency currency="USD">{balance}</Currency>
+  Last login: <DateTime>{lastLoginTime}</DateTime>
+</T>
 ```
 
-Variable components also isolate data, so they can be used to render dynamic content that is not part of a translation.
+### Important Exception
+Be careful with nested [`<T>`](/docs/react/api/components/t) components inside variable components:
 
 ```jsx
-import { T, Var } from 'gt-react';
-
-export default function Dashboard({ isAdmin }) {
-  return (
-    <T>
-      Your Dashboard:
-      <Var>{isAdmin ? <AdminDashboard /> : <UserDashboard />}</Var>
-    </T>
-  );
-}
+// ⚠️ The inner <T> content WILL be sent for translation
+<T>
+  <Var>
+    <T>Hello, world!</T>  {/* This gets translated */}
+    {privateData}         {/* This stays local */}
+  </Var>
+</T>
 ```
 
-In the example above, the `isAdmin` ternary operator makes the `Dashboard` component dynamic.
-
-Without the `<Var>`, component, this would be an invalid use of the `<T>` component.
-
-<Callout type="info">
-  When using `<T>` components with dynamic content, use `<Var>` to wrap anything dynamic!
-</Callout>
+## Standalone Usage
 
-
-### `<Num>`
-
-The `<Num>` component can be used as a child of a `<T>` component or as a standalone component.
+Variable components can be used outside of [`<T>`](/docs/react/api/components/t) for pure formatting:
 
 ```jsx
-import { T, Num } from 'gt-react';
-import { Badge } from '@components/custom/cart/Badge';
-
-export default function OrderSummary() {
-  const quantity = 10;
-  return (
-    <>
-      <T>
-        You have <Num>{quantity}</Num> items in your cart.
-      </T>
-      <Badge>
-        <Num>{quantity}</Num> // This is the same as using quantity.toLocaleString()
-      </Badge>
-    </>
-  );
-}
+// These work like their respective .toLocale*() methods
+<span><Num>{count}</Num></span>                    // count.toLocaleString()
+<span><Currency currency="USD">{price}</Currency></span>  // price formatting
+<span><DateTime>{date}</DateTime></span>           // date.toLocaleDateString()
 ```
 
-### `<Currency>`
-
-The `<Currency>` component can be used as a child of a `<T>` component or as a standalone component.
-
-```jsx
-import { T, Currency } from 'gt-react';
-import { Badge } from '@components/custom/cart/Badge';
-
-export default function OrderSummary() {
-  const total = 1000;
-  return (
-    <>
-      <T>
-        Your total is <Currency currency={"USD"}>{total}</Currency>.
-      </T>
-      <Badge>
-        <Currency currency={"USD"}>{total}</Currency> // This will be formatted as $1,000
-      </Badge>
-    </>
-  );
-}
-
-```
+## Common Issues
 
-### `<DateTime>`
+### Ignoring Localization Options
 
-The `<DateTime>` component can be used as a child of a `<T>` component or as a standalone component.
+For [`<Currency>`](/docs/react/api/components/currency), make sure to pass the `currency` prop to specify the currency type. This ensures that the correct currency symbol and formatting are used when displaying the value:
 
 ```jsx
-import { T, DateTime } from 'gt-react';
+// ❌ Defaults to USD - may not be what users expect
+<T>
+  The item costs <Currency>{price}</Currency>
+</T>
 
-export default function OrderSummary() {
-  const date = new Date();
-  return (
-    <T>
-      Your order was placed on <DateTime>{date}</DateTime>.
-    </T>
-    <DateTime>{date}</DateTime> // This is the same as using date.toLocaleDateString() or date.toLocaleTimeString()
-  );
-}
+// ✅ Explicitly specify the currency
+<T>
+  The item costs <Currency currency="EUR">{price}</Currency>
+</T>
 ```
 
----
-
-## Common Pitfalls
-
-### Ignoring Localization Options [#localization-options]
+Other components also have optional props that allow you to customize the formatting:
 
-For `<Currency>`, make sure to pass the `currency` prop to specify the currency type.
-This ensures that the correct currency symbol and formatting are used when displaying the value.
-
-Other components, such as `<Num>` and `<DateTime>`, also have optional props that allow you to customize the formatting as well.
+```jsx
+// Basic formatting
+<T>
+  <Num>{count}</Num> items in stock
+</T>
 
----
+// Custom formatting
+<T>
+  <Num options={{ style: 'percent' }}>{percentage}</Num> completion rate
+</T>
 
-## Notes
- * Variable components isolate data, so they can be used to render dynamic content that is not part of a translation.
- * Variable components do not send data to the General Translation APIs, so they are perfect for keeping sensitive data private and secure.
- * Variable components can be used either as a child of a [`<T>`](/docs/react/guides/jsx) component or as a standalone component.
+// Date formatting
+<T>
+  Last updated: <DateTime options={{ dateStyle: 'short' }}>{lastUpdate}</DateTime>
+</T>
+```
 
 ## Next Steps
- * Explore conditional logic in [Branching Components](/docs/react/guides/branches).
- * Learn more about formatting options for specific variable components in the API Reference:
-   - [`<Num>`](/docs/react/api/components/num)
-   - [`<Currency>`](/docs/react/api/components/currency)
-   - [`<DateTime>`](/docs/react/api/components/datetime)
-   - [`<Var>`](/docs/react/api/components/var)
\ No newline at end of file
+
+- [Branching Components Guide](/docs/react/guides/branches) - Add conditional logic to your translations
+- [String Translation Guide](/docs/react/guides/strings) - Translate plain text without JSX
+- API References:
+  - [`<Var>` Component](/docs/react/api/components/var)
+  - [`<Num>` Component](/docs/react/api/components/num) 
+  - [`<Currency>` Component](/docs/react/api/components/currency)
+  - [`<DateTime>` Component](/docs/react/api/components/datetime)
\ No newline at end of file
diff --git a/apps/docs/content/docs/en/react/introduction.mdx b/apps/docs/content/docs/en/react/introduction.mdx
index c982f2521..a15804ea1 100644
--- a/apps/docs/content/docs/en/react/introduction.mdx
+++ b/apps/docs/content/docs/en/react/introduction.mdx
@@ -5,14 +5,13 @@ description: Overview of General Translation's React SDK
 
 ## Introduction
 
-The General Translation React SDK is an open-source internationalization (i18n) library for React.
+The General Translation React SDK is an open-source internationalization (i18n) library for React applications.
 
-It offers a set of tools to help you internationalize your React application in a easy and maintainable way,
-with feature parity to other popular i18n libraries.
+It provides a comprehensive set of tools to internationalize your React application in an easy and maintainable way, with feature parity to other popular i18n libraries.
 
-The React SDK can be used without the General Translation platform, and will act very similarly to other i18n libraries.
+The SDK can be used standalone without the General Translation platform and behaves similarly to other i18n libraries.
 
-However, it also integrates with our platform, offering additional features such as:
+However, it also integrates with our platform for enhanced features:
 
 - Translation Hot Reloading in Development
 - Automatic AI translations
@@ -21,52 +20,58 @@ However, it also integrates with our platform, offering additional features such
 
 ## Concepts
 
-There are 4 main concepts to understand about the SDK.
+There are 5 main concepts to understand about the SDK.
 
 <Steps>
   <Step>
-    The `<GTProvider>` component
+    The [`<GTProvider>`](/docs/react/api/components/gtprovider) component
   </Step>
   <Step>
-    The `<T>` component
+    The [`<T>`](/docs/react/api/components/t) component
   </Step>
   <Step>
-    The `useGT` hook
+    The [`useGT`](/docs/react/api/strings/useGT) hook
   </Step>
   <Step>
-    (Optional) The `useTranslations` hook
+    The [`msg()`](/docs/react/api/strings/msg) function for shared strings
+  </Step>
+  <Step>
+    (Optional) The [`useTranslations`](/docs/react/api/dictionary/useTranslations) hook
   </Step>
 </Steps>
 
 ## The `<GTProvider>` component
 
+The [`<GTProvider>`](/docs/react/api/components/gtprovider) component provides translation context to your application, including the current language and relevant translations.
+
 ```tsx
 import { GTProvider } from 'gt-react';
-```
-
-The `<GTProvider>` component is the main component that you need to add to your application.
-
-It is used to provide the rest of your application with context. 
 
-This context includes the current language and the relevant translations for that language.
-
-### Important Considerations
+function App() {
+  return (
+    <GTProvider>
+      <div>
+        {/* Your application content */}
+      </div>
+    </GTProvider>
+  );
+}
+```
 
-- The provider should wrap your entire application.
-- Ideally, it should be placed as high in the tree as possible, such as in your root component.
+**Important:** The provider should wrap your entire application and be placed as high in the component tree as possible, such as in your root App component.
 
-See the [GTProvider](/docs/react/api/components/gtprovider) page for more information.
+See the [`GTProvider`](/docs/react/api/components/gtprovider) API reference for more information.
 
 ## The `<T>` component
 
-The `<T>` component is the recommended way to translate content in your application.
+The [`<T>`](/docs/react/api/components/t) component is the recommended way to translate content in your application.
 
 It is a React component that can be used to wrap any JSX element, and will automatically render the content of the element into a supported language.
 
 <Callout type="info">
-We recommend using the `<T>` component wherever possible, since it allows for the most flexibility in translations.
+We recommend using the [`<T>`](/docs/react/api/components/t) component wherever possible, since it allows for the most flexibility in translations.
 
-Unlike strings, the `<T>` component can be used to translate HTML content, making it much more powerful than string translations.
+Unlike strings, the [`<T>`](/docs/react/api/components/t) component can be used to translate HTML content, making it much more powerful than string translations.
 </Callout>
 
 ### Examples
@@ -91,29 +96,29 @@ Unlike strings, the `<T>` component can be used to translate HTML content, makin
   Formatting can be done easily with the `<T>` component.
   <Num>{1000}</Num>
   <DateTime>{new Date()}</DateTime>
-  <Currency>{1000}</Currency>
+  <Currency currency="USD">{1000}</Currency>
 </T>
 ```
 
-See the [translating JSX](/docs/react/guides/jsx) guide to learn about the different ways to use the `<T>` component.
+The [`<T>`](/docs/react/api/components/t) component works with [variable components](/docs/react/guides/variables) like [`<Num>`](/docs/react/api/components/num), [`<DateTime>`](/docs/react/api/components/datetime), and [`<Currency>`](/docs/react/api/components/currency) for dynamic content formatting.
 
-See the [T API Reference](/docs/react/api/components/t) for the API of the `<T>` component.
+See the [`<T>` component guide](/docs/react/guides/t) to learn about the different ways to use the [`<T>`](/docs/react/api/components/t) component.
 
 ## The `useGT` hook
 
-The `useGT` hook is a React hook that can be used similarly to the `<T>` component, with some trade-offs.
+The [`useGT`](/docs/react/api/strings/useGT) hook is a React hook that can be used similarly to the [`<T>`](/docs/react/api/components/t) component, with some trade-offs.
 
 The hook returns a function that can be used to translate strings.
 
 ```tsx
-const translate = useGT();
+const t = useGT();
 
-translate('Hello, world!');
+t('Hello, world!');
 ```
 
-Compared to the `<T>` component, the `useGT` hook allows for more flexibility in your codebase.
+Compared to the [`<T>`](/docs/react/api/components/t) component, the [`useGT`](/docs/react/api/strings/useGT) hook allows for more flexibility in your codebase.
 
-For example, if you have a complex data structure with nested strings, a `<T>` component would be more difficult to use.
+For example, if you have a complex data structure with nested strings, a [`<T>`](/docs/react/api/components/t) component would be more difficult to use.
 
 ```tsx
 const t = useGT();
@@ -123,13 +128,55 @@ const data = {
 };
 ```
 
-See the [strings](/docs/react/guides/strings) guide to learn more about the `useGT` hook.
+See the [strings](/docs/react/guides/strings) guide to learn more about the [`useGT`](/docs/react/api/strings/useGT) hook.
+
+## The `msg()` function
+
+The [`msg()`](/docs/react/api/strings/msg) function is used to mark strings for translation that are used across multiple components or stored in configuration objects.
+
+This is particularly useful for shared content like navigation labels, form messages, or any text that appears in multiple places throughout your application.
+
+```tsx
+// Mark strings for translation
+import { msg } from 'gt-react';
+
+const navItems = [
+  { label: msg('Home'), href: '/' },
+  { label: msg('About'), href: '/about' },
+  { label: msg('Contact'), href: '/contact' }
+];
+```
+
+```tsx
+// Decode and use the marked strings
+import { useMessages } from 'gt-react';
+
+function Navigation() {
+  const m = useMessages();
+  
+  return (
+    <nav>
+      {navItems.map(item => (
+        <a key={item.href} href={item.href}>
+          {m(item.label)}
+        </a>
+      ))}
+    </nav>
+  );
+}
+```
+
+The [`msg()`](/docs/react/api/strings/msg) function encodes strings with translation metadata, and [`useMessages()`](/docs/react/api/dictionary/useMessages) decodes them.
+
+<Callout type="info">
+Use [`msg()`](/docs/react/api/strings/msg) for shared content that needs to be translated consistently across your application. For component-specific content, prefer [`<T>`](/docs/react/api/components/t) or [`useGT()`](/docs/react/api/strings/useGT).
+</Callout>
 
-See the [useGT API Reference](/docs/react/api/strings/useGT) for more information.
+See the [shared strings](/docs/react/guides/shared-strings) guide to learn more about the `msg()` function.
 
 ## The `useTranslations` hook
 
-The `useTranslations` hook is a React hook that returns a function that can be used to retrieve translations for a given key.
+The [`useTranslations`](/docs/react/api/dictionary/useTranslations) hook is a React hook that returns a function that can be used to retrieve translations for a given key.
 
 ```tsx title="dictionary.ts"
 const dictionary = {
@@ -144,18 +191,18 @@ const translate = useTranslations();
 translate('hello.world');
 ```
 
-This behavior is similar to other translation libraries, such as `react-i18next` and `next-intl`.
+This behavior is similar to other translation libraries, such as [`react-i18next`](https://react.i18next.com/) and [`next-intl`](https://next-intl-docs.vercel.app/).
 
 <Callout type="warn">
-We do not recommend using the `useTranslations` hook in your application. Frequent use of the hook will make your codebase more difficult to maintain, 
+We do not recommend using the [`useTranslations`](/docs/react/api/dictionary/useTranslations) hook in your application. Frequent use of the [`useTranslations`](/docs/react/api/dictionary/useTranslations) hook will make your codebase more difficult to maintain, 
 and will lead to large tech debt.
 
-Instead, we recommend using the `<T>` component or the `useGT` hook.
+Instead, we recommend using the [`<T>`](/docs/react/api/components/t) component or the [`useGT`](/docs/react/api/strings/useGT) hook.
 
-If you are migrating from another i18n library, the `useTranslations` hook is a drop-in replacement and can useful for incrementally migrating your codebase.
+If you are migrating from another i18n library, the [`useTranslations`](/docs/react/api/dictionary/useTranslations) hook is a drop-in replacement and can useful for incrementally migrating your codebase.
 </Callout>
 
-See the [dictionaries](/docs/react/guides/dictionaries) guide to learn more about the `useTranslations` hook.
+See the [dictionaries](/docs/react/guides/dictionaries) guide to learn more about the [`useTranslations`](/docs/react/api/dictionary/useTranslations) hook.
 
 See the [useTranslations API Reference](/docs/react/api/dictionary/useTranslations) for more information.
 
@@ -163,6 +210,7 @@ See the [useTranslations API Reference](/docs/react/api/dictionary/useTranslatio
 
 ## Next Steps
 
-- Learn about how to setup your React project with the SDK: [Project Quickstart](/docs/react)
-- Learn about how to translate strings with the `useGT` hook: [Translating Strings](/docs/react/guides/hooks)
-- Learn about how to translate JSX content with the `<T>` component: [Translating JSX](/docs/react/guides/jsx)
+- Learn about how to setup your React project with the SDK: [Quickstart](/docs/react/tutorials/quickstart)
+- Learn about how to translate JSX content with the [`<T>`](/docs/react/api/components/t) component: [JSX Translation Guide](/docs/react/guides/t)
+- Learn about how to translate strings with the [`useGT`](/docs/react/api/strings/useGT) hook: [String Translation Guide](/docs/react/guides/strings)
+- Learn about shared strings with the [`msg()`](/docs/react/api/strings/msg) function: [Shared Strings Guide](/docs/react/guides/shared-strings)
diff --git a/apps/docs/content/docs/en/react/meta.json b/apps/docs/content/docs/en/react/meta.json
index 102bde304..a49c62971 100644
--- a/apps/docs/content/docs/en/react/meta.json
+++ b/apps/docs/content/docs/en/react/meta.json
@@ -3,17 +3,18 @@
   "icon": "Atom",
   "pages": [
     "---Getting Started---",
-    "index",
     "introduction",
-    "---Guides---",
-    "guides/jsx",
-    "guides/strings",
-    "guides/shared-strings",
+    "index",
+    "---Core Translation---",
+    "guides/t",
     "guides/variables",
     "guides/branches",
+    "guides/strings",
+    "guides/shared-strings",
+    "guides/dictionaries",
     "guides/languages",
+    "---Advanced Integration---",
     "guides/local-tx",
-    "guides/dictionaries",
     "guides/migration",
     "---Technical Concepts---",
     "concepts/environments",
diff --git a/apps/docs/content/docs/en/react/tutorials/quickstart.mdx b/apps/docs/content/docs/en/react/tutorials/quickstart.mdx
index c3cc7af7d..52c636657 100644
--- a/apps/docs/content/docs/en/react/tutorials/quickstart.mdx
+++ b/apps/docs/content/docs/en/react/tutorials/quickstart.mdx
@@ -1,38 +1,11 @@
 ---
-title: Quickstart
+title: React Quickstart
 description: Easily internationalize your React App with gt-react
 ---
 
-## Overview
+Get your React app translating content in minutes.
 
-This quickstart guide will walk you through internationalizing your React app with `gt-react`.
-
-By the end of this guide, you will have a fully internationalized React app.
-
-In this guide, we will cover the following:
-
-<Steps>
-  <Step>
-    Installation
-  </Step>
-  <Step>
-    Configuration
-  </Step>
-  <Step>
-    Usage
-  </Step>
-  <Step>
-    Testing Your App
-  </Step>
-  <Step>
-    Deployment
-  </Step>
-</Steps>
-
-### Prerequisites
-
-- A React project using a supported framework (Next.js, Vite, etc.)
-- Basic knowledge of React and JavaScript
+**Prerequisites:** React, basic JavaScript knowledge
 
 ## Installation
 
@@ -42,7 +15,7 @@ Install the `gt-react` and `gtx-cli` packages:
   <Tab value="npm">
   ```bash 
   npm i gt-react
-  npm i --save-dev gtx-cli
+  npm i gtx-cli
   ``` 
   </Tab>
   <Tab value="yarn">
@@ -66,17 +39,8 @@ Install the `gt-react` and `gtx-cli` packages:
   </Tab>
 </Tabs>
 
----
-
 <Callout type="info">
-  **Automatic Setup:** We have an experimental Setup Wizard that can help you setup your project with `gt-react`.
-
-  Try it out by running `npx gtx-cli@latest`. You'll still need to manually internationalize content, but it will help you get started.
-
-  See the [Setup Wizard](/docs/cli/init) reference guide for more information. 
-
-  Alternatively, if you would like your AI tool like Claude Code, Cursor, or Windsurf to automatically setup your project, 
-  you can use our [mcp server](/docs/platform/ai-tools).
+  **Quick Setup:** Try `npx gtx-cli@latest` for automatic configuration. See the [Setup Wizard](/docs/cli/init) guide or use our [AI tools integration](/docs/platform/ai-tools).
 </Callout>
 
 
@@ -84,106 +48,64 @@ Install the `gt-react` and `gtx-cli` packages:
 
 ### `GTProvider`
 
-The core of `gt-react` is the `GTProvider` component.
-
-It is responsible for:
-
-- Managing the user's current locale
-- Providing relevant translations to your application
-- Providing context to hooks for accessing translations
-- Providing context to hooks for changing the user's locale
+The [`GTProvider`](/docs/react/api/components/gtprovider) component provides translation context to your React components. It manages locale state, translations, and enables the [`useGT`](/docs/react/api/strings/useGT) and [`useTranslations`](/docs/react/api/dictionary/useTranslations) hooks.
 
-<Steps>
-  <Step>
-    First, add the `GTProvider` component to your application. It should be placed as high up in your component tree as possible.
+Add the [`GTProvider`](/docs/react/api/components/gtprovider) to your root App component:
 
-    ```tsx copy title="src/App.tsx"
-    import { GTProvider } from 'gt-react';
+```tsx title="src/App.tsx"
+import { GTProvider } from 'gt-react';
 
-    export default function App() {
-      return (
-        <GTProvider>
-          <App />
-        </GTProvider>
-      );
-    }
-    ```
-  </Step>
-  <Step>
-    Next, create a [`gt.config.json`](/docs/react/api/config/gt-config-json) file in the root of your project.
-    This file is used to configure both the `gtx-cli` tool and the `gt-react` library.
-
-    ```json title="gt.config.json" copy
-    {
-      "defaultLocale": "en",
-      "locales": ["fr", "es"]
-    }
-    ```
-    You should customize the `defaultLocale` and `locales` to match your project. See the list of [supported locales](/docs/platform/locale-strings) for more information.
-
-  </Step>
-  <Step>
-    Lastly, spread the `gt.config.json` file into the provider's props.
-
-    ```tsx
-    import gtConfig from './gt.config.json';
-
-    <GTProvider {...gtConfig}>
-      <App />
+export default function App() {
+  return (
+    <GTProvider>
+      <YourAppContent />
     </GTProvider>
-    ```
-    <Callout type="info">
-      Spreading the `gt.config.json` file makes the config consistent across your application and CLI tool.
+  );
+}
+```
 
-      Alternatively, you can individually specify each prop in the `GTProvider` component.
+Create a [`gt.config.json`](/docs/cli/reference/config) file in your project root:
 
-      ```tsx
-      <GTProvider
-        defaultLocale="en"
-        locales={["fr", "es"]}
-      >
-      ```
-    </Callout>
-  </Step>
-</Steps>
+```json title="gt.config.json"
+{
+  "defaultLocale": "en",
+  "locales": ["fr", "es", "de"]
+}
+```
+
+Customize the locales for your project. See [supported locales](/docs/platform/locale-strings) for options.
 
 ### Environment Variables
 
-Set the following environment variables:
+Add to your environment file for development hot-reloading:
 
-<Tabs items={["Vite", "Next.js Pages Router", "Gatsby", "RedwoodJS",  "create-react-app", "Other"]}>
+<Tabs items={["Vite", "create-react-app", "Gatsby", "RedwoodJS", "Other"]}>
     <Tab value="Vite">
-    ```bash copy
-    VITE_GT_API_KEY="" # Your General Translation Developer API key
-    VITE_GT_PROJECT_ID="" # Your General Translation project ID
+    ```bash title=".env.local"
+    VITE_GT_API_KEY="your-dev-api-key"
+    VITE_GT_PROJECT_ID="your-project-id"
     ```
     </Tab>
-    <Tab value="Gatsby">
-    ```bash copy
-    GATSBY_GT_API_KEY="" # Your General Translation Developer API key
-    GATSBY_GT_PROJECT_ID="" # Your General Translation project ID
-    ```
-    </Tab>
-    <Tab value="RedwoodJS">
-    ```bash copy
-    REDWOOD_ENV_GT_API_KEY="" # Your General Translation Developer API key
-    REDWOOD_ENV_PROJECT_ID="" # Your General Translation project ID
+    <Tab value="create-react-app">
+    ```bash title=".env.local"
+    REACT_APP_GT_API_KEY="your-dev-api-key"
+    REACT_APP_GT_PROJECT_ID="your-project-id"
     ```
     </Tab>
-    <Tab value="Next.js Pages Router">
-    ```bash copy
-    NEXT_PUBLIC_GT_API_KEY="" # Your General Translation Developer API key
-    NEXT_PUBLIC_GT_PROJECT_ID="" # Your General Translation project ID
+    <Tab value="Gatsby">
+    ```bash title=".env.development"
+    GATSBY_GT_API_KEY="your-dev-api-key"
+    GATSBY_GT_PROJECT_ID="your-project-id"
     ```
     </Tab>
-    <Tab value="create-react-app">
-    ```bash copy
-    REACT_APP_GT_API_KEY="" # Your General Translation Developer API key
-    REACT_APP_GT_PROJECT_ID="" # Your General Translation project ID
+    <Tab value="RedwoodJS">
+    ```bash title=".env"
+    REDWOOD_ENV_GT_API_KEY="your-dev-api-key"
+    REDWOOD_ENV_GT_PROJECT_ID="your-project-id"
     ```
     </Tab>
     <Tab value="Other">
-    Many react frameworks each have a unique way of exporting environment variables to the client.
+    Many React frameworks each have a unique way of exporting environment variables to the client.
     In development environments, both `GT_API_KEY` and `GT_PROJECT_ID` need to be exported to the client.
 
     We have added support for a few libraries so far,
@@ -192,14 +114,14 @@ Set the following environment variables:
 </Tabs>
 
 <Callout type="warn">
-  **Make sure your API key variable is only set in your development environment! It should not be set in production.**
+  **Development only:** Don't set `GT_API_KEY` in production - it's only for development hot-reloading.
 </Callout>
 
-You can get a free API key and project ID by creating a [General Translation account](https://dash.generaltranslation.com/signup).
-
-After creating an account, navigate to the [Development API Keys](https://dash.generaltranslation.com/settings/dev-api-keys) page to get your Dev API key and project ID.
+Get your free API keys at [dash.generaltranslation.com](https://dash.generaltranslation.com/signup) or run:
 
-Alternatively, you can also use the CLI tool command [`npx gtx-cli auth`](/docs/cli/auth) to generate an API key and project ID for your project, saved to your `.env.local` file.
+```bash
+npx gtx-cli auth
+```
 
 <Accordions>
   <Accordion title="What if I don't want to use the General Translation platform?">
@@ -213,6 +135,7 @@ Alternatively, you can also use the CLI tool command [`npx gtx-cli auth`](/docs/
   - Automatic AI translations
   - Syncing translations with the General Translation platform
   - Native integration with our translation CDN
+  - On-demand translation of React components in production (client-side)
 
   To avoid using the General Translation platform, just don't set any environment variables.
   </Accordion>
@@ -223,78 +146,79 @@ Alternatively, you can also use the CLI tool command [`npx gtx-cli auth`](/docs/
 
 ## Usage
 
-Great! If you've followed the steps above, your React project is now setup to use `gt-react`.
-
-The next step is to internationalize your content. 
-Here, we'll give a brief overview of the different ways to translate content in your application.
-
-
-### `<T>` Component
+Now you can start internationalizing your content. There are two main approaches:
 
-The `<T>` component is the main component for translating JSX content in your application.
+### JSX Content with `<T>`
 
-To use it, simply wrap the JSX you want to translate in the `<T>` component.
+Wrap JSX elements to translate them using the [`<T>`](/docs/react/api/components/t) component:
 
 ```tsx
 import { T } from 'gt-react';
-<T>
-  <div>Your content</div>
-</T>
+
+function Welcome() {
+  return (
+    <T>
+      <h1>Welcome to our app!</h1>
+    </T>
+  );
+}
 ```
 
-If you have dynamic content, you'll need to use [variable components](/docs/react/guides/variables) to pass in the dynamic values.
+For dynamic content, use [variable components](/docs/react/guides/variables) like [`<Var>`](/docs/react/api/components/var):
 
 ```tsx
 import { T, Var } from 'gt-react';
 
-<T>
-  <div>Hello, <Var>{name}</Var>!</div>
-</T>
+function Greeting({ user }) {
+  return (
+    <T>
+      <p>Hello, <Var>{user.name}</Var>!</p>
+    </T>
+  );
+}
 ```
 
-See the [Translating JSX](/docs/react/guides/jsx) guide for more information.
-
+See the guide on [using the `<T>` component](/docs/react/guides/t) for more information.
 
-### `useGT` Hook
+### Plain Strings with `useGT`
 
-The `useGT` hook is a React hook that returns a function that can be used to translate strings.
+For attributes, labels, and plain text using the [`useGT`](/docs/react/api/strings/useGT) hook:
 
 ```tsx
 import { useGT } from 'gt-react';
 
-const translate = useGT();
-translate('Hello, world!');
+function ContactForm() {
+  const t = useGT();
+  
+  return (
+    <input 
+      placeholder={t('Enter your email')}
+      aria-label={t('Email input field')}
+    />
+  );
+}
 ```
 
-See the [Translating Strings](/docs/react/guides/strings) guide for more information.
-
-
-<Callout type="info">
-  Utilizing the hot-reload translation functionality will be helpful for internationalizing your application.
-
-  To enable this, make sure you have the `GT_API_KEY` and `GT_PROJECT_ID` environment variables set in your development environment.
-</Callout>
+See the guide on [translating strings](/docs/react/guides/strings) for more information.
 
 ---
 
+
 ## Testing Your App
 
-Congratulations! 🥳 If you've followed the steps above, your app is now multilingual! Let's see it in action.
-
-### See Your App in a Different Language
-
-<Steps>
-  <Step>
-    Add the [`<LocaleSelector>`](/docs/react/api/components/localeSelector) component to your app.
-    This will allow you to select a different language for your app.
-    <Callout>
-      **Tip:**
-      You can also skip this step and just change your language in your browser settings.
-    </Callout>
-  </Step>
-  <Step>
-    Start your React app in development mode.
-    <Tabs items={["npm", "yarn", "bun", "pnpm"]}>
+Test your translations by switching languages:
+
+1. **Add a locale selection dropdown** using [`<LocaleSelector>`](/docs/react/api/components/localeSelector):
+   ```tsx
+   import { LocaleSelector } from 'gt-react';
+   
+   function App() {
+     return <LocaleSelector />;
+   }
+   ```
+   
+2. **Start your dev server**:
+   <Tabs items={["npm", "yarn", "bun", "pnpm"]}>
       <Tab value="npm">
       ```bash
       npm run dev 
@@ -316,12 +240,10 @@ Congratulations! 🥳 If you've followed the steps above, your app is now multil
       ```
       </Tab>
     </Tabs>
-  </Step>
-  <Step>
-    Open up your app in your preferred browser (usually at
-    [http://localhost:3000](http://localhost:3000)).
-  </Step>
-</Steps>
+
+3. **Visit [localhost:3000](http://localhost:3000)** and change languages via the locale selection dropdown.
+
+In development, translations happen on-demand (you'll see a brief loading time). In production, everything is pre-translated.
 
 ### Troubleshooting
 
@@ -342,10 +264,8 @@ Congratulations! 🥳 If you've followed the steps above, your app is now multil
     * [Firefox](https://support.mozilla.org/en-US/kb/delete-cookies-remove-info-websites-stored)
     * [Safari](https://support.apple.com/en-mn/guide/safari/sfri11471/16.0/mac/11.0)
     * [Edge](https://support.microsoft.com/en-us/microsoft-edge/delete-cookies-in-microsoft-edge-63947406-40ac-c3b8-57b9-2a946a29ae09)
-
-    If this does not work, make sure that the list of locales in your [`<GTProvider>`](/docs/react/api/components/gtprovider) is up to date.
   </Accordion>
-  <Accordion title="Why do new languages take a long time to load?">
+  <Accordion title="Why do languages take a long time to load in dev?">
     **On-Demand Translation**
 
     You may notice when loading languages in development, translations will take a few seconds to be displayed.
@@ -354,86 +274,57 @@ Congratulations! 🥳 If you've followed the steps above, your app is now multil
     
     This **only happens in dev** so you can easily prototype your website in different languages.
     All translations are preloaded in production, so there will be no delay.
-    Follow our guide on [shipping to production](/docs/next/tutorials/quickdeploy).
-  </Accordion>
-  <Accordion title="Why are some things translating and others not?">
-    **JSX Translation**
-
-    Right now, the setup tool automatically adds `<T>` components around text content.
-    We are currently working on a solution that will automatically setup string translations.
-    Until then, if you are rendering a string, please follow [this guide](/docs/react/guides/strings) for translating strings.
+    Follow our guide on [shipping to production](/docs/react/tutorials/quickdeploy).
   </Accordion>
   <Accordion title="Why are some translations inaccurate?">
     The most likely cause of an inaccurate translation is ambiguous wording.
     For example, "apple" can be a fruit or a technology company.
 
     To fix this, you can provide more context to the translation with the `context` prop.
-    The [`<T>`](/docs/react/api/components/t) and [`useGT()`](/docs/react/api/strings/useGT) functions support a `context` prop.
+    The [`<T>`](/docs/react/api/components/t) and [`useGT()`](/docs/react/api/strings/useGT) functions all support a `context` prop.
     For example:
     ```jsx
     <T context="the technology company">Apple</T>
     ```    
-    See our [guide on the `<T>` component](/docs/react/guides/jsx) for more information.
   </Accordion>
 </Accordions>
 
-
 ---
 
 ## Deployment
 
-Great! If you're satisfied with your translations and the functionality of your app, you can now deploy your application.
-
-The behavior of `gt-react` in production is slightly different from development. Specifically, no translations will be performed at runtime.
-
-This means that you'll need to translate your content before deploying your application, in the build process.
-
-Luckily, the `gtx-cli` tool has a `translate` command that can be used to automatically translate your content.
-
-<Steps>
-  <Step>
-    First, you'll need to get a Production API key from the [General Translation platform](https://dash.generaltranslation.com).
-
-    Please note that this key is different from your Development API key, and begins with `gtx-api-`, instead of `gtx-dev-`.
-
-    Read about the difference between Development and Production keys [here](/docs/react/concepts/environments).
-  </Step>
-  <Step>
-    Add this environment variable to your CI/CD pipeline.
-
-    ```bash
-    GT_PROJECT_ID=<your-project-id>
-    GT_API_KEY=<your-production-api-key>
-    ```
-    <Callout type='warn'>
-      Make sure that `GT_API_KEY` is **NOT** prefixed with `NEXT_PUBLIC_` or `VITE_`, depending on your framework!
-
-      If it is, you'll risk exposing your API key to the public.
-    </Callout>
-  </Step>
-  <Step>
-    Run the `translate` command to translate your content.
-
-    ```bash
-    npx gtx-cli translate
-    ```
-    You can configure the behavior of the `translate` command with the [`gt.config.json`](/docs/cli/reference/config) file.
-
-    See the [CLI Tool](/docs/cli/translate) reference guide for more information.
-    
-  </Step>
-  <Step>
-    Add the `translate` command to your build process.
-
-    ```json title="package.json" copy
-    {
-      "scripts": {
-        "build": "npx gtx-cli translate && <...YOUR_BUILD_COMMAND...>"
-      }
-    }
-    ```
-  </Step>
-</Steps>
+For production, you need to pre-translate content since runtime translation is disabled (except for [`<Tx>`](/docs/react/api/components/tx) and [`tx()`](/docs/react/api/strings/tx) functions).
+
+1. **Get a production API key** from [dash.generaltranslation.com](https://dash.generaltranslation.com). 
+   
+   Production keys begin with `gtx-api-` (different from dev keys which start with `gtx-dev-`). Learn more about [environment differences](/docs/react/concepts/environments).
+
+2. **Add to your CI/CD environment**:
+   ```bash
+   GT_PROJECT_ID=your-project-id
+   GT_API_KEY=gtx-api-your-production-key
+   ```
+   <Callout type="warn">
+     **Never** prefix production keys with your framework's public variable prefix (like `VITE_`, `REACT_APP_`, etc.) - they should remain server-side only.
+   </Callout>
+
+3. **Run the translate command** to translate your content:
+   ```bash
+   npx gtx-cli translate
+   ```
+   
+   You can configure the behavior of the translate command with the [`gt.config.json`](/docs/cli/reference/config) file.
+   
+   See the [CLI Tool](/docs/cli/translate) reference guide for more information.
+
+4. **Update your build script** to translate before building:
+   ```json title="package.json"
+   {
+     "scripts": {
+       "build": "npx gtx-cli translate && <...YOUR_BUILD_COMMAND...>"
+     }
+   }
+   ```
 
 <Accordions>
   <Accordion title="What if I'm not using the General Translation platform?">
@@ -451,17 +342,9 @@ Luckily, the `gtx-cli` tool has a `translate` command that can be used to automa
   </Accordion>
 </Accordions>
 
----
-
-## Summary
-
- * In this guide, we covered how to setup your React project with `gt-react`
- * We briefly covered the different ways to translate content in your application.
- * We also covered how to deploy your application after you've internationalized your content.
-
-
 ## Next Steps
 
-- Learn about how to translate JSX content with the `<T>` component: [Translating JSX](/docs/react/guides/jsx)
-- Learn about how to translate strings with the `useGT` hook: [Translating Strings](/docs/react/guides/hooks)
-- Learn how to use local translations: [Local Translations](/docs/react/guides/local-tx)
\ No newline at end of file
+- [`<T>` Component Guide](/docs/react/guides/t) - Deep dive into the [`<T>`](/docs/react/api/components/t) component and JSX translation
+- [String Translation Guide](/docs/react/guides/strings) - Using [`useGT()`](/docs/react/api/strings/useGT) for string translation  
+- [Variable Components](/docs/react/guides/variables) - Handle dynamic content with [`<Var>`](/docs/react/api/components/var), [`<Num>`](/docs/react/api/components/num), etc.
+- [Language Switching](/docs/react/guides/languages) - Let users change languages with [`<LocaleSelector>`](/docs/react/api/components/localeSelector)
\ No newline at end of file
diff --git a/apps/docs/gt.config.json b/apps/docs/gt.config.json
index 12eb243d5..6ea6c3e79 100644
--- a/apps/docs/gt.config.json
+++ b/apps/docs/gt.config.json
@@ -12,6 +12,5 @@
       "exclude": ["content/docs/[locale]/changelog/**/*.mdx"]
     }
   },
-  "locales": ["zh", "de", "fr", "es", "ja"],
-  "_versionId": "6c0c6d36f6c10300382686d7f29231a4de1550a6b9ebbef45438936a59d3ec37"
+  "locales": ["zh", "de", "fr", "es", "ja"]
 }
diff --git a/apps/docs/loadTranslations.ts b/apps/docs/loadTranslations.ts
index 829e82238..f30ccf3b6 100644
--- a/apps/docs/loadTranslations.ts
+++ b/apps/docs/loadTranslations.ts
@@ -1,4 +1,4 @@
 export default async function loadTranslations(locale: string) {
-  const t = await import(`./public/_gt/${locale}.json`);
-  return t.default;
+  const translations = await import(`./public/_gt/${locale}.json`);
+  return translations.default;
 }
diff --git a/apps/docs/next.config.mjs b/apps/docs/next.config.mjs
index f0f4c23be..80ecfd0be 100644
--- a/apps/docs/next.config.mjs
+++ b/apps/docs/next.config.mjs
@@ -20,6 +20,11 @@ const config = {
         destination: '/docs/platform',
         permanent: false,
       },
+      {
+        source: '/:locale/docs/changelog/:path*',
+        destination: 'https://github.com/generaltranslation/gt/releases',
+        permanent: false,
+      },
     ];
   },
   async rewrites() {
diff --git a/apps/docs/package-lock.json b/apps/docs/package-lock.json
index 02b41329a..476b5138d 100644
--- a/apps/docs/package-lock.json
+++ b/apps/docs/package-lock.json
@@ -19,11 +19,13 @@
         "fumadocs-mdx": "^11.6.5",
         "fumadocs-typescript": "^4.0.5",
         "fumadocs-ui": "^15.3.4",
-        "gt-next": "^6.2.5",
-        "gtx-cli": "^2.1.8",
+        "gt-next": "^6.6.2",
+        "gtx-cli": "^2.3.4",
         "lucide-react": "^0.483.0",
-        "next": "^15.3.2",
+        "mermaid": "^11.12.0",
+        "next": "^15.5.4",
         "next-sitemap": "^4.2.3",
+        "next-themes": "^0.4.6",
         "posthog-js": "^1.242.2",
         "posthog-node": "^4.17.1",
         "react": "^19.0.0",
@@ -73,6 +75,28 @@
         "node": ">=6.0.0"
       }
     },
+    "node_modules/@antfu/install-pkg": {
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/@antfu/install-pkg/-/install-pkg-1.1.0.tgz",
+      "integrity": "sha512-MGQsmw10ZyI+EJo45CdSER4zEb+p31LpDAFp2Z3gkSd1yqVZGi0Ebx++YTEMonJy4oChEMLsxZ64j8FH6sSqtQ==",
+      "license": "MIT",
+      "dependencies": {
+        "package-manager-detector": "^1.3.0",
+        "tinyexec": "^1.0.1"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/antfu"
+      }
+    },
+    "node_modules/@antfu/utils": {
+      "version": "9.2.1",
+      "resolved": "https://registry.npmjs.org/@antfu/utils/-/utils-9.2.1.tgz",
+      "integrity": "sha512-TMilPqXyii1AsiEii6l6ubRzbo76p6oshUSYPaKsmXDavyMLqjzVDkcp3pHp5ELMUNJHATcEOGxKTTsX9yYhGg==",
+      "license": "MIT",
+      "funding": {
+        "url": "https://github.com/sponsors/antfu"
+      }
+    },
     "node_modules/@babel/code-frame": {
       "version": "7.26.2",
       "resolved": "https://registry.npmjs.org/@babel/code-frame/-/code-frame-7.26.2.tgz",
@@ -368,6 +392,51 @@
         "node": ">=6.9.0"
       }
     },
+    "node_modules/@braintree/sanitize-url": {
+      "version": "7.1.1",
+      "resolved": "https://registry.npmjs.org/@braintree/sanitize-url/-/sanitize-url-7.1.1.tgz",
+      "integrity": "sha512-i1L7noDNxtFyL5DmZafWy1wRVhGehQmzZaz1HiN5e7iylJMSZR7ekOV7NsIqa5qBldlLrsKv4HbgFUVlQrz8Mw==",
+      "license": "MIT"
+    },
+    "node_modules/@chevrotain/cst-dts-gen": {
+      "version": "11.0.3",
+      "resolved": "https://registry.npmjs.org/@chevrotain/cst-dts-gen/-/cst-dts-gen-11.0.3.tgz",
+      "integrity": "sha512-BvIKpRLeS/8UbfxXxgC33xOumsacaeCKAjAeLyOn7Pcp95HiRbrpl14S+9vaZLolnbssPIUuiUd8IvgkRyt6NQ==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@chevrotain/gast": "11.0.3",
+        "@chevrotain/types": "11.0.3",
+        "lodash-es": "4.17.21"
+      }
+    },
+    "node_modules/@chevrotain/gast": {
+      "version": "11.0.3",
+      "resolved": "https://registry.npmjs.org/@chevrotain/gast/-/gast-11.0.3.tgz",
+      "integrity": "sha512-+qNfcoNk70PyS/uxmj3li5NiECO+2YKZZQMbmjTqRI3Qchu8Hig/Q9vgkHpI3alNjr7M+a2St5pw5w5F6NL5/Q==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@chevrotain/types": "11.0.3",
+        "lodash-es": "4.17.21"
+      }
+    },
+    "node_modules/@chevrotain/regexp-to-ast": {
+      "version": "11.0.3",
+      "resolved": "https://registry.npmjs.org/@chevrotain/regexp-to-ast/-/regexp-to-ast-11.0.3.tgz",
+      "integrity": "sha512-1fMHaBZxLFvWI067AVbGJav1eRY7N8DDvYCTwGBiE/ytKBgP8azTdgyrKyWZ9Mfh09eHWb5PgTSO8wi7U824RA==",
+      "license": "Apache-2.0"
+    },
+    "node_modules/@chevrotain/types": {
+      "version": "11.0.3",
+      "resolved": "https://registry.npmjs.org/@chevrotain/types/-/types-11.0.3.tgz",
+      "integrity": "sha512-gsiM3G8b58kZC2HaWR50gu6Y1440cHiJ+i3JUvcp/35JchYejb2+5MVeJK0iKThYpAa/P2PYFV4hoi44HD+aHQ==",
+      "license": "Apache-2.0"
+    },
+    "node_modules/@chevrotain/utils": {
+      "version": "11.0.3",
+      "resolved": "https://registry.npmjs.org/@chevrotain/utils/-/utils-11.0.3.tgz",
+      "integrity": "sha512-YslZMgtJUyuMbZ+aKvfF3x1f5liK4mWNxghFRv7jqRR9C3R3fAOGTTKvxXDa2Y1s9zSbcpuO0cAxDYsc9SrXoQ==",
+      "license": "Apache-2.0"
+    },
     "node_modules/@clack/core": {
       "version": "1.0.0-alpha.4",
       "resolved": "https://registry.npmjs.org/@clack/core/-/core-1.0.0-alpha.4.tgz",
@@ -417,9 +486,9 @@
       }
     },
     "node_modules/@emnapi/runtime": {
-      "version": "1.4.3",
-      "resolved": "https://registry.npmjs.org/@emnapi/runtime/-/runtime-1.4.3.tgz",
-      "integrity": "sha512-pBPWdu6MLKROBX05wSNKcNb++m5Er+KQ9QkB+WVM+pW2Kx9hoSrVTnu3BdkI5eBLZoKu/J6mW/B6i6bJB2ytXQ==",
+      "version": "1.5.0",
+      "resolved": "https://registry.npmjs.org/@emnapi/runtime/-/runtime-1.5.0.tgz",
+      "integrity": "sha512-97/BJ3iXHww3djw6hYIfErCZFee7qCtrneuLa20UXFCOTCfBM2cvQHjWJ2EG0s0MtdNwInarqCTz35i4wWXHsQ==",
       "license": "MIT",
       "optional": true,
       "dependencies": {
@@ -1018,6 +1087,40 @@
       "deprecated": "Use @eslint/object-schema instead",
       "dev": true
     },
+    "node_modules/@iconify/types": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/@iconify/types/-/types-2.0.0.tgz",
+      "integrity": "sha512-+wluvCrRhXrhyOmRDJ3q8mux9JkKy5SJ/v8ol2tu4FVjyYvtEzkc/3pK15ET6RKg4b4w4BmTk1+gsCUhf21Ykg==",
+      "license": "MIT"
+    },
+    "node_modules/@iconify/utils": {
+      "version": "3.0.2",
+      "resolved": "https://registry.npmjs.org/@iconify/utils/-/utils-3.0.2.tgz",
+      "integrity": "sha512-EfJS0rLfVuRuJRn4psJHtK2A9TqVnkxPpHY6lYHiB9+8eSuudsxbwMiavocG45ujOo6FJ+CIRlRnlOGinzkaGQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@antfu/install-pkg": "^1.1.0",
+        "@antfu/utils": "^9.2.0",
+        "@iconify/types": "^2.0.0",
+        "debug": "^4.4.1",
+        "globals": "^15.15.0",
+        "kolorist": "^1.8.0",
+        "local-pkg": "^1.1.1",
+        "mlly": "^1.7.4"
+      }
+    },
+    "node_modules/@iconify/utils/node_modules/globals": {
+      "version": "15.15.0",
+      "resolved": "https://registry.npmjs.org/globals/-/globals-15.15.0.tgz",
+      "integrity": "sha512-7ACyT3wmyp3I61S4fG682L0VA2RGD9otkqGJIwNUMF1SWUombIIk+af1unuDYgMm082aHYwD+mzJvv9Iu8dsgg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
     "node_modules/@icons-pack/react-simple-icons": {
       "version": "12.3.0",
       "resolved": "https://registry.npmjs.org/@icons-pack/react-simple-icons/-/react-simple-icons-12.3.0.tgz",
@@ -1026,10 +1129,20 @@
         "react": "^16.13 || ^17 || ^18 || ^19"
       }
     },
+    "node_modules/@img/colour": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/@img/colour/-/colour-1.0.0.tgz",
+      "integrity": "sha512-A5P/LfWGFSl6nsckYtjw9da+19jB8hkJ6ACTGcDfEJ0aE+l2n2El7dsVM7UVHZQ9s2lmYMWlrS21YLy2IR1LUw==",
+      "license": "MIT",
+      "optional": true,
+      "engines": {
+        "node": ">=18"
+      }
+    },
     "node_modules/@img/sharp-darwin-arm64": {
-      "version": "0.34.2",
-      "resolved": "https://registry.npmjs.org/@img/sharp-darwin-arm64/-/sharp-darwin-arm64-0.34.2.tgz",
-      "integrity": "sha512-OfXHZPppddivUJnqyKoi5YVeHRkkNE2zUFT2gbpKxp/JZCFYEYubnMg+gOp6lWfasPrTS+KPosKqdI+ELYVDtg==",
+      "version": "0.34.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-darwin-arm64/-/sharp-darwin-arm64-0.34.4.tgz",
+      "integrity": "sha512-sitdlPzDVyvmINUdJle3TNHl+AG9QcwiAMsXmccqsCOMZNIdW2/7S26w0LyU8euiLVzFBL3dXPwVCq/ODnf2vA==",
       "cpu": [
         "arm64"
       ],
@@ -1045,13 +1158,13 @@
         "url": "https://opencollective.com/libvips"
       },
       "optionalDependencies": {
-        "@img/sharp-libvips-darwin-arm64": "1.1.0"
+        "@img/sharp-libvips-darwin-arm64": "1.2.3"
       }
     },
     "node_modules/@img/sharp-darwin-x64": {
-      "version": "0.34.2",
-      "resolved": "https://registry.npmjs.org/@img/sharp-darwin-x64/-/sharp-darwin-x64-0.34.2.tgz",
-      "integrity": "sha512-dYvWqmjU9VxqXmjEtjmvHnGqF8GrVjM2Epj9rJ6BUIXvk8slvNDJbhGFvIoXzkDhrJC2jUxNLz/GUjjvSzfw+g==",
+      "version": "0.34.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-darwin-x64/-/sharp-darwin-x64-0.34.4.tgz",
+      "integrity": "sha512-rZheupWIoa3+SOdF/IcUe1ah4ZDpKBGWcsPX6MT0lYniH9micvIU7HQkYTfrx5Xi8u+YqwLtxC/3vl8TQN6rMg==",
       "cpu": [
         "x64"
       ],
@@ -1067,13 +1180,13 @@
         "url": "https://opencollective.com/libvips"
       },
       "optionalDependencies": {
-        "@img/sharp-libvips-darwin-x64": "1.1.0"
+        "@img/sharp-libvips-darwin-x64": "1.2.3"
       }
     },
     "node_modules/@img/sharp-libvips-darwin-arm64": {
-      "version": "1.1.0",
-      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-darwin-arm64/-/sharp-libvips-darwin-arm64-1.1.0.tgz",
-      "integrity": "sha512-HZ/JUmPwrJSoM4DIQPv/BfNh9yrOA8tlBbqbLz4JZ5uew2+o22Ik+tHQJcih7QJuSa0zo5coHTfD5J8inqj9DA==",
+      "version": "1.2.3",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-darwin-arm64/-/sharp-libvips-darwin-arm64-1.2.3.tgz",
+      "integrity": "sha512-QzWAKo7kpHxbuHqUC28DZ9pIKpSi2ts2OJnoIGI26+HMgq92ZZ4vk8iJd4XsxN+tYfNJxzH6W62X5eTcsBymHw==",
       "cpu": [
         "arm64"
       ],
@@ -1087,9 +1200,9 @@
       }
     },
     "node_modules/@img/sharp-libvips-darwin-x64": {
-      "version": "1.1.0",
-      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-darwin-x64/-/sharp-libvips-darwin-x64-1.1.0.tgz",
-      "integrity": "sha512-Xzc2ToEmHN+hfvsl9wja0RlnXEgpKNmftriQp6XzY/RaSfwD9th+MSh0WQKzUreLKKINb3afirxW7A0fz2YWuQ==",
+      "version": "1.2.3",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-darwin-x64/-/sharp-libvips-darwin-x64-1.2.3.tgz",
+      "integrity": "sha512-Ju+g2xn1E2AKO6YBhxjj+ACcsPQRHT0bhpglxcEf+3uyPY+/gL8veniKoo96335ZaPo03bdDXMv0t+BBFAbmRA==",
       "cpu": [
         "x64"
       ],
@@ -1103,9 +1216,9 @@
       }
     },
     "node_modules/@img/sharp-libvips-linux-arm": {
-      "version": "1.1.0",
-      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-arm/-/sharp-libvips-linux-arm-1.1.0.tgz",
-      "integrity": "sha512-s8BAd0lwUIvYCJyRdFqvsj+BJIpDBSxs6ivrOPm/R7piTs5UIwY5OjXrP2bqXC9/moGsyRa37eYWYCOGVXxVrA==",
+      "version": "1.2.3",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-arm/-/sharp-libvips-linux-arm-1.2.3.tgz",
+      "integrity": "sha512-x1uE93lyP6wEwGvgAIV0gP6zmaL/a0tGzJs/BIDDG0zeBhMnuUPm7ptxGhUbcGs4okDJrk4nxgrmxpib9g6HpA==",
       "cpu": [
         "arm"
       ],
@@ -1119,9 +1232,9 @@
       }
     },
     "node_modules/@img/sharp-libvips-linux-arm64": {
-      "version": "1.1.0",
-      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-arm64/-/sharp-libvips-linux-arm64-1.1.0.tgz",
-      "integrity": "sha512-IVfGJa7gjChDET1dK9SekxFFdflarnUB8PwW8aGwEoF3oAsSDuNUTYS+SKDOyOJxQyDC1aPFMuRYLoDInyV9Ew==",
+      "version": "1.2.3",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-arm64/-/sharp-libvips-linux-arm64-1.2.3.tgz",
+      "integrity": "sha512-I4RxkXU90cpufazhGPyVujYwfIm9Nk1QDEmiIsaPwdnm013F7RIceaCc87kAH+oUB1ezqEvC6ga4m7MSlqsJvQ==",
       "cpu": [
         "arm64"
       ],
@@ -1135,9 +1248,9 @@
       }
     },
     "node_modules/@img/sharp-libvips-linux-ppc64": {
-      "version": "1.1.0",
-      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-ppc64/-/sharp-libvips-linux-ppc64-1.1.0.tgz",
-      "integrity": "sha512-tiXxFZFbhnkWE2LA8oQj7KYR+bWBkiV2nilRldT7bqoEZ4HiDOcePr9wVDAZPi/Id5fT1oY9iGnDq20cwUz8lQ==",
+      "version": "1.2.3",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-ppc64/-/sharp-libvips-linux-ppc64-1.2.3.tgz",
+      "integrity": "sha512-Y2T7IsQvJLMCBM+pmPbM3bKT/yYJvVtLJGfCs4Sp95SjvnFIjynbjzsa7dY1fRJX45FTSfDksbTp6AGWudiyCg==",
       "cpu": [
         "ppc64"
       ],
@@ -1151,9 +1264,9 @@
       }
     },
     "node_modules/@img/sharp-libvips-linux-s390x": {
-      "version": "1.1.0",
-      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-s390x/-/sharp-libvips-linux-s390x-1.1.0.tgz",
-      "integrity": "sha512-xukSwvhguw7COyzvmjydRb3x/09+21HykyapcZchiCUkTThEQEOMtBj9UhkaBRLuBrgLFzQ2wbxdeCCJW/jgJA==",
+      "version": "1.2.3",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-s390x/-/sharp-libvips-linux-s390x-1.2.3.tgz",
+      "integrity": "sha512-RgWrs/gVU7f+K7P+KeHFaBAJlNkD1nIZuVXdQv6S+fNA6syCcoboNjsV2Pou7zNlVdNQoQUpQTk8SWDHUA3y/w==",
       "cpu": [
         "s390x"
       ],
@@ -1167,9 +1280,9 @@
       }
     },
     "node_modules/@img/sharp-libvips-linux-x64": {
-      "version": "1.1.0",
-      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-x64/-/sharp-libvips-linux-x64-1.1.0.tgz",
-      "integrity": "sha512-yRj2+reB8iMg9W5sULM3S74jVS7zqSzHG3Ol/twnAAkAhnGQnpjj6e4ayUz7V+FpKypwgs82xbRdYtchTTUB+Q==",
+      "version": "1.2.3",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-x64/-/sharp-libvips-linux-x64-1.2.3.tgz",
+      "integrity": "sha512-3JU7LmR85K6bBiRzSUc/Ff9JBVIFVvq6bomKE0e63UXGeRw2HPVEjoJke1Yx+iU4rL7/7kUjES4dZ/81Qjhyxg==",
       "cpu": [
         "x64"
       ],
@@ -1183,9 +1296,9 @@
       }
     },
     "node_modules/@img/sharp-libvips-linuxmusl-arm64": {
-      "version": "1.1.0",
-      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linuxmusl-arm64/-/sharp-libvips-linuxmusl-arm64-1.1.0.tgz",
-      "integrity": "sha512-jYZdG+whg0MDK+q2COKbYidaqW/WTz0cc1E+tMAusiDygrM4ypmSCjOJPmFTvHHJ8j/6cAGyeDWZOsK06tP33w==",
+      "version": "1.2.3",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linuxmusl-arm64/-/sharp-libvips-linuxmusl-arm64-1.2.3.tgz",
+      "integrity": "sha512-F9q83RZ8yaCwENw1GieztSfj5msz7GGykG/BA+MOUefvER69K/ubgFHNeSyUu64amHIYKGDs4sRCMzXVj8sEyw==",
       "cpu": [
         "arm64"
       ],
@@ -1199,9 +1312,9 @@
       }
     },
     "node_modules/@img/sharp-libvips-linuxmusl-x64": {
-      "version": "1.1.0",
-      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linuxmusl-x64/-/sharp-libvips-linuxmusl-x64-1.1.0.tgz",
-      "integrity": "sha512-wK7SBdwrAiycjXdkPnGCPLjYb9lD4l6Ze2gSdAGVZrEL05AOUJESWU2lhlC+Ffn5/G+VKuSm6zzbQSzFX/P65A==",
+      "version": "1.2.3",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linuxmusl-x64/-/sharp-libvips-linuxmusl-x64-1.2.3.tgz",
+      "integrity": "sha512-U5PUY5jbc45ANM6tSJpsgqmBF/VsL6LnxJmIf11kB7J5DctHgqm0SkuXzVWtIY90GnJxKnC/JT251TDnk1fu/g==",
       "cpu": [
         "x64"
       ],
@@ -1215,9 +1328,9 @@
       }
     },
     "node_modules/@img/sharp-linux-arm": {
-      "version": "0.34.2",
-      "resolved": "https://registry.npmjs.org/@img/sharp-linux-arm/-/sharp-linux-arm-0.34.2.tgz",
-      "integrity": "sha512-0DZzkvuEOqQUP9mo2kjjKNok5AmnOr1jB2XYjkaoNRwpAYMDzRmAqUIa1nRi58S2WswqSfPOWLNOr0FDT3H5RQ==",
+      "version": "0.34.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-linux-arm/-/sharp-linux-arm-0.34.4.tgz",
+      "integrity": "sha512-Xyam4mlqM0KkTHYVSuc6wXRmM7LGN0P12li03jAnZ3EJWZqj83+hi8Y9UxZUbxsgsK1qOEwg7O0Bc0LjqQVtxA==",
       "cpu": [
         "arm"
       ],
@@ -1233,13 +1346,13 @@
         "url": "https://opencollective.com/libvips"
       },
       "optionalDependencies": {
-        "@img/sharp-libvips-linux-arm": "1.1.0"
+        "@img/sharp-libvips-linux-arm": "1.2.3"
       }
     },
     "node_modules/@img/sharp-linux-arm64": {
-      "version": "0.34.2",
-      "resolved": "https://registry.npmjs.org/@img/sharp-linux-arm64/-/sharp-linux-arm64-0.34.2.tgz",
-      "integrity": "sha512-D8n8wgWmPDakc83LORcfJepdOSN6MvWNzzz2ux0MnIbOqdieRZwVYY32zxVx+IFUT8er5KPcyU3XXsn+GzG/0Q==",
+      "version": "0.34.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-linux-arm64/-/sharp-linux-arm64-0.34.4.tgz",
+      "integrity": "sha512-YXU1F/mN/Wu786tl72CyJjP/Ngl8mGHN1hST4BGl+hiW5jhCnV2uRVTNOcaYPs73NeT/H8Upm3y9582JVuZHrQ==",
       "cpu": [
         "arm64"
       ],
@@ -1255,13 +1368,35 @@
         "url": "https://opencollective.com/libvips"
       },
       "optionalDependencies": {
-        "@img/sharp-libvips-linux-arm64": "1.1.0"
+        "@img/sharp-libvips-linux-arm64": "1.2.3"
+      }
+    },
+    "node_modules/@img/sharp-linux-ppc64": {
+      "version": "0.34.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-linux-ppc64/-/sharp-linux-ppc64-0.34.4.tgz",
+      "integrity": "sha512-F4PDtF4Cy8L8hXA2p3TO6s4aDt93v+LKmpcYFLAVdkkD3hSxZzee0rh6/+94FpAynsuMpLX5h+LRsSG3rIciUQ==",
+      "cpu": [
+        "ppc64"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      },
+      "optionalDependencies": {
+        "@img/sharp-libvips-linux-ppc64": "1.2.3"
       }
     },
     "node_modules/@img/sharp-linux-s390x": {
-      "version": "0.34.2",
-      "resolved": "https://registry.npmjs.org/@img/sharp-linux-s390x/-/sharp-linux-s390x-0.34.2.tgz",
-      "integrity": "sha512-EGZ1xwhBI7dNISwxjChqBGELCWMGDvmxZXKjQRuqMrakhO8QoMgqCrdjnAqJq/CScxfRn+Bb7suXBElKQpPDiw==",
+      "version": "0.34.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-linux-s390x/-/sharp-linux-s390x-0.34.4.tgz",
+      "integrity": "sha512-qVrZKE9Bsnzy+myf7lFKvng6bQzhNUAYcVORq2P7bDlvmF6u2sCmK2KyEQEBdYk+u3T01pVsPrkj943T1aJAsw==",
       "cpu": [
         "s390x"
       ],
@@ -1277,13 +1412,13 @@
         "url": "https://opencollective.com/libvips"
       },
       "optionalDependencies": {
-        "@img/sharp-libvips-linux-s390x": "1.1.0"
+        "@img/sharp-libvips-linux-s390x": "1.2.3"
       }
     },
     "node_modules/@img/sharp-linux-x64": {
-      "version": "0.34.2",
-      "resolved": "https://registry.npmjs.org/@img/sharp-linux-x64/-/sharp-linux-x64-0.34.2.tgz",
-      "integrity": "sha512-sD7J+h5nFLMMmOXYH4DD9UtSNBD05tWSSdWAcEyzqW8Cn5UxXvsHAxmxSesYUsTOBmUnjtxghKDl15EvfqLFbQ==",
+      "version": "0.34.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-linux-x64/-/sharp-linux-x64-0.34.4.tgz",
+      "integrity": "sha512-ZfGtcp2xS51iG79c6Vhw9CWqQC8l2Ot8dygxoDoIQPTat/Ov3qAa8qpxSrtAEAJW+UjTXc4yxCjNfxm4h6Xm2A==",
       "cpu": [
         "x64"
       ],
@@ -1299,13 +1434,13 @@
         "url": "https://opencollective.com/libvips"
       },
       "optionalDependencies": {
-        "@img/sharp-libvips-linux-x64": "1.1.0"
+        "@img/sharp-libvips-linux-x64": "1.2.3"
       }
     },
     "node_modules/@img/sharp-linuxmusl-arm64": {
-      "version": "0.34.2",
-      "resolved": "https://registry.npmjs.org/@img/sharp-linuxmusl-arm64/-/sharp-linuxmusl-arm64-0.34.2.tgz",
-      "integrity": "sha512-NEE2vQ6wcxYav1/A22OOxoSOGiKnNmDzCYFOZ949xFmrWZOVII1Bp3NqVVpvj+3UeHMFyN5eP/V5hzViQ5CZNA==",
+      "version": "0.34.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-linuxmusl-arm64/-/sharp-linuxmusl-arm64-0.34.4.tgz",
+      "integrity": "sha512-8hDVvW9eu4yHWnjaOOR8kHVrew1iIX+MUgwxSuH2XyYeNRtLUe4VNioSqbNkB7ZYQJj9rUTT4PyRscyk2PXFKA==",
       "cpu": [
         "arm64"
       ],
@@ -1321,13 +1456,13 @@
         "url": "https://opencollective.com/libvips"
       },
       "optionalDependencies": {
-        "@img/sharp-libvips-linuxmusl-arm64": "1.1.0"
+        "@img/sharp-libvips-linuxmusl-arm64": "1.2.3"
       }
     },
     "node_modules/@img/sharp-linuxmusl-x64": {
-      "version": "0.34.2",
-      "resolved": "https://registry.npmjs.org/@img/sharp-linuxmusl-x64/-/sharp-linuxmusl-x64-0.34.2.tgz",
-      "integrity": "sha512-DOYMrDm5E6/8bm/yQLCWyuDJwUnlevR8xtF8bs+gjZ7cyUNYXiSf/E8Kp0Ss5xasIaXSHzb888V1BE4i1hFhAA==",
+      "version": "0.34.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-linuxmusl-x64/-/sharp-linuxmusl-x64-0.34.4.tgz",
+      "integrity": "sha512-lU0aA5L8QTlfKjpDCEFOZsTYGn3AEiO6db8W5aQDxj0nQkVrZWmN3ZP9sYKWJdtq3PWPhUNlqehWyXpYDcI9Sg==",
       "cpu": [
         "x64"
       ],
@@ -1343,20 +1478,20 @@
         "url": "https://opencollective.com/libvips"
       },
       "optionalDependencies": {
-        "@img/sharp-libvips-linuxmusl-x64": "1.1.0"
+        "@img/sharp-libvips-linuxmusl-x64": "1.2.3"
       }
     },
     "node_modules/@img/sharp-wasm32": {
-      "version": "0.34.2",
-      "resolved": "https://registry.npmjs.org/@img/sharp-wasm32/-/sharp-wasm32-0.34.2.tgz",
-      "integrity": "sha512-/VI4mdlJ9zkaq53MbIG6rZY+QRN3MLbR6usYlgITEzi4Rpx5S6LFKsycOQjkOGmqTNmkIdLjEvooFKwww6OpdQ==",
+      "version": "0.34.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-wasm32/-/sharp-wasm32-0.34.4.tgz",
+      "integrity": "sha512-33QL6ZO/qpRyG7woB/HUALz28WnTMI2W1jgX3Nu2bypqLIKx/QKMILLJzJjI+SIbvXdG9fUnmrxR7vbi1sTBeA==",
       "cpu": [
         "wasm32"
       ],
       "license": "Apache-2.0 AND LGPL-3.0-or-later AND MIT",
       "optional": true,
       "dependencies": {
-        "@emnapi/runtime": "^1.4.3"
+        "@emnapi/runtime": "^1.5.0"
       },
       "engines": {
         "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
@@ -1366,9 +1501,9 @@
       }
     },
     "node_modules/@img/sharp-win32-arm64": {
-      "version": "0.34.2",
-      "resolved": "https://registry.npmjs.org/@img/sharp-win32-arm64/-/sharp-win32-arm64-0.34.2.tgz",
-      "integrity": "sha512-cfP/r9FdS63VA5k0xiqaNaEoGxBg9k7uE+RQGzuK9fHt7jib4zAVVseR9LsE4gJcNWgT6APKMNnCcnyOtmSEUQ==",
+      "version": "0.34.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-win32-arm64/-/sharp-win32-arm64-0.34.4.tgz",
+      "integrity": "sha512-2Q250do/5WXTwxW3zjsEuMSv5sUU4Tq9VThWKlU2EYLm4MB7ZeMwF+SFJutldYODXF6jzc6YEOC+VfX0SZQPqA==",
       "cpu": [
         "arm64"
       ],
@@ -1385,9 +1520,9 @@
       }
     },
     "node_modules/@img/sharp-win32-ia32": {
-      "version": "0.34.2",
-      "resolved": "https://registry.npmjs.org/@img/sharp-win32-ia32/-/sharp-win32-ia32-0.34.2.tgz",
-      "integrity": "sha512-QLjGGvAbj0X/FXl8n1WbtQ6iVBpWU7JO94u/P2M4a8CFYsvQi4GW2mRy/JqkRx0qpBzaOdKJKw8uc930EX2AHw==",
+      "version": "0.34.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-win32-ia32/-/sharp-win32-ia32-0.34.4.tgz",
+      "integrity": "sha512-3ZeLue5V82dT92CNL6rsal6I2weKw1cYu+rGKm8fOCCtJTR2gYeUfY3FqUnIJsMUPIH68oS5jmZ0NiJ508YpEw==",
       "cpu": [
         "ia32"
       ],
@@ -1404,9 +1539,9 @@
       }
     },
     "node_modules/@img/sharp-win32-x64": {
-      "version": "0.34.2",
-      "resolved": "https://registry.npmjs.org/@img/sharp-win32-x64/-/sharp-win32-x64-0.34.2.tgz",
-      "integrity": "sha512-aUdT6zEYtDKCaxkofmmJDJYGCf0+pJg3eU9/oBuqvEeoB9dKI6ZLc/1iLJCTuJQDO4ptntAlkUmHgGjyuobZbw==",
+      "version": "0.34.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-win32-x64/-/sharp-win32-x64-0.34.4.tgz",
+      "integrity": "sha512-xIyj4wpYs8J18sVN3mSQjwrw7fKUqRw+Z5rnHNCy5fYTxigBz81u5mOMPmFumwjcn8+ld1ppptMBCLic1nz6ig==",
       "cpu": [
         "x64"
       ],
@@ -1589,10 +1724,19 @@
         "url": "https://opencollective.com/unified"
       }
     },
+    "node_modules/@mermaid-js/parser": {
+      "version": "0.6.2",
+      "resolved": "https://registry.npmjs.org/@mermaid-js/parser/-/parser-0.6.2.tgz",
+      "integrity": "sha512-+PO02uGF6L6Cs0Bw8RpGhikVvMWEysfAyl27qTlroUB8jSWr1lL0Sf6zi78ZxlSnmgSY2AMMKVgghnN9jTtwkQ==",
+      "license": "MIT",
+      "dependencies": {
+        "langium": "3.3.1"
+      }
+    },
     "node_modules/@next/env": {
-      "version": "15.3.2",
-      "resolved": "https://registry.npmjs.org/@next/env/-/env-15.3.2.tgz",
-      "integrity": "sha512-xURk++7P7qR9JG1jJtLzPzf0qEvqCN0A/T3DXf8IPMKo9/6FfjxtEffRJIIew/bIL4T3C2jLLqBor8B/zVlx6g==",
+      "version": "15.5.4",
+      "resolved": "https://registry.npmjs.org/@next/env/-/env-15.5.4.tgz",
+      "integrity": "sha512-27SQhYp5QryzIT5uO8hq99C69eLQ7qkzkDPsk3N+GuS2XgOgoYEeOav7Pf8Tn4drECOVDsDg8oj+/DVy8qQL2A==",
       "license": "MIT"
     },
     "node_modules/@next/eslint-plugin-next": {
@@ -1605,9 +1749,9 @@
       }
     },
     "node_modules/@next/swc-darwin-arm64": {
-      "version": "15.3.2",
-      "resolved": "https://registry.npmjs.org/@next/swc-darwin-arm64/-/swc-darwin-arm64-15.3.2.tgz",
-      "integrity": "sha512-2DR6kY/OGcokbnCsjHpNeQblqCZ85/1j6njYSkzRdpLn5At7OkSdmk7WyAmB9G0k25+VgqVZ/u356OSoQZ3z0g==",
+      "version": "15.5.4",
+      "resolved": "https://registry.npmjs.org/@next/swc-darwin-arm64/-/swc-darwin-arm64-15.5.4.tgz",
+      "integrity": "sha512-nopqz+Ov6uvorej8ndRX6HlxCYWCO3AHLfKK2TYvxoSB2scETOcfm/HSS3piPqc3A+MUgyHoqE6je4wnkjfrOA==",
       "cpu": [
         "arm64"
       ],
@@ -1621,9 +1765,9 @@
       }
     },
     "node_modules/@next/swc-darwin-x64": {
-      "version": "15.3.2",
-      "resolved": "https://registry.npmjs.org/@next/swc-darwin-x64/-/swc-darwin-x64-15.3.2.tgz",
-      "integrity": "sha512-ro/fdqaZWL6k1S/5CLv1I0DaZfDVJkWNaUU3un8Lg6m0YENWlDulmIWzV96Iou2wEYyEsZq51mwV8+XQXqMp3w==",
+      "version": "15.5.4",
+      "resolved": "https://registry.npmjs.org/@next/swc-darwin-x64/-/swc-darwin-x64-15.5.4.tgz",
+      "integrity": "sha512-QOTCFq8b09ghfjRJKfb68kU9k2K+2wsC4A67psOiMn849K9ZXgCSRQr0oVHfmKnoqCbEmQWG1f2h1T2vtJJ9mA==",
       "cpu": [
         "x64"
       ],
@@ -1637,9 +1781,9 @@
       }
     },
     "node_modules/@next/swc-linux-arm64-gnu": {
-      "version": "15.3.2",
-      "resolved": "https://registry.npmjs.org/@next/swc-linux-arm64-gnu/-/swc-linux-arm64-gnu-15.3.2.tgz",
-      "integrity": "sha512-covwwtZYhlbRWK2HlYX9835qXum4xYZ3E2Mra1mdQ+0ICGoMiw1+nVAn4d9Bo7R3JqSmK1grMq/va+0cdh7bJA==",
+      "version": "15.5.4",
+      "resolved": "https://registry.npmjs.org/@next/swc-linux-arm64-gnu/-/swc-linux-arm64-gnu-15.5.4.tgz",
+      "integrity": "sha512-eRD5zkts6jS3VfE/J0Kt1VxdFqTnMc3QgO5lFE5GKN3KDI/uUpSyK3CjQHmfEkYR4wCOl0R0XrsjpxfWEA++XA==",
       "cpu": [
         "arm64"
       ],
@@ -1653,9 +1797,9 @@
       }
     },
     "node_modules/@next/swc-linux-arm64-musl": {
-      "version": "15.3.2",
-      "resolved": "https://registry.npmjs.org/@next/swc-linux-arm64-musl/-/swc-linux-arm64-musl-15.3.2.tgz",
-      "integrity": "sha512-KQkMEillvlW5Qk5mtGA/3Yz0/tzpNlSw6/3/ttsV1lNtMuOHcGii3zVeXZyi4EJmmLDKYcTcByV2wVsOhDt/zg==",
+      "version": "15.5.4",
+      "resolved": "https://registry.npmjs.org/@next/swc-linux-arm64-musl/-/swc-linux-arm64-musl-15.5.4.tgz",
+      "integrity": "sha512-TOK7iTxmXFc45UrtKqWdZ1shfxuL4tnVAOuuJK4S88rX3oyVV4ZkLjtMT85wQkfBrOOvU55aLty+MV8xmcJR8A==",
       "cpu": [
         "arm64"
       ],
@@ -1669,9 +1813,9 @@
       }
     },
     "node_modules/@next/swc-linux-x64-gnu": {
-      "version": "15.3.2",
-      "resolved": "https://registry.npmjs.org/@next/swc-linux-x64-gnu/-/swc-linux-x64-gnu-15.3.2.tgz",
-      "integrity": "sha512-uRBo6THWei0chz+Y5j37qzx+BtoDRFIkDzZjlpCItBRXyMPIg079eIkOCl3aqr2tkxL4HFyJ4GHDes7W8HuAUg==",
+      "version": "15.5.4",
+      "resolved": "https://registry.npmjs.org/@next/swc-linux-x64-gnu/-/swc-linux-x64-gnu-15.5.4.tgz",
+      "integrity": "sha512-7HKolaj+481FSW/5lL0BcTkA4Ueam9SPYWyN/ib/WGAFZf0DGAN8frNpNZYFHtM4ZstrHZS3LY3vrwlIQfsiMA==",
       "cpu": [
         "x64"
       ],
@@ -1685,9 +1829,9 @@
       }
     },
     "node_modules/@next/swc-linux-x64-musl": {
-      "version": "15.3.2",
-      "resolved": "https://registry.npmjs.org/@next/swc-linux-x64-musl/-/swc-linux-x64-musl-15.3.2.tgz",
-      "integrity": "sha512-+uxFlPuCNx/T9PdMClOqeE8USKzj8tVz37KflT3Kdbx/LOlZBRI2yxuIcmx1mPNK8DwSOMNCr4ureSet7eyC0w==",
+      "version": "15.5.4",
+      "resolved": "https://registry.npmjs.org/@next/swc-linux-x64-musl/-/swc-linux-x64-musl-15.5.4.tgz",
+      "integrity": "sha512-nlQQ6nfgN0nCO/KuyEUwwOdwQIGjOs4WNMjEUtpIQJPR2NUfmGpW2wkJln1d4nJ7oUzd1g4GivH5GoEPBgfsdw==",
       "cpu": [
         "x64"
       ],
@@ -1701,9 +1845,9 @@
       }
     },
     "node_modules/@next/swc-win32-arm64-msvc": {
-      "version": "15.3.2",
-      "resolved": "https://registry.npmjs.org/@next/swc-win32-arm64-msvc/-/swc-win32-arm64-msvc-15.3.2.tgz",
-      "integrity": "sha512-LLTKmaI5cfD8dVzh5Vt7+OMo+AIOClEdIU/TSKbXXT2iScUTSxOGoBhfuv+FU8R9MLmrkIL1e2fBMkEEjYAtPQ==",
+      "version": "15.5.4",
+      "resolved": "https://registry.npmjs.org/@next/swc-win32-arm64-msvc/-/swc-win32-arm64-msvc-15.5.4.tgz",
+      "integrity": "sha512-PcR2bN7FlM32XM6eumklmyWLLbu2vs+D7nJX8OAIoWy69Kef8mfiN4e8TUv2KohprwifdpFKPzIP1njuCjD0YA==",
       "cpu": [
         "arm64"
       ],
@@ -1717,9 +1861,9 @@
       }
     },
     "node_modules/@next/swc-win32-x64-msvc": {
-      "version": "15.3.2",
-      "resolved": "https://registry.npmjs.org/@next/swc-win32-x64-msvc/-/swc-win32-x64-msvc-15.3.2.tgz",
-      "integrity": "sha512-aW5B8wOPioJ4mBdMDXkt5f3j8pUr9W8AnlX0Df35uRWNT1Y6RIybxjnSUe+PhM+M1bwgyY8PHLmXZC6zT1o5tA==",
+      "version": "15.5.4",
+      "resolved": "https://registry.npmjs.org/@next/swc-win32-x64-msvc/-/swc-win32-x64-msvc-15.5.4.tgz",
+      "integrity": "sha512-1ur2tSHZj8Px/KMAthmuI9FMp/YFusMMGoRNJaRZMOlSkgvLjzosSdQI0cJAKogdHl3qXUQKL9MGaYvKwA7DXg==",
       "cpu": [
         "x64"
       ],
@@ -2902,11 +3046,6 @@
       "resolved": "https://registry.npmjs.org/@standard-schema/spec/-/spec-1.0.0.tgz",
       "integrity": "sha512-m2bOd0f2RT9k8QJx1JN85cZYyH1RqFBdlwtkSlf4tBDYLCiiZnv1fIIwacK6cqwXavOydf0NPToMQgpKq+dVlA=="
     },
-    "node_modules/@swc/counter": {
-      "version": "0.1.3",
-      "resolved": "https://registry.npmjs.org/@swc/counter/-/counter-0.1.3.tgz",
-      "integrity": "sha512-e2BR4lsJkkRlKZ/qCHPw9ZaSxc0MVUd7gtbtaB7aMvHeJVYe8sOB8DBZkP2DtISHGSku9sCK6T6cnY0CtXrOCQ=="
-    },
     "node_modules/@swc/helpers": {
       "version": "0.5.15",
       "resolved": "https://registry.npmjs.org/@swc/helpers/-/helpers-0.5.15.tgz",
@@ -3243,6 +3382,259 @@
         "@types/node": "*"
       }
     },
+    "node_modules/@types/d3": {
+      "version": "7.4.3",
+      "resolved": "https://registry.npmjs.org/@types/d3/-/d3-7.4.3.tgz",
+      "integrity": "sha512-lZXZ9ckh5R8uiFVt8ogUNf+pIrK4EsWrx2Np75WvF/eTpJ0FMHNhjXk8CKEx/+gpHbNQyJWehbFaTvqmHWB3ww==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/d3-array": "*",
+        "@types/d3-axis": "*",
+        "@types/d3-brush": "*",
+        "@types/d3-chord": "*",
+        "@types/d3-color": "*",
+        "@types/d3-contour": "*",
+        "@types/d3-delaunay": "*",
+        "@types/d3-dispatch": "*",
+        "@types/d3-drag": "*",
+        "@types/d3-dsv": "*",
+        "@types/d3-ease": "*",
+        "@types/d3-fetch": "*",
+        "@types/d3-force": "*",
+        "@types/d3-format": "*",
+        "@types/d3-geo": "*",
+        "@types/d3-hierarchy": "*",
+        "@types/d3-interpolate": "*",
+        "@types/d3-path": "*",
+        "@types/d3-polygon": "*",
+        "@types/d3-quadtree": "*",
+        "@types/d3-random": "*",
+        "@types/d3-scale": "*",
+        "@types/d3-scale-chromatic": "*",
+        "@types/d3-selection": "*",
+        "@types/d3-shape": "*",
+        "@types/d3-time": "*",
+        "@types/d3-time-format": "*",
+        "@types/d3-timer": "*",
+        "@types/d3-transition": "*",
+        "@types/d3-zoom": "*"
+      }
+    },
+    "node_modules/@types/d3-array": {
+      "version": "3.2.2",
+      "resolved": "https://registry.npmjs.org/@types/d3-array/-/d3-array-3.2.2.tgz",
+      "integrity": "sha512-hOLWVbm7uRza0BYXpIIW5pxfrKe0W+D5lrFiAEYR+pb6w3N2SwSMaJbXdUfSEv+dT4MfHBLtn5js0LAWaO6otw==",
+      "license": "MIT"
+    },
+    "node_modules/@types/d3-axis": {
+      "version": "3.0.6",
+      "resolved": "https://registry.npmjs.org/@types/d3-axis/-/d3-axis-3.0.6.tgz",
+      "integrity": "sha512-pYeijfZuBd87T0hGn0FO1vQ/cgLk6E1ALJjfkC0oJ8cbwkZl3TpgS8bVBLZN+2jjGgg38epgxb2zmoGtSfvgMw==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/d3-selection": "*"
+      }
+    },
+    "node_modules/@types/d3-brush": {
+      "version": "3.0.6",
+      "resolved": "https://registry.npmjs.org/@types/d3-brush/-/d3-brush-3.0.6.tgz",
+      "integrity": "sha512-nH60IZNNxEcrh6L1ZSMNA28rj27ut/2ZmI3r96Zd+1jrZD++zD3LsMIjWlvg4AYrHn/Pqz4CF3veCxGjtbqt7A==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/d3-selection": "*"
+      }
+    },
+    "node_modules/@types/d3-chord": {
+      "version": "3.0.6",
+      "resolved": "https://registry.npmjs.org/@types/d3-chord/-/d3-chord-3.0.6.tgz",
+      "integrity": "sha512-LFYWWd8nwfwEmTZG9PfQxd17HbNPksHBiJHaKuY1XeqscXacsS2tyoo6OdRsjf+NQYeB6XrNL3a25E3gH69lcg==",
+      "license": "MIT"
+    },
+    "node_modules/@types/d3-color": {
+      "version": "3.1.3",
+      "resolved": "https://registry.npmjs.org/@types/d3-color/-/d3-color-3.1.3.tgz",
+      "integrity": "sha512-iO90scth9WAbmgv7ogoq57O9YpKmFBbmoEoCHDB2xMBY0+/KVrqAaCDyCE16dUspeOvIxFFRI+0sEtqDqy2b4A==",
+      "license": "MIT"
+    },
+    "node_modules/@types/d3-contour": {
+      "version": "3.0.6",
+      "resolved": "https://registry.npmjs.org/@types/d3-contour/-/d3-contour-3.0.6.tgz",
+      "integrity": "sha512-BjzLgXGnCWjUSYGfH1cpdo41/hgdWETu4YxpezoztawmqsvCeep+8QGfiY6YbDvfgHz/DkjeIkkZVJavB4a3rg==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/d3-array": "*",
+        "@types/geojson": "*"
+      }
+    },
+    "node_modules/@types/d3-delaunay": {
+      "version": "6.0.4",
+      "resolved": "https://registry.npmjs.org/@types/d3-delaunay/-/d3-delaunay-6.0.4.tgz",
+      "integrity": "sha512-ZMaSKu4THYCU6sV64Lhg6qjf1orxBthaC161plr5KuPHo3CNm8DTHiLw/5Eq2b6TsNP0W0iJrUOFscY6Q450Hw==",
+      "license": "MIT"
+    },
+    "node_modules/@types/d3-dispatch": {
+      "version": "3.0.7",
+      "resolved": "https://registry.npmjs.org/@types/d3-dispatch/-/d3-dispatch-3.0.7.tgz",
+      "integrity": "sha512-5o9OIAdKkhN1QItV2oqaE5KMIiXAvDWBDPrD85e58Qlz1c1kI/J0NcqbEG88CoTwJrYe7ntUCVfeUl2UJKbWgA==",
+      "license": "MIT"
+    },
+    "node_modules/@types/d3-drag": {
+      "version": "3.0.7",
+      "resolved": "https://registry.npmjs.org/@types/d3-drag/-/d3-drag-3.0.7.tgz",
+      "integrity": "sha512-HE3jVKlzU9AaMazNufooRJ5ZpWmLIoc90A37WU2JMmeq28w1FQqCZswHZ3xR+SuxYftzHq6WU6KJHvqxKzTxxQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/d3-selection": "*"
+      }
+    },
+    "node_modules/@types/d3-dsv": {
+      "version": "3.0.7",
+      "resolved": "https://registry.npmjs.org/@types/d3-dsv/-/d3-dsv-3.0.7.tgz",
+      "integrity": "sha512-n6QBF9/+XASqcKK6waudgL0pf/S5XHPPI8APyMLLUHd8NqouBGLsU8MgtO7NINGtPBtk9Kko/W4ea0oAspwh9g==",
+      "license": "MIT"
+    },
+    "node_modules/@types/d3-ease": {
+      "version": "3.0.2",
+      "resolved": "https://registry.npmjs.org/@types/d3-ease/-/d3-ease-3.0.2.tgz",
+      "integrity": "sha512-NcV1JjO5oDzoK26oMzbILE6HW7uVXOHLQvHshBUW4UMdZGfiY6v5BeQwh9a9tCzv+CeefZQHJt5SRgK154RtiA==",
+      "license": "MIT"
+    },
+    "node_modules/@types/d3-fetch": {
+      "version": "3.0.7",
+      "resolved": "https://registry.npmjs.org/@types/d3-fetch/-/d3-fetch-3.0.7.tgz",
+      "integrity": "sha512-fTAfNmxSb9SOWNB9IoG5c8Hg6R+AzUHDRlsXsDZsNp6sxAEOP0tkP3gKkNSO/qmHPoBFTxNrjDprVHDQDvo5aA==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/d3-dsv": "*"
+      }
+    },
+    "node_modules/@types/d3-force": {
+      "version": "3.0.10",
+      "resolved": "https://registry.npmjs.org/@types/d3-force/-/d3-force-3.0.10.tgz",
+      "integrity": "sha512-ZYeSaCF3p73RdOKcjj+swRlZfnYpK1EbaDiYICEEp5Q6sUiqFaFQ9qgoshp5CzIyyb/yD09kD9o2zEltCexlgw==",
+      "license": "MIT"
+    },
+    "node_modules/@types/d3-format": {
+      "version": "3.0.4",
+      "resolved": "https://registry.npmjs.org/@types/d3-format/-/d3-format-3.0.4.tgz",
+      "integrity": "sha512-fALi2aI6shfg7vM5KiR1wNJnZ7r6UuggVqtDA+xiEdPZQwy/trcQaHnwShLuLdta2rTymCNpxYTiMZX/e09F4g==",
+      "license": "MIT"
+    },
+    "node_modules/@types/d3-geo": {
+      "version": "3.1.0",
+      "resolved": "https://registry.npmjs.org/@types/d3-geo/-/d3-geo-3.1.0.tgz",
+      "integrity": "sha512-856sckF0oP/diXtS4jNsiQw/UuK5fQG8l/a9VVLeSouf1/PPbBE1i1W852zVwKwYCBkFJJB7nCFTbk6UMEXBOQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/geojson": "*"
+      }
+    },
+    "node_modules/@types/d3-hierarchy": {
+      "version": "3.1.7",
+      "resolved": "https://registry.npmjs.org/@types/d3-hierarchy/-/d3-hierarchy-3.1.7.tgz",
+      "integrity": "sha512-tJFtNoYBtRtkNysX1Xq4sxtjK8YgoWUNpIiUee0/jHGRwqvzYxkq0hGVbbOGSz+JgFxxRu4K8nb3YpG3CMARtg==",
+      "license": "MIT"
+    },
+    "node_modules/@types/d3-interpolate": {
+      "version": "3.0.4",
+      "resolved": "https://registry.npmjs.org/@types/d3-interpolate/-/d3-interpolate-3.0.4.tgz",
+      "integrity": "sha512-mgLPETlrpVV1YRJIglr4Ez47g7Yxjl1lj7YKsiMCb27VJH9W8NVM6Bb9d8kkpG/uAQS5AmbA48q2IAolKKo1MA==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/d3-color": "*"
+      }
+    },
+    "node_modules/@types/d3-path": {
+      "version": "3.1.1",
+      "resolved": "https://registry.npmjs.org/@types/d3-path/-/d3-path-3.1.1.tgz",
+      "integrity": "sha512-VMZBYyQvbGmWyWVea0EHs/BwLgxc+MKi1zLDCONksozI4YJMcTt8ZEuIR4Sb1MMTE8MMW49v0IwI5+b7RmfWlg==",
+      "license": "MIT"
+    },
+    "node_modules/@types/d3-polygon": {
+      "version": "3.0.2",
+      "resolved": "https://registry.npmjs.org/@types/d3-polygon/-/d3-polygon-3.0.2.tgz",
+      "integrity": "sha512-ZuWOtMaHCkN9xoeEMr1ubW2nGWsp4nIql+OPQRstu4ypeZ+zk3YKqQT0CXVe/PYqrKpZAi+J9mTs05TKwjXSRA==",
+      "license": "MIT"
+    },
+    "node_modules/@types/d3-quadtree": {
+      "version": "3.0.6",
+      "resolved": "https://registry.npmjs.org/@types/d3-quadtree/-/d3-quadtree-3.0.6.tgz",
+      "integrity": "sha512-oUzyO1/Zm6rsxKRHA1vH0NEDG58HrT5icx/azi9MF1TWdtttWl0UIUsjEQBBh+SIkrpd21ZjEv7ptxWys1ncsg==",
+      "license": "MIT"
+    },
+    "node_modules/@types/d3-random": {
+      "version": "3.0.3",
+      "resolved": "https://registry.npmjs.org/@types/d3-random/-/d3-random-3.0.3.tgz",
+      "integrity": "sha512-Imagg1vJ3y76Y2ea0871wpabqp613+8/r0mCLEBfdtqC7xMSfj9idOnmBYyMoULfHePJyxMAw3nWhJxzc+LFwQ==",
+      "license": "MIT"
+    },
+    "node_modules/@types/d3-scale": {
+      "version": "4.0.9",
+      "resolved": "https://registry.npmjs.org/@types/d3-scale/-/d3-scale-4.0.9.tgz",
+      "integrity": "sha512-dLmtwB8zkAeO/juAMfnV+sItKjlsw2lKdZVVy6LRr0cBmegxSABiLEpGVmSJJ8O08i4+sGR6qQtb6WtuwJdvVw==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/d3-time": "*"
+      }
+    },
+    "node_modules/@types/d3-scale-chromatic": {
+      "version": "3.1.0",
+      "resolved": "https://registry.npmjs.org/@types/d3-scale-chromatic/-/d3-scale-chromatic-3.1.0.tgz",
+      "integrity": "sha512-iWMJgwkK7yTRmWqRB5plb1kadXyQ5Sj8V/zYlFGMUBbIPKQScw+Dku9cAAMgJG+z5GYDoMjWGLVOvjghDEFnKQ==",
+      "license": "MIT"
+    },
+    "node_modules/@types/d3-selection": {
+      "version": "3.0.11",
+      "resolved": "https://registry.npmjs.org/@types/d3-selection/-/d3-selection-3.0.11.tgz",
+      "integrity": "sha512-bhAXu23DJWsrI45xafYpkQ4NtcKMwWnAC/vKrd2l+nxMFuvOT3XMYTIj2opv8vq8AO5Yh7Qac/nSeP/3zjTK0w==",
+      "license": "MIT"
+    },
+    "node_modules/@types/d3-shape": {
+      "version": "3.1.7",
+      "resolved": "https://registry.npmjs.org/@types/d3-shape/-/d3-shape-3.1.7.tgz",
+      "integrity": "sha512-VLvUQ33C+3J+8p+Daf+nYSOsjB4GXp19/S/aGo60m9h1v6XaxjiT82lKVWJCfzhtuZ3yD7i/TPeC/fuKLLOSmg==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/d3-path": "*"
+      }
+    },
+    "node_modules/@types/d3-time": {
+      "version": "3.0.4",
+      "resolved": "https://registry.npmjs.org/@types/d3-time/-/d3-time-3.0.4.tgz",
+      "integrity": "sha512-yuzZug1nkAAaBlBBikKZTgzCeA+k1uy4ZFwWANOfKw5z5LRhV0gNA7gNkKm7HoK+HRN0wX3EkxGk0fpbWhmB7g==",
+      "license": "MIT"
+    },
+    "node_modules/@types/d3-time-format": {
+      "version": "4.0.3",
+      "resolved": "https://registry.npmjs.org/@types/d3-time-format/-/d3-time-format-4.0.3.tgz",
+      "integrity": "sha512-5xg9rC+wWL8kdDj153qZcsJ0FWiFt0J5RB6LYUNZjwSnesfblqrI/bJ1wBdJ8OQfncgbJG5+2F+qfqnqyzYxyg==",
+      "license": "MIT"
+    },
+    "node_modules/@types/d3-timer": {
+      "version": "3.0.2",
+      "resolved": "https://registry.npmjs.org/@types/d3-timer/-/d3-timer-3.0.2.tgz",
+      "integrity": "sha512-Ps3T8E8dZDam6fUyNiMkekK3XUsaUEik+idO9/YjPtfj2qruF8tFBXS7XhtE4iIXBLxhmLjP3SXpLhVf21I9Lw==",
+      "license": "MIT"
+    },
+    "node_modules/@types/d3-transition": {
+      "version": "3.0.9",
+      "resolved": "https://registry.npmjs.org/@types/d3-transition/-/d3-transition-3.0.9.tgz",
+      "integrity": "sha512-uZS5shfxzO3rGlu0cC3bjmMFKsXv+SmZZcgp0KD22ts4uGXp5EVYGzu/0YdwZeKmddhcAccYtREJKkPfXkZuCg==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/d3-selection": "*"
+      }
+    },
+    "node_modules/@types/d3-zoom": {
+      "version": "3.0.8",
+      "resolved": "https://registry.npmjs.org/@types/d3-zoom/-/d3-zoom-3.0.8.tgz",
+      "integrity": "sha512-iqMC4/YlFCSlO8+2Ii1GGGliCAY4XdeG748w5vQUbevlbDu0zSjH/+jojorQVBK/se0j6DUFNPBGSqD3YWYnDw==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/d3-interpolate": "*",
+        "@types/d3-selection": "*"
+      }
+    },
     "node_modules/@types/debug": {
       "version": "4.1.12",
       "resolved": "https://registry.npmjs.org/@types/debug/-/debug-4.1.12.tgz",
@@ -3264,6 +3656,12 @@
         "@types/estree": "*"
       }
     },
+    "node_modules/@types/geojson": {
+      "version": "7946.0.16",
+      "resolved": "https://registry.npmjs.org/@types/geojson/-/geojson-7946.0.16.tgz",
+      "integrity": "sha512-6C8nqWur3j98U6+lXDfTUWIfgvZU+EumvpHKcYjujKH7woYyLj2sUmff0tRhrqM7BohUw7Pz3ZB1jj2gW9Fvmg==",
+      "license": "MIT"
+    },
     "node_modules/@types/hast": {
       "version": "3.0.4",
       "resolved": "https://registry.npmjs.org/@types/hast/-/hast-3.0.4.tgz",
@@ -3351,6 +3749,13 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/@types/trusted-types": {
+      "version": "2.0.7",
+      "resolved": "https://registry.npmjs.org/@types/trusted-types/-/trusted-types-2.0.7.tgz",
+      "integrity": "sha512-ScaPdn1dQczgbl0QFTeTOmVHFULt394XJgOQNoyVhZ6r2vLnMLJfBPd53SB52T/3G36VI1/g2MZaX0cwDuXsfw==",
+      "license": "MIT",
+      "optional": true
+    },
     "node_modules/@types/unist": {
       "version": "3.0.3",
       "resolved": "https://registry.npmjs.org/@types/unist/-/unist-3.0.3.tgz",
@@ -3608,9 +4013,10 @@
       }
     },
     "node_modules/acorn": {
-      "version": "8.14.1",
-      "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.14.1.tgz",
-      "integrity": "sha512-OvQ/2pUDKmgfCg++xsTX1wGxfTaszcHVcTctW4UJB4hibJx2HXxxO5UmVgyjMa+ZDsiaf5wWLXYpRWMmBI0QHg==",
+      "version": "8.15.0",
+      "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.15.0.tgz",
+      "integrity": "sha512-NZyJarBfL7nWwIq+FDL6Zp/yHEhePMNnnJ0y3qfieCrmNvYct8uvtiV41UvlSe6apAfk0fY1FbWx+NwfmpvtTg==",
+      "license": "MIT",
       "bin": {
         "acorn": "bin/acorn"
       },
@@ -4082,17 +4488,6 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
-    "node_modules/busboy": {
-      "version": "1.6.0",
-      "resolved": "https://registry.npmjs.org/busboy/-/busboy-1.6.0.tgz",
-      "integrity": "sha512-8SFQbg/0hQ9xy3UNTB0YEnsNBbWfhf7RtnzpL7TkBiTBRfrQ9Fxcnz7VJsleJpyp6rVLvXiuORqjlHi5q+PYuA==",
-      "dependencies": {
-        "streamsearch": "^1.1.0"
-      },
-      "engines": {
-        "node": ">=10.16.0"
-      }
-    },
     "node_modules/call-bind": {
       "version": "1.0.8",
       "resolved": "https://registry.npmjs.org/call-bind/-/call-bind-1.0.8.tgz",
@@ -4228,6 +4623,32 @@
         "url": "https://github.com/sponsors/wooorm"
       }
     },
+    "node_modules/chevrotain": {
+      "version": "11.0.3",
+      "resolved": "https://registry.npmjs.org/chevrotain/-/chevrotain-11.0.3.tgz",
+      "integrity": "sha512-ci2iJH6LeIkvP9eJW6gpueU8cnZhv85ELY8w8WiFtNjMHA5ad6pQLaJo9mEly/9qUyCpvqX8/POVUTf18/HFdw==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@chevrotain/cst-dts-gen": "11.0.3",
+        "@chevrotain/gast": "11.0.3",
+        "@chevrotain/regexp-to-ast": "11.0.3",
+        "@chevrotain/types": "11.0.3",
+        "@chevrotain/utils": "11.0.3",
+        "lodash-es": "4.17.21"
+      }
+    },
+    "node_modules/chevrotain-allstar": {
+      "version": "0.3.1",
+      "resolved": "https://registry.npmjs.org/chevrotain-allstar/-/chevrotain-allstar-0.3.1.tgz",
+      "integrity": "sha512-b7g+y9A0v4mxCW1qUhf3BSVPg+/NvGErk/dOkrDaHA0nQIQGAtrOjlX//9OQtRlSCy+x9rfB5N8yC71lH1nvMw==",
+      "license": "MIT",
+      "dependencies": {
+        "lodash-es": "^4.17.21"
+      },
+      "peerDependencies": {
+        "chevrotain": "^11.0.0"
+      }
+    },
     "node_modules/chokidar": {
       "version": "4.0.3",
       "resolved": "https://registry.npmjs.org/chokidar/-/chokidar-4.0.3.tgz",
@@ -4324,25 +4745,11 @@
         "url": "https://github.com/sponsors/wooorm"
       }
     },
-    "node_modules/color": {
-      "version": "4.2.3",
-      "resolved": "https://registry.npmjs.org/color/-/color-4.2.3.tgz",
-      "integrity": "sha512-1rXeuUUiGGrykh+CeBdu5Ie7OJwinCgQY0bc7GCRxy5xVHy+moaqkpL/jqQq0MtQOeYcrqEz4abc5f0KtU7W4A==",
-      "license": "MIT",
-      "optional": true,
-      "dependencies": {
-        "color-convert": "^2.0.1",
-        "color-string": "^1.9.0"
-      },
-      "engines": {
-        "node": ">=12.5.0"
-      }
-    },
     "node_modules/color-convert": {
       "version": "2.0.1",
       "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-2.0.1.tgz",
       "integrity": "sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==",
-      "devOptional": true,
+      "dev": true,
       "dependencies": {
         "color-name": "~1.1.4"
       },
@@ -4354,18 +4761,7 @@
       "version": "1.1.4",
       "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.4.tgz",
       "integrity": "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==",
-      "devOptional": true
-    },
-    "node_modules/color-string": {
-      "version": "1.9.1",
-      "resolved": "https://registry.npmjs.org/color-string/-/color-string-1.9.1.tgz",
-      "integrity": "sha512-shrVawQFojnZv6xM40anx4CkoDP+fZsw/ZerEMsW/pyzsRbElpsL/DBVW7q3ExxwusdNXI3lXpuhEZkzs8p5Eg==",
-      "license": "MIT",
-      "optional": true,
-      "dependencies": {
-        "color-name": "^1.0.0",
-        "simple-swizzle": "^0.2.2"
-      }
+      "dev": true
     },
     "node_modules/combined-stream": {
       "version": "1.0.8",
@@ -4422,6 +4818,12 @@
         "typedarray": "^0.0.6"
       }
     },
+    "node_modules/confbox": {
+      "version": "0.2.2",
+      "resolved": "https://registry.npmjs.org/confbox/-/confbox-0.2.2.tgz",
+      "integrity": "sha512-1NB+BKqhtNipMsov4xI/NnhCKp9XG9NamYp5PVm9klAT0fsrNPjaFICsCFhNhwZJKNh7zB/3q8qXz0E9oaMNtQ==",
+      "license": "MIT"
+    },
     "node_modules/convert-source-map": {
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/convert-source-map/-/convert-source-map-2.0.0.tgz",
@@ -4439,47 +4841,564 @@
         "url": "https://opencollective.com/core-js"
       }
     },
-    "node_modules/create-require": {
-      "version": "1.1.1",
-      "resolved": "https://registry.npmjs.org/create-require/-/create-require-1.1.1.tgz",
-      "integrity": "sha512-dcKFX3jn0MpIaXjisoRvexIJVEKzaq7z2rZKxf+MSr9TkdmHmsU4m2lcLojrj/FHl8mk5VxMmYA+ftRkP/3oKQ==",
-      "dev": true
+    "node_modules/cose-base": {
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/cose-base/-/cose-base-1.0.3.tgz",
+      "integrity": "sha512-s9whTXInMSgAp/NVXVNuVxVKzGH2qck3aQlVHxDCdAEPgtMKwc4Wq6/QKhgdEdgbLSi9rBTAcPoRa6JpiG4ksg==",
+      "license": "MIT",
+      "dependencies": {
+        "layout-base": "^1.0.0"
+      }
+    },
+    "node_modules/create-require": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/create-require/-/create-require-1.1.1.tgz",
+      "integrity": "sha512-dcKFX3jn0MpIaXjisoRvexIJVEKzaq7z2rZKxf+MSr9TkdmHmsU4m2lcLojrj/FHl8mk5VxMmYA+ftRkP/3oKQ==",
+      "dev": true
+    },
+    "node_modules/cross-spawn": {
+      "version": "7.0.6",
+      "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.6.tgz",
+      "integrity": "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==",
+      "dependencies": {
+        "path-key": "^3.1.0",
+        "shebang-command": "^2.0.0",
+        "which": "^2.0.1"
+      },
+      "engines": {
+        "node": ">= 8"
+      }
+    },
+    "node_modules/crypto-js": {
+      "version": "4.2.0",
+      "resolved": "https://registry.npmjs.org/crypto-js/-/crypto-js-4.2.0.tgz",
+      "integrity": "sha512-KALDyEYgpY+Rlob/iriUtjV6d5Eq+Y191A5g4UqLAi8CyGP9N1+FdVbkc1SxKc2r4YAYqG8JzO2KGL+AizD70Q==",
+      "license": "MIT"
+    },
+    "node_modules/cssesc": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/cssesc/-/cssesc-3.0.0.tgz",
+      "integrity": "sha512-/Tb/JcjK111nNScGob5MNtsntNM1aCNUDipB/TkwZFhyDrrE47SOx/18wF2bbjgc3ZzCSKW1T5nt5EbFoAz/Vg==",
+      "bin": {
+        "cssesc": "bin/cssesc"
+      },
+      "engines": {
+        "node": ">=4"
+      }
+    },
+    "node_modules/csstype": {
+      "version": "3.1.3",
+      "resolved": "https://registry.npmjs.org/csstype/-/csstype-3.1.3.tgz",
+      "integrity": "sha512-M1uQkMl8rQK/szD0LNhtqxIPLpimGm8sOBwU7lLnCpSbTyY3yeU1Vc7l4KT5zT4s/yOxHH5O7tIuuLOCnLADRw==",
+      "devOptional": true
+    },
+    "node_modules/cytoscape": {
+      "version": "3.33.1",
+      "resolved": "https://registry.npmjs.org/cytoscape/-/cytoscape-3.33.1.tgz",
+      "integrity": "sha512-iJc4TwyANnOGR1OmWhsS9ayRS3s+XQ185FmuHObThD+5AeJCakAAbWv8KimMTt08xCCLNgneQwFp+JRJOr9qGQ==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10"
+      }
+    },
+    "node_modules/cytoscape-cose-bilkent": {
+      "version": "4.1.0",
+      "resolved": "https://registry.npmjs.org/cytoscape-cose-bilkent/-/cytoscape-cose-bilkent-4.1.0.tgz",
+      "integrity": "sha512-wgQlVIUJF13Quxiv5e1gstZ08rnZj2XaLHGoFMYXz7SkNfCDOOteKBE6SYRfA9WxxI/iBc3ajfDoc6hb/MRAHQ==",
+      "license": "MIT",
+      "dependencies": {
+        "cose-base": "^1.0.0"
+      },
+      "peerDependencies": {
+        "cytoscape": "^3.2.0"
+      }
+    },
+    "node_modules/cytoscape-fcose": {
+      "version": "2.2.0",
+      "resolved": "https://registry.npmjs.org/cytoscape-fcose/-/cytoscape-fcose-2.2.0.tgz",
+      "integrity": "sha512-ki1/VuRIHFCzxWNrsshHYPs6L7TvLu3DL+TyIGEsRcvVERmxokbf5Gdk7mFxZnTdiGtnA4cfSmjZJMviqSuZrQ==",
+      "license": "MIT",
+      "dependencies": {
+        "cose-base": "^2.2.0"
+      },
+      "peerDependencies": {
+        "cytoscape": "^3.2.0"
+      }
+    },
+    "node_modules/cytoscape-fcose/node_modules/cose-base": {
+      "version": "2.2.0",
+      "resolved": "https://registry.npmjs.org/cose-base/-/cose-base-2.2.0.tgz",
+      "integrity": "sha512-AzlgcsCbUMymkADOJtQm3wO9S3ltPfYOFD5033keQn9NJzIbtnZj+UdBJe7DYml/8TdbtHJW3j58SOnKhWY/5g==",
+      "license": "MIT",
+      "dependencies": {
+        "layout-base": "^2.0.0"
+      }
+    },
+    "node_modules/cytoscape-fcose/node_modules/layout-base": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/layout-base/-/layout-base-2.0.1.tgz",
+      "integrity": "sha512-dp3s92+uNI1hWIpPGH3jK2kxE2lMjdXdr+DH8ynZHpd6PUlH6x6cbuXnoMmiNumznqaNO31xu9e79F0uuZ0JFg==",
+      "license": "MIT"
+    },
+    "node_modules/d3": {
+      "version": "7.9.0",
+      "resolved": "https://registry.npmjs.org/d3/-/d3-7.9.0.tgz",
+      "integrity": "sha512-e1U46jVP+w7Iut8Jt8ri1YsPOvFpg46k+K8TpCb0P+zjCkjkPnV7WzfDJzMHy1LnA+wj5pLT1wjO901gLXeEhA==",
+      "license": "ISC",
+      "dependencies": {
+        "d3-array": "3",
+        "d3-axis": "3",
+        "d3-brush": "3",
+        "d3-chord": "3",
+        "d3-color": "3",
+        "d3-contour": "4",
+        "d3-delaunay": "6",
+        "d3-dispatch": "3",
+        "d3-drag": "3",
+        "d3-dsv": "3",
+        "d3-ease": "3",
+        "d3-fetch": "3",
+        "d3-force": "3",
+        "d3-format": "3",
+        "d3-geo": "3",
+        "d3-hierarchy": "3",
+        "d3-interpolate": "3",
+        "d3-path": "3",
+        "d3-polygon": "3",
+        "d3-quadtree": "3",
+        "d3-random": "3",
+        "d3-scale": "4",
+        "d3-scale-chromatic": "3",
+        "d3-selection": "3",
+        "d3-shape": "3",
+        "d3-time": "3",
+        "d3-time-format": "4",
+        "d3-timer": "3",
+        "d3-transition": "3",
+        "d3-zoom": "3"
+      },
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/d3-array": {
+      "version": "3.2.4",
+      "resolved": "https://registry.npmjs.org/d3-array/-/d3-array-3.2.4.tgz",
+      "integrity": "sha512-tdQAmyA18i4J7wprpYq8ClcxZy3SC31QMeByyCFyRt7BVHdREQZ5lpzoe5mFEYZUWe+oq8HBvk9JjpibyEV4Jg==",
+      "license": "ISC",
+      "dependencies": {
+        "internmap": "1 - 2"
+      },
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/d3-axis": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/d3-axis/-/d3-axis-3.0.0.tgz",
+      "integrity": "sha512-IH5tgjV4jE/GhHkRV0HiVYPDtvfjHQlQfJHs0usq7M30XcSBvOotpmH1IgkcXsO/5gEQZD43B//fc7SRT5S+xw==",
+      "license": "ISC",
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/d3-brush": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/d3-brush/-/d3-brush-3.0.0.tgz",
+      "integrity": "sha512-ALnjWlVYkXsVIGlOsuWH1+3udkYFI48Ljihfnh8FZPF2QS9o+PzGLBslO0PjzVoHLZ2KCVgAM8NVkXPJB2aNnQ==",
+      "license": "ISC",
+      "dependencies": {
+        "d3-dispatch": "1 - 3",
+        "d3-drag": "2 - 3",
+        "d3-interpolate": "1 - 3",
+        "d3-selection": "3",
+        "d3-transition": "3"
+      },
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/d3-chord": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/d3-chord/-/d3-chord-3.0.1.tgz",
+      "integrity": "sha512-VE5S6TNa+j8msksl7HwjxMHDM2yNK3XCkusIlpX5kwauBfXuyLAtNg9jCp/iHH61tgI4sb6R/EIMWCqEIdjT/g==",
+      "license": "ISC",
+      "dependencies": {
+        "d3-path": "1 - 3"
+      },
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/d3-color": {
+      "version": "3.1.0",
+      "resolved": "https://registry.npmjs.org/d3-color/-/d3-color-3.1.0.tgz",
+      "integrity": "sha512-zg/chbXyeBtMQ1LbD/WSoW2DpC3I0mpmPdW+ynRTj/x2DAWYrIY7qeZIHidozwV24m4iavr15lNwIwLxRmOxhA==",
+      "license": "ISC",
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/d3-contour": {
+      "version": "4.0.2",
+      "resolved": "https://registry.npmjs.org/d3-contour/-/d3-contour-4.0.2.tgz",
+      "integrity": "sha512-4EzFTRIikzs47RGmdxbeUvLWtGedDUNkTcmzoeyg4sP/dvCexO47AaQL7VKy/gul85TOxw+IBgA8US2xwbToNA==",
+      "license": "ISC",
+      "dependencies": {
+        "d3-array": "^3.2.0"
+      },
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/d3-delaunay": {
+      "version": "6.0.4",
+      "resolved": "https://registry.npmjs.org/d3-delaunay/-/d3-delaunay-6.0.4.tgz",
+      "integrity": "sha512-mdjtIZ1XLAM8bm/hx3WwjfHt6Sggek7qH043O8KEjDXN40xi3vx/6pYSVTwLjEgiXQTbvaouWKynLBiUZ6SK6A==",
+      "license": "ISC",
+      "dependencies": {
+        "delaunator": "5"
+      },
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/d3-dispatch": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/d3-dispatch/-/d3-dispatch-3.0.1.tgz",
+      "integrity": "sha512-rzUyPU/S7rwUflMyLc1ETDeBj0NRuHKKAcvukozwhshr6g6c5d8zh4c2gQjY2bZ0dXeGLWc1PF174P2tVvKhfg==",
+      "license": "ISC",
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/d3-drag": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/d3-drag/-/d3-drag-3.0.0.tgz",
+      "integrity": "sha512-pWbUJLdETVA8lQNJecMxoXfH6x+mO2UQo8rSmZ+QqxcbyA3hfeprFgIT//HW2nlHChWeIIMwS2Fq+gEARkhTkg==",
+      "license": "ISC",
+      "dependencies": {
+        "d3-dispatch": "1 - 3",
+        "d3-selection": "3"
+      },
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/d3-dsv": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/d3-dsv/-/d3-dsv-3.0.1.tgz",
+      "integrity": "sha512-UG6OvdI5afDIFP9w4G0mNq50dSOsXHJaRE8arAS5o9ApWnIElp8GZw1Dun8vP8OyHOZ/QJUKUJwxiiCCnUwm+Q==",
+      "license": "ISC",
+      "dependencies": {
+        "commander": "7",
+        "iconv-lite": "0.6",
+        "rw": "1"
+      },
+      "bin": {
+        "csv2json": "bin/dsv2json.js",
+        "csv2tsv": "bin/dsv2dsv.js",
+        "dsv2dsv": "bin/dsv2dsv.js",
+        "dsv2json": "bin/dsv2json.js",
+        "json2csv": "bin/json2dsv.js",
+        "json2dsv": "bin/json2dsv.js",
+        "json2tsv": "bin/json2dsv.js",
+        "tsv2csv": "bin/dsv2dsv.js",
+        "tsv2json": "bin/dsv2json.js"
+      },
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/d3-dsv/node_modules/commander": {
+      "version": "7.2.0",
+      "resolved": "https://registry.npmjs.org/commander/-/commander-7.2.0.tgz",
+      "integrity": "sha512-QrWXB+ZQSVPmIWIhtEO9H+gwHaMGYiF5ChvoJ+K9ZGHG/sVsa6yiesAD1GC/x46sET00Xlwo1u49RVVVzvcSkw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 10"
+      }
+    },
+    "node_modules/d3-ease": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/d3-ease/-/d3-ease-3.0.1.tgz",
+      "integrity": "sha512-wR/XK3D3XcLIZwpbvQwQ5fK+8Ykds1ip7A2Txe0yxncXSdq1L9skcG7blcedkOX+ZcgxGAmLX1FrRGbADwzi0w==",
+      "license": "BSD-3-Clause",
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/d3-fetch": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/d3-fetch/-/d3-fetch-3.0.1.tgz",
+      "integrity": "sha512-kpkQIM20n3oLVBKGg6oHrUchHM3xODkTzjMoj7aWQFq5QEM+R6E4WkzT5+tojDY7yjez8KgCBRoj4aEr99Fdqw==",
+      "license": "ISC",
+      "dependencies": {
+        "d3-dsv": "1 - 3"
+      },
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/d3-force": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/d3-force/-/d3-force-3.0.0.tgz",
+      "integrity": "sha512-zxV/SsA+U4yte8051P4ECydjD/S+qeYtnaIyAs9tgHCqfguma/aAQDjo85A9Z6EKhBirHRJHXIgJUlffT4wdLg==",
+      "license": "ISC",
+      "dependencies": {
+        "d3-dispatch": "1 - 3",
+        "d3-quadtree": "1 - 3",
+        "d3-timer": "1 - 3"
+      },
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/d3-format": {
+      "version": "3.1.0",
+      "resolved": "https://registry.npmjs.org/d3-format/-/d3-format-3.1.0.tgz",
+      "integrity": "sha512-YyUI6AEuY/Wpt8KWLgZHsIU86atmikuoOmCfommt0LYHiQSPjvX2AcFc38PX0CBpr2RCyZhjex+NS/LPOv6YqA==",
+      "license": "ISC",
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/d3-geo": {
+      "version": "3.1.1",
+      "resolved": "https://registry.npmjs.org/d3-geo/-/d3-geo-3.1.1.tgz",
+      "integrity": "sha512-637ln3gXKXOwhalDzinUgY83KzNWZRKbYubaG+fGVuc/dxO64RRljtCTnf5ecMyE1RIdtqpkVcq0IbtU2S8j2Q==",
+      "license": "ISC",
+      "dependencies": {
+        "d3-array": "2.5.0 - 3"
+      },
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/d3-hierarchy": {
+      "version": "3.1.2",
+      "resolved": "https://registry.npmjs.org/d3-hierarchy/-/d3-hierarchy-3.1.2.tgz",
+      "integrity": "sha512-FX/9frcub54beBdugHjDCdikxThEqjnR93Qt7PvQTOHxyiNCAlvMrHhclk3cD5VeAaq9fxmfRp+CnWw9rEMBuA==",
+      "license": "ISC",
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/d3-interpolate": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/d3-interpolate/-/d3-interpolate-3.0.1.tgz",
+      "integrity": "sha512-3bYs1rOD33uo8aqJfKP3JWPAibgw8Zm2+L9vBKEHJ2Rg+viTR7o5Mmv5mZcieN+FRYaAOWX5SJATX6k1PWz72g==",
+      "license": "ISC",
+      "dependencies": {
+        "d3-color": "1 - 3"
+      },
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/d3-path": {
+      "version": "3.1.0",
+      "resolved": "https://registry.npmjs.org/d3-path/-/d3-path-3.1.0.tgz",
+      "integrity": "sha512-p3KP5HCf/bvjBSSKuXid6Zqijx7wIfNW+J/maPs+iwR35at5JCbLUT0LzF1cnjbCHWhqzQTIN2Jpe8pRebIEFQ==",
+      "license": "ISC",
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/d3-polygon": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/d3-polygon/-/d3-polygon-3.0.1.tgz",
+      "integrity": "sha512-3vbA7vXYwfe1SYhED++fPUQlWSYTTGmFmQiany/gdbiWgU/iEyQzyymwL9SkJjFFuCS4902BSzewVGsHHmHtXg==",
+      "license": "ISC",
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/d3-quadtree": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/d3-quadtree/-/d3-quadtree-3.0.1.tgz",
+      "integrity": "sha512-04xDrxQTDTCFwP5H6hRhsRcb9xxv2RzkcsygFzmkSIOJy3PeRJP7sNk3VRIbKXcog561P9oU0/rVH6vDROAgUw==",
+      "license": "ISC",
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/d3-random": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/d3-random/-/d3-random-3.0.1.tgz",
+      "integrity": "sha512-FXMe9GfxTxqd5D6jFsQ+DJ8BJS4E/fT5mqqdjovykEB2oFbTMDVdg1MGFxfQW+FBOGoB++k8swBrgwSHT1cUXQ==",
+      "license": "ISC",
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/d3-sankey": {
+      "version": "0.12.3",
+      "resolved": "https://registry.npmjs.org/d3-sankey/-/d3-sankey-0.12.3.tgz",
+      "integrity": "sha512-nQhsBRmM19Ax5xEIPLMY9ZmJ/cDvd1BG3UVvt5h3WRxKg5zGRbvnteTyWAbzeSvlh3tW7ZEmq4VwR5mB3tutmQ==",
+      "license": "BSD-3-Clause",
+      "dependencies": {
+        "d3-array": "1 - 2",
+        "d3-shape": "^1.2.0"
+      }
+    },
+    "node_modules/d3-sankey/node_modules/d3-array": {
+      "version": "2.12.1",
+      "resolved": "https://registry.npmjs.org/d3-array/-/d3-array-2.12.1.tgz",
+      "integrity": "sha512-B0ErZK/66mHtEsR1TkPEEkwdy+WDesimkM5gpZr5Dsg54BiTA5RXtYW5qTLIAcekaS9xfZrzBLF/OAkB3Qn1YQ==",
+      "license": "BSD-3-Clause",
+      "dependencies": {
+        "internmap": "^1.0.0"
+      }
+    },
+    "node_modules/d3-sankey/node_modules/d3-path": {
+      "version": "1.0.9",
+      "resolved": "https://registry.npmjs.org/d3-path/-/d3-path-1.0.9.tgz",
+      "integrity": "sha512-VLaYcn81dtHVTjEHd8B+pbe9yHWpXKZUC87PzoFmsFrJqgFwDe/qxfp5MlfsfM1V5E/iVt0MmEbWQ7FVIXh/bg==",
+      "license": "BSD-3-Clause"
+    },
+    "node_modules/d3-sankey/node_modules/d3-shape": {
+      "version": "1.3.7",
+      "resolved": "https://registry.npmjs.org/d3-shape/-/d3-shape-1.3.7.tgz",
+      "integrity": "sha512-EUkvKjqPFUAZyOlhY5gzCxCeI0Aep04LwIRpsZ/mLFelJiUfnK56jo5JMDSE7yyP2kLSb6LtF+S5chMk7uqPqw==",
+      "license": "BSD-3-Clause",
+      "dependencies": {
+        "d3-path": "1"
+      }
+    },
+    "node_modules/d3-sankey/node_modules/internmap": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/internmap/-/internmap-1.0.1.tgz",
+      "integrity": "sha512-lDB5YccMydFBtasVtxnZ3MRBHuaoE8GKsppq+EchKL2U4nK/DmEpPHNH8MZe5HkMtpSiTSOZwfN0tzYjO/lJEw==",
+      "license": "ISC"
+    },
+    "node_modules/d3-scale": {
+      "version": "4.0.2",
+      "resolved": "https://registry.npmjs.org/d3-scale/-/d3-scale-4.0.2.tgz",
+      "integrity": "sha512-GZW464g1SH7ag3Y7hXjf8RoUuAFIqklOAq3MRl4OaWabTFJY9PN/E1YklhXLh+OQ3fM9yS2nOkCoS+WLZ6kvxQ==",
+      "license": "ISC",
+      "dependencies": {
+        "d3-array": "2.10.0 - 3",
+        "d3-format": "1 - 3",
+        "d3-interpolate": "1.2.0 - 3",
+        "d3-time": "2.1.1 - 3",
+        "d3-time-format": "2 - 4"
+      },
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/d3-scale-chromatic": {
+      "version": "3.1.0",
+      "resolved": "https://registry.npmjs.org/d3-scale-chromatic/-/d3-scale-chromatic-3.1.0.tgz",
+      "integrity": "sha512-A3s5PWiZ9YCXFye1o246KoscMWqf8BsD9eRiJ3He7C9OBaxKhAd5TFCdEx/7VbKtxxTsu//1mMJFrEt572cEyQ==",
+      "license": "ISC",
+      "dependencies": {
+        "d3-color": "1 - 3",
+        "d3-interpolate": "1 - 3"
+      },
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/d3-selection": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/d3-selection/-/d3-selection-3.0.0.tgz",
+      "integrity": "sha512-fmTRWbNMmsmWq6xJV8D19U/gw/bwrHfNXxrIN+HfZgnzqTHp9jOmKMhsTUjXOJnZOdZY9Q28y4yebKzqDKlxlQ==",
+      "license": "ISC",
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/d3-shape": {
+      "version": "3.2.0",
+      "resolved": "https://registry.npmjs.org/d3-shape/-/d3-shape-3.2.0.tgz",
+      "integrity": "sha512-SaLBuwGm3MOViRq2ABk3eLoxwZELpH6zhl3FbAoJ7Vm1gofKx6El1Ib5z23NUEhF9AsGl7y+dzLe5Cw2AArGTA==",
+      "license": "ISC",
+      "dependencies": {
+        "d3-path": "^3.1.0"
+      },
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/d3-time": {
+      "version": "3.1.0",
+      "resolved": "https://registry.npmjs.org/d3-time/-/d3-time-3.1.0.tgz",
+      "integrity": "sha512-VqKjzBLejbSMT4IgbmVgDjpkYrNWUYJnbCGo874u7MMKIWsILRX+OpX/gTk8MqjpT1A/c6HY2dCA77ZN0lkQ2Q==",
+      "license": "ISC",
+      "dependencies": {
+        "d3-array": "2 - 3"
+      },
+      "engines": {
+        "node": ">=12"
+      }
     },
-    "node_modules/cross-spawn": {
-      "version": "7.0.6",
-      "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.6.tgz",
-      "integrity": "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==",
+    "node_modules/d3-time-format": {
+      "version": "4.1.0",
+      "resolved": "https://registry.npmjs.org/d3-time-format/-/d3-time-format-4.1.0.tgz",
+      "integrity": "sha512-dJxPBlzC7NugB2PDLwo9Q8JiTR3M3e4/XANkreKSUxF8vvXKqm1Yfq4Q5dl8budlunRVlUUaDUgFt7eA8D6NLg==",
+      "license": "ISC",
       "dependencies": {
-        "path-key": "^3.1.0",
-        "shebang-command": "^2.0.0",
-        "which": "^2.0.1"
+        "d3-time": "1 - 3"
       },
       "engines": {
-        "node": ">= 8"
+        "node": ">=12"
       }
     },
-    "node_modules/crypto-js": {
-      "version": "4.2.0",
-      "resolved": "https://registry.npmjs.org/crypto-js/-/crypto-js-4.2.0.tgz",
-      "integrity": "sha512-KALDyEYgpY+Rlob/iriUtjV6d5Eq+Y191A5g4UqLAi8CyGP9N1+FdVbkc1SxKc2r4YAYqG8JzO2KGL+AizD70Q==",
-      "license": "MIT"
+    "node_modules/d3-timer": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/d3-timer/-/d3-timer-3.0.1.tgz",
+      "integrity": "sha512-ndfJ/JxxMd3nw31uyKoY2naivF+r29V+Lc0svZxe1JvvIRmi8hUsrMvdOwgS1o6uBHmiz91geQ0ylPP0aj1VUA==",
+      "license": "ISC",
+      "engines": {
+        "node": ">=12"
+      }
     },
-    "node_modules/cssesc": {
+    "node_modules/d3-transition": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/d3-transition/-/d3-transition-3.0.1.tgz",
+      "integrity": "sha512-ApKvfjsSR6tg06xrL434C0WydLr7JewBB3V+/39RMHsaXTOG0zmt/OAXeng5M5LBm0ojmxJrpomQVZ1aPvBL4w==",
+      "license": "ISC",
+      "dependencies": {
+        "d3-color": "1 - 3",
+        "d3-dispatch": "1 - 3",
+        "d3-ease": "1 - 3",
+        "d3-interpolate": "1 - 3",
+        "d3-timer": "1 - 3"
+      },
+      "engines": {
+        "node": ">=12"
+      },
+      "peerDependencies": {
+        "d3-selection": "2 - 3"
+      }
+    },
+    "node_modules/d3-zoom": {
       "version": "3.0.0",
-      "resolved": "https://registry.npmjs.org/cssesc/-/cssesc-3.0.0.tgz",
-      "integrity": "sha512-/Tb/JcjK111nNScGob5MNtsntNM1aCNUDipB/TkwZFhyDrrE47SOx/18wF2bbjgc3ZzCSKW1T5nt5EbFoAz/Vg==",
-      "bin": {
-        "cssesc": "bin/cssesc"
+      "resolved": "https://registry.npmjs.org/d3-zoom/-/d3-zoom-3.0.0.tgz",
+      "integrity": "sha512-b8AmV3kfQaqWAuacbPuNbL6vahnOJflOhexLzMMNLga62+/nh0JzvJ0aO/5a5MVgUFGS7Hu1P9P03o3fJkDCyw==",
+      "license": "ISC",
+      "dependencies": {
+        "d3-dispatch": "1 - 3",
+        "d3-drag": "2 - 3",
+        "d3-interpolate": "1 - 3",
+        "d3-selection": "2 - 3",
+        "d3-transition": "2 - 3"
       },
       "engines": {
-        "node": ">=4"
+        "node": ">=12"
       }
     },
-    "node_modules/csstype": {
-      "version": "3.1.3",
-      "resolved": "https://registry.npmjs.org/csstype/-/csstype-3.1.3.tgz",
-      "integrity": "sha512-M1uQkMl8rQK/szD0LNhtqxIPLpimGm8sOBwU7lLnCpSbTyY3yeU1Vc7l4KT5zT4s/yOxHH5O7tIuuLOCnLADRw==",
-      "devOptional": true
+    "node_modules/dagre-d3-es": {
+      "version": "7.0.11",
+      "resolved": "https://registry.npmjs.org/dagre-d3-es/-/dagre-d3-es-7.0.11.tgz",
+      "integrity": "sha512-tvlJLyQf834SylNKax8Wkzco/1ias1OPw8DcUMDE7oUIoSEW25riQVuiu/0OWEFqT0cxHT3Pa9/D82Jr47IONw==",
+      "license": "MIT",
+      "dependencies": {
+        "d3": "^7.9.0",
+        "lodash-es": "^4.17.21"
+      }
     },
     "node_modules/damerau-levenshtein": {
       "version": "1.0.8",
@@ -4538,10 +5457,17 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
+    "node_modules/dayjs": {
+      "version": "1.11.18",
+      "resolved": "https://registry.npmjs.org/dayjs/-/dayjs-1.11.18.tgz",
+      "integrity": "sha512-zFBQ7WFRvVRhKcWoUh+ZA1g2HVgUbsZm9sbddh8EC5iv93sui8DVVz1Npvz+r6meo9VKfa8NyLWBsQK1VvIKPA==",
+      "license": "MIT"
+    },
     "node_modules/debug": {
-      "version": "4.4.0",
-      "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.0.tgz",
-      "integrity": "sha512-6WTZ/IxCY/T6BALoZHaE4ctp9xm+Z5kY/pzYaCHRFeyVhojxlrm+46y68HA6hr0TcwEssoxNiDEUJQjfPZ/RYA==",
+      "version": "4.4.3",
+      "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz",
+      "integrity": "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==",
+      "license": "MIT",
       "dependencies": {
         "ms": "^2.1.3"
       },
@@ -4652,6 +5578,15 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
+    "node_modules/delaunator": {
+      "version": "5.0.1",
+      "resolved": "https://registry.npmjs.org/delaunator/-/delaunator-5.0.1.tgz",
+      "integrity": "sha512-8nvh+XBe96aCESrGOqMp/84b13H9cdKbG5P2ejQCh4d4sK9RL4371qou9drQjMhvnPmhWl5hnmqbEE0fXr9Xnw==",
+      "license": "ISC",
+      "dependencies": {
+        "robust-predicates": "^3.0.2"
+      }
+    },
     "node_modules/delayed-stream": {
       "version": "1.0.0",
       "resolved": "https://registry.npmjs.org/delayed-stream/-/delayed-stream-1.0.0.tgz",
@@ -4669,9 +5604,9 @@
       }
     },
     "node_modules/detect-libc": {
-      "version": "2.0.4",
-      "resolved": "https://registry.npmjs.org/detect-libc/-/detect-libc-2.0.4.tgz",
-      "integrity": "sha512-3UDv+G9CsCKO1WKMGw9fwq/SWJYbI0c5Y7LU1AXYoDdbhE2AHQ6N6Nb34sG8Fj7T5APy8qXDCKuuIHd1BR0tVA==",
+      "version": "2.1.1",
+      "resolved": "https://registry.npmjs.org/detect-libc/-/detect-libc-2.1.1.tgz",
+      "integrity": "sha512-ecqj/sy1jcK1uWrwpR67UhYrIFQ+5WlGxth34WquCbamhFA6hkkwiu37o6J5xCHdo1oixJRfVRw+ywV+Hq/0Aw==",
       "devOptional": true,
       "license": "Apache-2.0",
       "engines": {
@@ -4716,6 +5651,15 @@
         "node": ">=6.0.0"
       }
     },
+    "node_modules/dompurify": {
+      "version": "3.2.7",
+      "resolved": "https://registry.npmjs.org/dompurify/-/dompurify-3.2.7.tgz",
+      "integrity": "sha512-WhL/YuveyGXJaerVlMYGWhvQswa7myDG17P7Vu65EWC05o8vfeNbvNf4d/BOvH99+ZW+LlQsc1GDKMa1vNK6dw==",
+      "license": "(MPL-2.0 OR Apache-2.0)",
+      "optionalDependencies": {
+        "@types/trusted-types": "^2.0.7"
+      }
+    },
     "node_modules/dotenv": {
       "version": "16.4.7",
       "resolved": "https://registry.npmjs.org/dotenv/-/dotenv-16.4.7.tgz",
@@ -5579,6 +6523,12 @@
         "node": ">=0.10.0"
       }
     },
+    "node_modules/exsolve": {
+      "version": "1.0.7",
+      "resolved": "https://registry.npmjs.org/exsolve/-/exsolve-1.0.7.tgz",
+      "integrity": "sha512-VO5fQUzZtI6C+vx4w/4BWJpg3s/5l+6pRQEHzFRM8WFi4XffSP1Z+4qi7GbjWbvRQEbdIco5mIMq+zX4rPuLrw==",
+      "license": "MIT"
+    },
     "node_modules/extend": {
       "version": "3.0.2",
       "resolved": "https://registry.npmjs.org/extend/-/extend-3.0.2.tgz",
@@ -6032,9 +6982,9 @@
       }
     },
     "node_modules/generaltranslation": {
-      "version": "7.4.1",
-      "resolved": "https://registry.npmjs.org/generaltranslation/-/generaltranslation-7.4.1.tgz",
-      "integrity": "sha512-dwavW+DW2ZJ9irEEkWu369sCcmEHy7aUIvKDUyE/8GQPzYKXnBJzEdYoSHRJxIzuVbGBoQOZ6oJKn/tgZSlntQ==",
+      "version": "7.6.3",
+      "resolved": "https://registry.npmjs.org/generaltranslation/-/generaltranslation-7.6.3.tgz",
+      "integrity": "sha512-e9lt/Nuz8qgzCgFCHhjuiuEvlyTkJymqZ+byzt7Y1fSBmiVEtGNqjU7iVd7u5ikwm7TCFq0rhTjEx/i3dtvvkw==",
       "license": "FSL-1.1-ALv2",
       "dependencies": {
         "crypto-js": "^4.2.0",
@@ -6261,14 +7211,14 @@
       }
     },
     "node_modules/gt-next": {
-      "version": "6.2.5",
-      "resolved": "https://registry.npmjs.org/gt-next/-/gt-next-6.2.5.tgz",
-      "integrity": "sha512-ykPzu3ioA3PWC2MM6CcBufwN3Xga1wEATXjiaIq1+x6mXT1Rxxj8VXVvQlTyLXswsigwtbfDd1fYbL6pmxAinA==",
+      "version": "6.6.2",
+      "resolved": "https://registry.npmjs.org/gt-next/-/gt-next-6.6.2.tgz",
+      "integrity": "sha512-a0IDlShegCoNs6w0OaB5POsKOzjzmlxSczd1vyHvcJ6fmOSUeoXfndJOJjifY9VB97gyYNWSI7EPyvLhY36yIw==",
       "license": "FSL-1.1-ALv2",
       "dependencies": {
         "@generaltranslation/supported-locales": "^2.0.13",
-        "generaltranslation": "^7.4.1",
-        "gt-react": "^10.3.1"
+        "generaltranslation": "^7.5.0",
+        "gt-react": "^10.6.1"
       },
       "peerDependencies": {
         "next": ">=13.0.0 <15.2.1 || >15.2.2",
@@ -6277,23 +7227,32 @@
       }
     },
     "node_modules/gt-react": {
-      "version": "10.3.1",
-      "resolved": "https://registry.npmjs.org/gt-react/-/gt-react-10.3.1.tgz",
-      "integrity": "sha512-E+Ib1Mxasc6ZJw8lF3Cbnfrg7z4H4OXuxxLc81PE4UEwOAS1CHxUSW8944NEkr3sbTA6+Y5sqKD1Zxg0pzrNaA==",
+      "version": "10.6.1",
+      "resolved": "https://registry.npmjs.org/gt-react/-/gt-react-10.6.1.tgz",
+      "integrity": "sha512-V6lS+czyy7G9KUP2pTV2kJXw/CBYdiWrDSCffLYd3uUPUFmZtT6euaDapS68Z8bztODAKo7ho/j8pAXJ1GBrug==",
       "license": "FSL-1.1-ALv2",
       "dependencies": {
         "@generaltranslation/supported-locales": "^2.0.13",
-        "generaltranslation": "^7.4.1"
+        "generaltranslation": "^7.5.0"
       },
       "peerDependencies": {
         "react": ">=16.8.0",
         "react-dom": ">=16.8.0"
       }
     },
+    "node_modules/gt-remark": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/gt-remark/-/gt-remark-1.0.1.tgz",
+      "integrity": "sha512-vMpZI7SEKiXrtKanuApcw4HmdcSwncLvKq9c1oP8SxFsNQETMo8XRrrnHyk7XCHWK34VkHk8SuZvhbFQDqkNHg==",
+      "license": "FSL-1.1-ALv2",
+      "dependencies": {
+        "mdast-util-find-and-replace": "^3.0.1"
+      }
+    },
     "node_modules/gtx-cli": {
-      "version": "2.1.8",
-      "resolved": "https://registry.npmjs.org/gtx-cli/-/gtx-cli-2.1.8.tgz",
-      "integrity": "sha512-znLYWqeGAk1OF3vKmrkYCPdRHnV25eARAft9YtjpkXDrd6dZRIubt1Rh6nB9FTqpnWVgd0sAIDOL4EY5SmXFaQ==",
+      "version": "2.3.4",
+      "resolved": "https://registry.npmjs.org/gtx-cli/-/gtx-cli-2.3.4.tgz",
+      "integrity": "sha512-T2oAajFX9/uoDSB4Ss4PZR5dwX1BUA6J25rQyWPU9UiESWkIWBKUppORMVcdCWXJWwJxAHheJs6/txAiANmClg==",
       "license": "FSL-1.1-ALv2",
       "dependencies": {
         "@babel/generator": "^7.25.7",
@@ -6307,10 +7266,12 @@
         "esbuild": "^0.25.4",
         "fast-glob": "^3.3.3",
         "form-data": "^4.0.4",
-        "generaltranslation": "^7.4.1",
+        "generaltranslation": "^7.6.2",
+        "gt-remark": "^1.0.1",
         "json-pointer": "^0.6.2",
         "jsonpath-plus": "^10.3.0",
         "jsonpointer": "^5.0.1",
+        "mdast-util-find-and-replace": "^3.0.2",
         "micromatch": "^4.0.8",
         "open": "^10.1.1",
         "ora": "^8.2.0",
@@ -6392,6 +7353,12 @@
         "node": ">=6"
       }
     },
+    "node_modules/hachure-fill": {
+      "version": "0.5.2",
+      "resolved": "https://registry.npmjs.org/hachure-fill/-/hachure-fill-0.5.2.tgz",
+      "integrity": "sha512-3GKBOn+m2LX9iq+JC1064cSFprJY4jL1jCXTcpnfER5HYE2l/4EfWSGzkPa/ZDBmYI0ZOEj5VHV/eKnPGkHuOg==",
+      "license": "MIT"
+    },
     "node_modules/has-bigints": {
       "version": "1.1.0",
       "resolved": "https://registry.npmjs.org/has-bigints/-/has-bigints-1.1.0.tgz",
@@ -6607,6 +7574,18 @@
         "url": "https://github.com/sponsors/wooorm"
       }
     },
+    "node_modules/iconv-lite": {
+      "version": "0.6.3",
+      "resolved": "https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.6.3.tgz",
+      "integrity": "sha512-4fCk79wshMdzMp2rH06qWrJE4iolqLhCUH+OiuIgU++RB0+94NlDL81atO7GX55uUKueo0txHNtvEyI6D7WdMw==",
+      "license": "MIT",
+      "dependencies": {
+        "safer-buffer": ">= 2.1.2 < 3.0.0"
+      },
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
     "node_modules/ignore": {
       "version": "5.3.2",
       "resolved": "https://registry.npmjs.org/ignore/-/ignore-5.3.2.tgz",
@@ -6710,6 +7689,15 @@
         "node": ">= 0.4"
       }
     },
+    "node_modules/internmap": {
+      "version": "2.0.3",
+      "resolved": "https://registry.npmjs.org/internmap/-/internmap-2.0.3.tgz",
+      "integrity": "sha512-5Hh7Y1wQbvY5ooGgPbDaL5iYLAPzMTUrjMulskHLH6wnv/A+1q5rgEaiuqEjB+oxGXIVZs1FF+R/KPN3ZSQYYg==",
+      "license": "ISC",
+      "engines": {
+        "node": ">=12"
+      }
+    },
     "node_modules/intl-messageformat": {
       "version": "10.7.16",
       "resolved": "https://registry.npmjs.org/intl-messageformat/-/intl-messageformat-10.7.16.tgz",
@@ -6761,13 +7749,6 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
-    "node_modules/is-arrayish": {
-      "version": "0.3.2",
-      "resolved": "https://registry.npmjs.org/is-arrayish/-/is-arrayish-0.3.2.tgz",
-      "integrity": "sha512-eVRqCvVlZbuw3GrM63ovNSNAeA1K16kaR/LRY/92w0zxQ5/1YzwblUX652i4Xs9RwAGjW9d9y6X88t8OaAJfWQ==",
-      "license": "MIT",
-      "optional": true
-    },
     "node_modules/is-async-function": {
       "version": "2.1.1",
       "resolved": "https://registry.npmjs.org/is-async-function/-/is-async-function-2.1.1.tgz",
@@ -7436,6 +8417,31 @@
         "node": ">=4.0"
       }
     },
+    "node_modules/katex": {
+      "version": "0.16.22",
+      "resolved": "https://registry.npmjs.org/katex/-/katex-0.16.22.tgz",
+      "integrity": "sha512-XCHRdUw4lf3SKBaJe4EvgqIuWwkPSo9XoeO8GjQW94Bp7TWv9hNhzZjZ+OH9yf1UmLygb7DIT5GSFQiyt16zYg==",
+      "funding": [
+        "https://opencollective.com/katex",
+        "https://github.com/sponsors/katex"
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "commander": "^8.3.0"
+      },
+      "bin": {
+        "katex": "cli.js"
+      }
+    },
+    "node_modules/katex/node_modules/commander": {
+      "version": "8.3.0",
+      "resolved": "https://registry.npmjs.org/commander/-/commander-8.3.0.tgz",
+      "integrity": "sha512-OkTL9umf+He2DZkUq8f8J9of7yL6RJKI24dVITBmNfZBmri9zYZQrKkuXiKhyfPSu8tUhnVBB1iKXevvnlR4Ww==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 12"
+      }
+    },
     "node_modules/keyv": {
       "version": "4.5.4",
       "resolved": "https://registry.npmjs.org/keyv/-/keyv-4.5.4.tgz",
@@ -7445,6 +8451,11 @@
         "json-buffer": "3.0.1"
       }
     },
+    "node_modules/khroma": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/khroma/-/khroma-2.1.0.tgz",
+      "integrity": "sha512-Ls993zuzfayK269Svk9hzpeGUKob/sIgZzyHYdjQoAdQetRKpOLj+k/QQQ/6Qi0Yz65mlROrfd+Ev+1+7dz9Kw=="
+    },
     "node_modules/kind-of": {
       "version": "6.0.3",
       "resolved": "https://registry.npmjs.org/kind-of/-/kind-of-6.0.3.tgz",
@@ -7453,6 +8464,28 @@
         "node": ">=0.10.0"
       }
     },
+    "node_modules/kolorist": {
+      "version": "1.8.0",
+      "resolved": "https://registry.npmjs.org/kolorist/-/kolorist-1.8.0.tgz",
+      "integrity": "sha512-Y+60/zizpJ3HRH8DCss+q95yr6145JXZo46OTpFvDZWLfRCE4qChOyk1b26nMaNpfHHgxagk9dXT5OP0Tfe+dQ==",
+      "license": "MIT"
+    },
+    "node_modules/langium": {
+      "version": "3.3.1",
+      "resolved": "https://registry.npmjs.org/langium/-/langium-3.3.1.tgz",
+      "integrity": "sha512-QJv/h939gDpvT+9SiLVlY7tZC3xB2qK57v0J04Sh9wpMb6MP1q8gB21L3WIo8T5P1MSMg3Ep14L7KkDCFG3y4w==",
+      "license": "MIT",
+      "dependencies": {
+        "chevrotain": "~11.0.3",
+        "chevrotain-allstar": "~0.3.0",
+        "vscode-languageserver": "~9.0.1",
+        "vscode-languageserver-textdocument": "~1.0.11",
+        "vscode-uri": "~3.0.8"
+      },
+      "engines": {
+        "node": ">=16.0.0"
+      }
+    },
     "node_modules/language-subtag-registry": {
       "version": "0.3.23",
       "resolved": "https://registry.npmjs.org/language-subtag-registry/-/language-subtag-registry-0.3.23.tgz",
@@ -7471,6 +8504,12 @@
         "node": ">=0.10"
       }
     },
+    "node_modules/layout-base": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/layout-base/-/layout-base-1.0.2.tgz",
+      "integrity": "sha512-8h2oVEZNktL4BH2JCOI90iD1yXwL6iNW7KcCKT2QZgQJR2vbqDsldCTPRU9NifTCqHZci57XvQQ15YTu+sTYPg==",
+      "license": "MIT"
+    },
     "node_modules/levenshtein-edit-distance": {
       "version": "1.0.0",
       "resolved": "https://registry.npmjs.org/levenshtein-edit-distance/-/levenshtein-edit-distance-1.0.0.tgz",
@@ -7747,6 +8786,23 @@
         "url": "https://github.com/sponsors/wooorm"
       }
     },
+    "node_modules/local-pkg": {
+      "version": "1.1.2",
+      "resolved": "https://registry.npmjs.org/local-pkg/-/local-pkg-1.1.2.tgz",
+      "integrity": "sha512-arhlxbFRmoQHl33a0Zkle/YWlmNwoyt6QNZEIJcqNbdrsix5Lvc4HyyI3EnwxTYlZYc32EbYrQ8SzEZ7dqgg9A==",
+      "license": "MIT",
+      "dependencies": {
+        "mlly": "^1.7.4",
+        "pkg-types": "^2.3.0",
+        "quansync": "^0.2.11"
+      },
+      "engines": {
+        "node": ">=14"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/antfu"
+      }
+    },
     "node_modules/locate-path": {
       "version": "6.0.0",
       "resolved": "https://registry.npmjs.org/locate-path/-/locate-path-6.0.0.tgz",
@@ -7762,6 +8818,12 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
+    "node_modules/lodash-es": {
+      "version": "4.17.21",
+      "resolved": "https://registry.npmjs.org/lodash-es/-/lodash-es-4.17.21.tgz",
+      "integrity": "sha512-mKnC+QJ9pWVzv+C4/U3rRsHapFfHvQFoFB92e52xeyGMcX6/OlIl78je1u8vePzYZSkkogMPJ2yjxxsb89cxyw==",
+      "license": "MIT"
+    },
     "node_modules/lodash.merge": {
       "version": "4.6.2",
       "resolved": "https://registry.npmjs.org/lodash.merge/-/lodash.merge-4.6.2.tgz",
@@ -7869,6 +8931,18 @@
         "url": "https://github.com/sponsors/wooorm"
       }
     },
+    "node_modules/marked": {
+      "version": "16.3.0",
+      "resolved": "https://registry.npmjs.org/marked/-/marked-16.3.0.tgz",
+      "integrity": "sha512-K3UxuKu6l6bmA5FUwYho8CfJBlsUWAooKtdGgMcERSpF7gcBUrCGsLH7wDaaNOzwq18JzSUDyoEb/YsrqMac3w==",
+      "license": "MIT",
+      "bin": {
+        "marked": "bin/marked.js"
+      },
+      "engines": {
+        "node": ">= 20"
+      }
+    },
     "node_modules/math-intrinsics": {
       "version": "1.1.0",
       "resolved": "https://registry.npmjs.org/math-intrinsics/-/math-intrinsics-1.1.0.tgz",
@@ -8197,6 +9271,34 @@
         "node": ">= 8"
       }
     },
+    "node_modules/mermaid": {
+      "version": "11.12.0",
+      "resolved": "https://registry.npmjs.org/mermaid/-/mermaid-11.12.0.tgz",
+      "integrity": "sha512-ZudVx73BwrMJfCFmSSJT84y6u5brEoV8DOItdHomNLz32uBjNrelm7mg95X7g+C6UoQH/W6mBLGDEDv73JdxBg==",
+      "license": "MIT",
+      "dependencies": {
+        "@braintree/sanitize-url": "^7.1.1",
+        "@iconify/utils": "^3.0.1",
+        "@mermaid-js/parser": "^0.6.2",
+        "@types/d3": "^7.4.3",
+        "cytoscape": "^3.29.3",
+        "cytoscape-cose-bilkent": "^4.1.0",
+        "cytoscape-fcose": "^2.2.0",
+        "d3": "^7.9.0",
+        "d3-sankey": "^0.12.3",
+        "dagre-d3-es": "7.0.11",
+        "dayjs": "^1.11.18",
+        "dompurify": "^3.2.5",
+        "katex": "^0.16.22",
+        "khroma": "^2.1.0",
+        "lodash-es": "^4.17.21",
+        "marked": "^16.2.1",
+        "roughjs": "^4.6.6",
+        "stylis": "^4.3.6",
+        "ts-dedent": "^2.2.0",
+        "uuid": "^11.1.0"
+      }
+    },
     "node_modules/micromark": {
       "version": "4.0.2",
       "resolved": "https://registry.npmjs.org/micromark/-/micromark-4.0.2.tgz",
@@ -8969,6 +10071,35 @@
         "node": ">=16 || 14 >=14.17"
       }
     },
+    "node_modules/mlly": {
+      "version": "1.8.0",
+      "resolved": "https://registry.npmjs.org/mlly/-/mlly-1.8.0.tgz",
+      "integrity": "sha512-l8D9ODSRWLe2KHJSifWGwBqpTZXIXTeo8mlKjY+E2HAakaTeNpqAyBZ8GSqLzHgw4XmHmC8whvpjJNMbFZN7/g==",
+      "license": "MIT",
+      "dependencies": {
+        "acorn": "^8.15.0",
+        "pathe": "^2.0.3",
+        "pkg-types": "^1.3.1",
+        "ufo": "^1.6.1"
+      }
+    },
+    "node_modules/mlly/node_modules/confbox": {
+      "version": "0.1.8",
+      "resolved": "https://registry.npmjs.org/confbox/-/confbox-0.1.8.tgz",
+      "integrity": "sha512-RMtmw0iFkeR4YV+fUOSucriAQNb9g8zFR52MWCtl+cCZOFRNL6zeB395vPzFhEjjn4fMxXudmELnl/KF/WrK6w==",
+      "license": "MIT"
+    },
+    "node_modules/mlly/node_modules/pkg-types": {
+      "version": "1.3.1",
+      "resolved": "https://registry.npmjs.org/pkg-types/-/pkg-types-1.3.1.tgz",
+      "integrity": "sha512-/Jm5M4RvtBFVkKWRu2BLUTNP8/M2a+UwuAX+ae4770q1qVGtfjG+WTCupoZixokjmHiry8uI+dlY8KXYV5HVVQ==",
+      "license": "MIT",
+      "dependencies": {
+        "confbox": "^0.1.8",
+        "mlly": "^1.7.4",
+        "pathe": "^2.0.1"
+      }
+    },
     "node_modules/ms": {
       "version": "2.1.3",
       "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz",
@@ -9006,15 +10137,13 @@
       }
     },
     "node_modules/next": {
-      "version": "15.3.2",
-      "resolved": "https://registry.npmjs.org/next/-/next-15.3.2.tgz",
-      "integrity": "sha512-CA3BatMyHkxZ48sgOCLdVHjFU36N7TF1HhqAHLFOkV6buwZnvMI84Cug8xD56B9mCuKrqXnLn94417GrZ/jjCQ==",
+      "version": "15.5.4",
+      "resolved": "https://registry.npmjs.org/next/-/next-15.5.4.tgz",
+      "integrity": "sha512-xH4Yjhb82sFYQfY3vbkJfgSDgXvBB6a8xPs9i35k6oZJRoQRihZH+4s9Yo2qsWpzBmZ3lPXaJ2KPXLfkvW4LnA==",
       "license": "MIT",
       "dependencies": {
-        "@next/env": "15.3.2",
-        "@swc/counter": "0.1.3",
+        "@next/env": "15.5.4",
         "@swc/helpers": "0.5.15",
-        "busboy": "1.6.0",
         "caniuse-lite": "^1.0.30001579",
         "postcss": "8.4.31",
         "styled-jsx": "5.1.6"
@@ -9026,19 +10155,19 @@
         "node": "^18.18.0 || ^19.8.0 || >= 20.0.0"
       },
       "optionalDependencies": {
-        "@next/swc-darwin-arm64": "15.3.2",
-        "@next/swc-darwin-x64": "15.3.2",
-        "@next/swc-linux-arm64-gnu": "15.3.2",
-        "@next/swc-linux-arm64-musl": "15.3.2",
-        "@next/swc-linux-x64-gnu": "15.3.2",
-        "@next/swc-linux-x64-musl": "15.3.2",
-        "@next/swc-win32-arm64-msvc": "15.3.2",
-        "@next/swc-win32-x64-msvc": "15.3.2",
-        "sharp": "^0.34.1"
+        "@next/swc-darwin-arm64": "15.5.4",
+        "@next/swc-darwin-x64": "15.5.4",
+        "@next/swc-linux-arm64-gnu": "15.5.4",
+        "@next/swc-linux-arm64-musl": "15.5.4",
+        "@next/swc-linux-x64-gnu": "15.5.4",
+        "@next/swc-linux-x64-musl": "15.5.4",
+        "@next/swc-win32-arm64-msvc": "15.5.4",
+        "@next/swc-win32-x64-msvc": "15.5.4",
+        "sharp": "^0.34.3"
       },
       "peerDependencies": {
         "@opentelemetry/api": "^1.1.0",
-        "@playwright/test": "^1.41.2",
+        "@playwright/test": "^1.51.1",
         "babel-plugin-react-compiler": "*",
         "react": "^18.2.0 || 19.0.0-rc-de68d2f4-20241204 || ^19.0.0",
         "react-dom": "^18.2.0 || 19.0.0-rc-de68d2f4-20241204 || ^19.0.0",
@@ -9094,6 +10223,7 @@
       "version": "0.4.6",
       "resolved": "https://registry.npmjs.org/next-themes/-/next-themes-0.4.6.tgz",
       "integrity": "sha512-pZvgD5L0IEvX5/9GWyHMf3m8BKiVQwsCMHfoFosXtXBMnaS0ZnIJ9ST4b4NqLVKDEm8QBxoNNGNaBv2JNF6XNA==",
+      "license": "MIT",
       "peerDependencies": {
         "react": "^16.8 || ^17 || ^18 || ^19 || ^19.0.0-rc",
         "react-dom": "^16.8 || ^17 || ^18 || ^19 || ^19.0.0-rc"
@@ -9536,6 +10666,12 @@
       "dev": true,
       "license": "BlueOak-1.0.0"
     },
+    "node_modules/package-manager-detector": {
+      "version": "1.3.0",
+      "resolved": "https://registry.npmjs.org/package-manager-detector/-/package-manager-detector-1.3.0.tgz",
+      "integrity": "sha512-ZsEbbZORsyHuO00lY1kV3/t72yp6Ysay6Pd17ZAlNGuGwmWDLCJxFpRs0IzfXfj1o4icJOkUEioexFHzyPurSQ==",
+      "license": "MIT"
+    },
     "node_modules/parent-module": {
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/parent-module/-/parent-module-1.0.1.tgz",
@@ -9610,6 +10746,12 @@
       "integrity": "sha512-b7uo2UCUOYZcnF/3ID0lulOJi/bafxa1xPe7ZPsammBSpjSWQkjNxlt635YGS2MiR9GjvuXCtz2emr3jbsz98g==",
       "license": "MIT"
     },
+    "node_modules/path-data-parser": {
+      "version": "0.1.0",
+      "resolved": "https://registry.npmjs.org/path-data-parser/-/path-data-parser-0.1.0.tgz",
+      "integrity": "sha512-NOnmBpt5Y2RWbuv0LMzsayp3lVylAHLPUTut412ZA3l+C4uw4ZVkQbjShYCQ8TCpUMdPapr4YjUqLYD6v68j+w==",
+      "license": "MIT"
+    },
     "node_modules/path-exists": {
       "version": "4.0.0",
       "resolved": "https://registry.npmjs.org/path-exists/-/path-exists-4.0.0.tgz",
@@ -9665,6 +10807,12 @@
       "dev": true,
       "license": "ISC"
     },
+    "node_modules/pathe": {
+      "version": "2.0.3",
+      "resolved": "https://registry.npmjs.org/pathe/-/pathe-2.0.3.tgz",
+      "integrity": "sha512-WUjGcAqP1gQacoQe+OBJsFA7Ld4DyXuUIjZ5cc75cLHvJ7dtNsTugphxIADwspS+AraAUePCKrSVtPLFj/F88w==",
+      "license": "MIT"
+    },
     "node_modules/picocolors": {
       "version": "1.1.1",
       "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz",
@@ -9681,6 +10829,33 @@
         "url": "https://github.com/sponsors/jonschlinkert"
       }
     },
+    "node_modules/pkg-types": {
+      "version": "2.3.0",
+      "resolved": "https://registry.npmjs.org/pkg-types/-/pkg-types-2.3.0.tgz",
+      "integrity": "sha512-SIqCzDRg0s9npO5XQ3tNZioRY1uK06lA41ynBC1YmFTmnY6FjUjVt6s4LoADmwoig1qqD0oK8h1p/8mlMx8Oig==",
+      "license": "MIT",
+      "dependencies": {
+        "confbox": "^0.2.2",
+        "exsolve": "^1.0.7",
+        "pathe": "^2.0.3"
+      }
+    },
+    "node_modules/points-on-curve": {
+      "version": "0.2.0",
+      "resolved": "https://registry.npmjs.org/points-on-curve/-/points-on-curve-0.2.0.tgz",
+      "integrity": "sha512-0mYKnYYe9ZcqMCWhUjItv/oHjvgEsfKvnUTg8sAtnHr3GVy7rGkXCb6d5cSyqrWqL4k81b9CPg3urd+T7aop3A==",
+      "license": "MIT"
+    },
+    "node_modules/points-on-path": {
+      "version": "0.2.1",
+      "resolved": "https://registry.npmjs.org/points-on-path/-/points-on-path-0.2.1.tgz",
+      "integrity": "sha512-25ClnWWuw7JbWZcgqY/gJ4FQWadKxGWk+3kR/7kD0tCaDtPPMj7oHu2ToLaVhfpnHrZzYby2w6tUA0eOIuUg8g==",
+      "license": "MIT",
+      "dependencies": {
+        "path-data-parser": "0.1.0",
+        "points-on-curve": "0.2.0"
+      }
+    },
     "node_modules/possible-typed-array-names": {
       "version": "1.1.0",
       "resolved": "https://registry.npmjs.org/possible-typed-array-names/-/possible-typed-array-names-1.1.0.tgz",
@@ -9880,6 +11055,22 @@
         "node": ">=6"
       }
     },
+    "node_modules/quansync": {
+      "version": "0.2.11",
+      "resolved": "https://registry.npmjs.org/quansync/-/quansync-0.2.11.tgz",
+      "integrity": "sha512-AifT7QEbW9Nri4tAwR5M/uzpBuqfZf+zwaEM/QkzEjj7NBuFD2rBuy0K3dE+8wltbezDV7JMA0WfnCPYRSYbXA==",
+      "funding": [
+        {
+          "type": "individual",
+          "url": "https://github.com/sponsors/antfu"
+        },
+        {
+          "type": "individual",
+          "url": "https://github.com/sponsors/sxzz"
+        }
+      ],
+      "license": "MIT"
+    },
     "node_modules/queue-microtask": {
       "version": "1.2.3",
       "resolved": "https://registry.npmjs.org/queue-microtask/-/queue-microtask-1.2.3.tgz",
@@ -10424,6 +11615,24 @@
         "url": "https://github.com/sponsors/isaacs"
       }
     },
+    "node_modules/robust-predicates": {
+      "version": "3.0.2",
+      "resolved": "https://registry.npmjs.org/robust-predicates/-/robust-predicates-3.0.2.tgz",
+      "integrity": "sha512-IXgzBWvWQwE6PrDI05OvmXUIruQTcoMDzRsOd5CDvHCVLcLHMTSYvOK5Cm46kWqlV3yAbuSpBZdJ5oP5OUoStg==",
+      "license": "Unlicense"
+    },
+    "node_modules/roughjs": {
+      "version": "4.6.6",
+      "resolved": "https://registry.npmjs.org/roughjs/-/roughjs-4.6.6.tgz",
+      "integrity": "sha512-ZUz/69+SYpFN/g/lUlo2FXcIjRkSu3nDarreVdGGndHEBJ6cXPdKguS8JGxwj5HA5xIbVKSmLgr5b3AWxtRfvQ==",
+      "license": "MIT",
+      "dependencies": {
+        "hachure-fill": "^0.5.2",
+        "path-data-parser": "^0.1.0",
+        "points-on-curve": "^0.2.0",
+        "points-on-path": "^0.2.1"
+      }
+    },
     "node_modules/run-applescript": {
       "version": "7.0.0",
       "resolved": "https://registry.npmjs.org/run-applescript/-/run-applescript-7.0.0.tgz",
@@ -10458,6 +11667,12 @@
         "queue-microtask": "^1.2.2"
       }
     },
+    "node_modules/rw": {
+      "version": "1.3.3",
+      "resolved": "https://registry.npmjs.org/rw/-/rw-1.3.3.tgz",
+      "integrity": "sha512-PdhdWy89SiZogBLaw42zdeqtRJ//zFd2PgQavcICDUgJT5oW10QCRKbJ6bg4r0/UY2M6BWd5tkxuGFRvCkgfHQ==",
+      "license": "BSD-3-Clause"
+    },
     "node_modules/safe-array-concat": {
       "version": "1.1.3",
       "resolved": "https://registry.npmjs.org/safe-array-concat/-/safe-array-concat-1.1.3.tgz",
@@ -10531,6 +11746,12 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
+    "node_modules/safer-buffer": {
+      "version": "2.1.2",
+      "resolved": "https://registry.npmjs.org/safer-buffer/-/safer-buffer-2.1.2.tgz",
+      "integrity": "sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg==",
+      "license": "MIT"
+    },
     "node_modules/scheduler": {
       "version": "0.25.0",
       "resolved": "https://registry.npmjs.org/scheduler/-/scheduler-0.25.0.tgz",
@@ -10616,15 +11837,15 @@
       }
     },
     "node_modules/sharp": {
-      "version": "0.34.2",
-      "resolved": "https://registry.npmjs.org/sharp/-/sharp-0.34.2.tgz",
-      "integrity": "sha512-lszvBmB9QURERtyKT2bNmsgxXK0ShJrL/fvqlonCo7e6xBF8nT8xU6pW+PMIbLsz0RxQk3rgH9kd8UmvOzlMJg==",
+      "version": "0.34.4",
+      "resolved": "https://registry.npmjs.org/sharp/-/sharp-0.34.4.tgz",
+      "integrity": "sha512-FUH39xp3SBPnxWvd5iib1X8XY7J0K0X7d93sie9CJg2PO8/7gmg89Nve6OjItK53/MlAushNNxteBYfM6DEuoA==",
       "hasInstallScript": true,
       "license": "Apache-2.0",
       "optional": true,
       "dependencies": {
-        "color": "^4.2.3",
-        "detect-libc": "^2.0.4",
+        "@img/colour": "^1.0.0",
+        "detect-libc": "^2.1.0",
         "semver": "^7.7.2"
       },
       "engines": {
@@ -10634,27 +11855,28 @@
         "url": "https://opencollective.com/libvips"
       },
       "optionalDependencies": {
-        "@img/sharp-darwin-arm64": "0.34.2",
-        "@img/sharp-darwin-x64": "0.34.2",
-        "@img/sharp-libvips-darwin-arm64": "1.1.0",
-        "@img/sharp-libvips-darwin-x64": "1.1.0",
-        "@img/sharp-libvips-linux-arm": "1.1.0",
-        "@img/sharp-libvips-linux-arm64": "1.1.0",
-        "@img/sharp-libvips-linux-ppc64": "1.1.0",
-        "@img/sharp-libvips-linux-s390x": "1.1.0",
-        "@img/sharp-libvips-linux-x64": "1.1.0",
-        "@img/sharp-libvips-linuxmusl-arm64": "1.1.0",
-        "@img/sharp-libvips-linuxmusl-x64": "1.1.0",
-        "@img/sharp-linux-arm": "0.34.2",
-        "@img/sharp-linux-arm64": "0.34.2",
-        "@img/sharp-linux-s390x": "0.34.2",
-        "@img/sharp-linux-x64": "0.34.2",
-        "@img/sharp-linuxmusl-arm64": "0.34.2",
-        "@img/sharp-linuxmusl-x64": "0.34.2",
-        "@img/sharp-wasm32": "0.34.2",
-        "@img/sharp-win32-arm64": "0.34.2",
-        "@img/sharp-win32-ia32": "0.34.2",
-        "@img/sharp-win32-x64": "0.34.2"
+        "@img/sharp-darwin-arm64": "0.34.4",
+        "@img/sharp-darwin-x64": "0.34.4",
+        "@img/sharp-libvips-darwin-arm64": "1.2.3",
+        "@img/sharp-libvips-darwin-x64": "1.2.3",
+        "@img/sharp-libvips-linux-arm": "1.2.3",
+        "@img/sharp-libvips-linux-arm64": "1.2.3",
+        "@img/sharp-libvips-linux-ppc64": "1.2.3",
+        "@img/sharp-libvips-linux-s390x": "1.2.3",
+        "@img/sharp-libvips-linux-x64": "1.2.3",
+        "@img/sharp-libvips-linuxmusl-arm64": "1.2.3",
+        "@img/sharp-libvips-linuxmusl-x64": "1.2.3",
+        "@img/sharp-linux-arm": "0.34.4",
+        "@img/sharp-linux-arm64": "0.34.4",
+        "@img/sharp-linux-ppc64": "0.34.4",
+        "@img/sharp-linux-s390x": "0.34.4",
+        "@img/sharp-linux-x64": "0.34.4",
+        "@img/sharp-linuxmusl-arm64": "0.34.4",
+        "@img/sharp-linuxmusl-x64": "0.34.4",
+        "@img/sharp-wasm32": "0.34.4",
+        "@img/sharp-win32-arm64": "0.34.4",
+        "@img/sharp-win32-ia32": "0.34.4",
+        "@img/sharp-win32-x64": "0.34.4"
       }
     },
     "node_modules/shebang-command": {
@@ -10775,16 +11997,6 @@
         "url": "https://github.com/sponsors/isaacs"
       }
     },
-    "node_modules/simple-swizzle": {
-      "version": "0.2.2",
-      "resolved": "https://registry.npmjs.org/simple-swizzle/-/simple-swizzle-0.2.2.tgz",
-      "integrity": "sha512-JA//kQgZtbuY83m+xT+tXJkmJncGMTFT+C+g2h2R9uxkYIrE2yy9sgmcLhCnw57/WSD+Eh3J97FPEDFnbXnDUg==",
-      "license": "MIT",
-      "optional": true,
-      "dependencies": {
-        "is-arrayish": "^0.3.1"
-      }
-    },
     "node_modules/sisteransi": {
       "version": "1.0.5",
       "resolved": "https://registry.npmjs.org/sisteransi/-/sisteransi-1.0.5.tgz",
@@ -10874,14 +12086,6 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
-    "node_modules/streamsearch": {
-      "version": "1.1.0",
-      "resolved": "https://registry.npmjs.org/streamsearch/-/streamsearch-1.1.0.tgz",
-      "integrity": "sha512-Mcc5wHehp9aXz1ax6bZUyY5afg9u2rv5cqQI3mRrYkGC8rW2hM02jWuwjtL++LS5qinSyhj2QfLyNsuc+VsExg==",
-      "engines": {
-        "node": ">=10.0.0"
-      }
-    },
     "node_modules/string_decoder": {
       "version": "1.3.0",
       "resolved": "https://registry.npmjs.org/string_decoder/-/string_decoder-1.3.0.tgz",
@@ -11173,6 +12377,12 @@
         }
       }
     },
+    "node_modules/stylis": {
+      "version": "4.3.6",
+      "resolved": "https://registry.npmjs.org/stylis/-/stylis-4.3.6.tgz",
+      "integrity": "sha512-yQ3rwFWRfwNUY7H5vpU0wfdkNSnvnJinhF9830Swlaxl03zsOjCfmX0ugac+3LtK0lYSgwL/KXc8oYL3mG4YFQ==",
+      "license": "MIT"
+    },
     "node_modules/supports-color": {
       "version": "7.2.0",
       "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-7.2.0.tgz",
@@ -11237,6 +12447,12 @@
       "integrity": "sha512-N+8UisAXDGk8PFXP4HAzVR9nbfmVJ3zYLAWiTIoqC5v5isinhr+r5uaO8+7r3BMfuNIufIsA7RdpVgacC2cSpw==",
       "dev": true
     },
+    "node_modules/tinyexec": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/tinyexec/-/tinyexec-1.0.1.tgz",
+      "integrity": "sha512-5uC6DDlmeqiOwCPmK9jMSdOuZTh8bU39Ys6yidB+UTt5hfZUPGAypSgFRiEp+jbi9qH40BLDvy85jIU88wKSqw==",
+      "license": "MIT"
+    },
     "node_modules/tinyglobby": {
       "version": "0.2.13",
       "resolved": "https://registry.npmjs.org/tinyglobby/-/tinyglobby-0.2.13.tgz",
@@ -11320,6 +12536,15 @@
         "typescript": ">=4.8.4"
       }
     },
+    "node_modules/ts-dedent": {
+      "version": "2.2.0",
+      "resolved": "https://registry.npmjs.org/ts-dedent/-/ts-dedent-2.2.0.tgz",
+      "integrity": "sha512-q5W7tVM71e2xjHZTlgfTDoPF/SmqKG5hddq9SzR49CH2hayqRKJtQ4mtRlSxKaJlR/+9rEM+mnBHf7I2/BQcpQ==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=6.10"
+      }
+    },
     "node_modules/ts-morph": {
       "version": "26.0.0",
       "resolved": "https://registry.npmjs.org/ts-morph/-/ts-morph-26.0.0.tgz",
@@ -11526,6 +12751,12 @@
         "node": ">=14.17"
       }
     },
+    "node_modules/ufo": {
+      "version": "1.6.1",
+      "resolved": "https://registry.npmjs.org/ufo/-/ufo-1.6.1.tgz",
+      "integrity": "sha512-9a4/uxlTWJ4+a5i0ooc1rU7C7YOw3wT+UGqdeNNHWnOF9qcMBgLRS+4IYUqbczewFx4mLEig6gawh7X6mFlEkA==",
+      "license": "MIT"
+    },
     "node_modules/unbox-primitive": {
       "version": "1.1.0",
       "resolved": "https://registry.npmjs.org/unbox-primitive/-/unbox-primitive-1.1.0.tgz",
@@ -11960,6 +13191,19 @@
       "resolved": "https://registry.npmjs.org/util-deprecate/-/util-deprecate-1.0.2.tgz",
       "integrity": "sha512-EPD5q1uXyFxJpCrLnCc1nHnq3gOa6DZBocAIiI2TaSCA7VCJ1UJDMagCzIkXNsUYfD1daK//LTEQ8xiIbrHtcw=="
     },
+    "node_modules/uuid": {
+      "version": "11.1.0",
+      "resolved": "https://registry.npmjs.org/uuid/-/uuid-11.1.0.tgz",
+      "integrity": "sha512-0/A9rDy9P7cJ+8w1c9WD9V//9Wj15Ce2MPz8Ri6032usz+NfePxx5AcN3bN+r6ZL6jEo066/yNYB3tn4pQEx+A==",
+      "funding": [
+        "https://github.com/sponsors/broofa",
+        "https://github.com/sponsors/ctavan"
+      ],
+      "license": "MIT",
+      "bin": {
+        "uuid": "dist/esm/bin/uuid"
+      }
+    },
     "node_modules/v8-compile-cache-lib": {
       "version": "3.0.1",
       "resolved": "https://registry.npmjs.org/v8-compile-cache-lib/-/v8-compile-cache-lib-3.0.1.tgz",
@@ -12131,6 +13375,55 @@
         "url": "https://opencollective.com/unified"
       }
     },
+    "node_modules/vscode-jsonrpc": {
+      "version": "8.2.0",
+      "resolved": "https://registry.npmjs.org/vscode-jsonrpc/-/vscode-jsonrpc-8.2.0.tgz",
+      "integrity": "sha512-C+r0eKJUIfiDIfwJhria30+TYWPtuHJXHtI7J0YlOmKAo7ogxP20T0zxB7HZQIFhIyvoBPwWskjxrvAtfjyZfA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=14.0.0"
+      }
+    },
+    "node_modules/vscode-languageserver": {
+      "version": "9.0.1",
+      "resolved": "https://registry.npmjs.org/vscode-languageserver/-/vscode-languageserver-9.0.1.tgz",
+      "integrity": "sha512-woByF3PDpkHFUreUa7Hos7+pUWdeWMXRd26+ZX2A8cFx6v/JPTtd4/uN0/jB6XQHYaOlHbio03NTHCqrgG5n7g==",
+      "license": "MIT",
+      "dependencies": {
+        "vscode-languageserver-protocol": "3.17.5"
+      },
+      "bin": {
+        "installServerIntoExtension": "bin/installServerIntoExtension"
+      }
+    },
+    "node_modules/vscode-languageserver-protocol": {
+      "version": "3.17.5",
+      "resolved": "https://registry.npmjs.org/vscode-languageserver-protocol/-/vscode-languageserver-protocol-3.17.5.tgz",
+      "integrity": "sha512-mb1bvRJN8SVznADSGWM9u/b07H7Ecg0I3OgXDuLdn307rl/J3A9YD6/eYOssqhecL27hK1IPZAsaqh00i/Jljg==",
+      "license": "MIT",
+      "dependencies": {
+        "vscode-jsonrpc": "8.2.0",
+        "vscode-languageserver-types": "3.17.5"
+      }
+    },
+    "node_modules/vscode-languageserver-textdocument": {
+      "version": "1.0.12",
+      "resolved": "https://registry.npmjs.org/vscode-languageserver-textdocument/-/vscode-languageserver-textdocument-1.0.12.tgz",
+      "integrity": "sha512-cxWNPesCnQCcMPeenjKKsOCKQZ/L6Tv19DTRIGuLWe32lyzWhihGVJ/rcckZXJxfdKCFvRLS3fpBIsV/ZGX4zA==",
+      "license": "MIT"
+    },
+    "node_modules/vscode-languageserver-types": {
+      "version": "3.17.5",
+      "resolved": "https://registry.npmjs.org/vscode-languageserver-types/-/vscode-languageserver-types-3.17.5.tgz",
+      "integrity": "sha512-Ld1VelNuX9pdF39h2Hgaeb5hEZM2Z3jUrrMgWQAu82jMtZp7p3vJT3BzToKtZI7NgQssZje5o0zryOrhQvzQAg==",
+      "license": "MIT"
+    },
+    "node_modules/vscode-uri": {
+      "version": "3.0.8",
+      "resolved": "https://registry.npmjs.org/vscode-uri/-/vscode-uri-3.0.8.tgz",
+      "integrity": "sha512-AyFQ0EVmsOZOlAnxoFOGOq1SQDWAB7C6aqMGS23svWAllfOaxbuFvcT8D1i8z3Gyn8fraVeZNNmN6e9bxxXkKw==",
+      "license": "MIT"
+    },
     "node_modules/walk-up-path": {
       "version": "3.0.1",
       "resolved": "https://registry.npmjs.org/walk-up-path/-/walk-up-path-3.0.1.tgz",
diff --git a/apps/docs/package.json b/apps/docs/package.json
index 0ce2bcc43..d5728a81b 100644
--- a/apps/docs/package.json
+++ b/apps/docs/package.json
@@ -25,11 +25,13 @@
     "fumadocs-mdx": "^11.6.5",
     "fumadocs-typescript": "^4.0.5",
     "fumadocs-ui": "^15.3.4",
-    "gt-next": "^6.2.5",
-    "gtx-cli": "^2.1.8",
+    "gt-next": "^6.6.2",
+    "gtx-cli": "^2.3.4",
     "lucide-react": "^0.483.0",
-    "next": "^15.3.2",
+    "mermaid": "^11.12.0",
+    "next": "^15.5.4",
     "next-sitemap": "^4.2.3",
+    "next-themes": "^0.4.6",
     "posthog-js": "^1.242.2",
     "posthog-node": "^4.17.1",
     "react": "^19.0.0",
diff --git a/apps/docs/public/core-demo.mp4 b/apps/docs/public/core-demo.mp4
new file mode 100644
index 000000000..aa08c82ea
Binary files /dev/null and b/apps/docs/public/core-demo.mp4 differ
diff --git a/apps/docs/public/core/quickstart/core-quickstart-1.png b/apps/docs/public/core/quickstart/core-quickstart-1.png
new file mode 100644
index 000000000..cd4afa0df
Binary files /dev/null and b/apps/docs/public/core/quickstart/core-quickstart-1.png differ
diff --git a/apps/docs/public/demo.gif b/apps/docs/public/demo.gif
new file mode 100644
index 000000000..4609721d3
Binary files /dev/null and b/apps/docs/public/demo.gif differ
diff --git a/apps/docs/public/locadex-screenshots/auto-merge/add-bypass.png b/apps/docs/public/locadex-screenshots/auto-merge/add-bypass.png
new file mode 100644
index 000000000..f8d5cb003
Binary files /dev/null and b/apps/docs/public/locadex-screenshots/auto-merge/add-bypass.png differ
diff --git a/apps/docs/public/locadex-screenshots/auto-merge/require-pull-request.png b/apps/docs/public/locadex-screenshots/auto-merge/require-pull-request.png
new file mode 100644
index 000000000..921019508
Binary files /dev/null and b/apps/docs/public/locadex-screenshots/auto-merge/require-pull-request.png differ
diff --git a/apps/docs/public/locadex-screenshots/auto-merge/run-configuration.png b/apps/docs/public/locadex-screenshots/auto-merge/run-configuration.png
new file mode 100644
index 000000000..6ea1ec3ea
Binary files /dev/null and b/apps/docs/public/locadex-screenshots/auto-merge/run-configuration.png differ
diff --git a/apps/docs/public/locadex-screenshots/deployment/deployment-section-edit-button.png b/apps/docs/public/locadex-screenshots/deployment/deployment-section-edit-button.png
new file mode 100644
index 000000000..d6277cb77
Binary files /dev/null and b/apps/docs/public/locadex-screenshots/deployment/deployment-section-edit-button.png differ
diff --git a/apps/docs/public/locadex-screenshots/deployment/deployment-section.png b/apps/docs/public/locadex-screenshots/deployment/deployment-section.png
new file mode 100644
index 000000000..24d080648
Binary files /dev/null and b/apps/docs/public/locadex-screenshots/deployment/deployment-section.png differ
diff --git a/apps/docs/public/locadex-screenshots/deployment/edit-locales.png b/apps/docs/public/locadex-screenshots/deployment/edit-locales.png
new file mode 100644
index 000000000..7794dac2d
Binary files /dev/null and b/apps/docs/public/locadex-screenshots/deployment/edit-locales.png differ
diff --git a/packages/cli/src/config/validateSettings.ts b/packages/cli/src/config/validateSettings.ts
index b77b0eae3..9089e5ce5 100644
--- a/packages/cli/src/config/validateSettings.ts
+++ b/packages/cli/src/config/validateSettings.ts
@@ -3,7 +3,6 @@ import { Settings } from '../types/index.js';
 import { logErrorAndExit } from '../console/logging.js';
 import fs from 'node:fs';
 import path from 'node:path';
-import { gt } from '../utils/gt.js';
 
 export function validateSettings(settings: Settings) {
   // Validate locales
diff --git a/packages/core/src/types-dir/uploadFiles.ts b/packages/core/src/types-dir/uploadFiles.ts
index de6491cb5..dd54c6e43 100644
--- a/packages/core/src/types-dir/uploadFiles.ts
+++ b/packages/core/src/types-dir/uploadFiles.ts
@@ -27,7 +27,7 @@ export type UploadData = {
 };
 
 export type UploadFilesOptions = {
-  sourceLocale: string;
+  sourceLocale?: string;
   modelProvider?: string;
   timeout?: number;
 };