From 56417b236f5196a660ddfc3c94c8584501efed15 Mon Sep 17 00:00:00 2001
From: moss-bryophyta <261561981+moss-bryophyta@users.noreply.github.com>
Date: Thu, 5 Mar 2026 18:57:10 -0800
Subject: [PATCH 1/3] Add example app links to 5 high-impact docs pages
---
docs-templates/guides/dictionaries.mdx | 4 ++++
docs-templates/guides/t.mdx | 4 ++++
docs/en-US/next/guides/dictionaries.mdx | 4 ++++
docs/en-US/next/guides/dynamic-content.mdx | 4 ++++
docs/en-US/next/index.mdx | 4 ++++
docs/en-US/next/introduction.mdx | 4 ++++
6 files changed, 24 insertions(+)
diff --git a/docs-templates/guides/dictionaries.mdx b/docs-templates/guides/dictionaries.mdx
index 540b0ff..22f92cb 100644
--- a/docs-templates/guides/dictionaries.mdx
+++ b/docs-templates/guides/dictionaries.mdx
@@ -319,6 +319,10 @@ function MixedApproach() {
## Next steps
+
+ **See it in action:** Check out the [dictionary pattern example app](https://github.com/gt-examples/dictionary-pattern) for a working demo — [live preview](https://dictionary-pattern.generaltranslation.dev).
+
+
- [Languages Guide](__DOCS_PATH__/guides/languages) - Configure supported languages and locale settings
- [Dynamic Content Guide](/docs/key-concepts/dynamic-content) - Handle runtime translation needs
- API References:
diff --git a/docs-templates/guides/t.mdx b/docs-templates/guides/t.mdx
index bce51c7..276bb9a 100644
--- a/docs-templates/guides/t.mdx
+++ b/docs-templates/guides/t.mdx
@@ -215,5 +215,9 @@ The CLI will error on dynamic content in [``](__DOCS_PATH__/api/components/t)
## Next steps
+
+ **See it in action:** Check out the [`` component basics example app](https://github.com/gt-examples/t-component-basics) for a working demo — [live preview](https://t-component-basics.generaltranslation.dev).
+
+
- [Variable Components Guide](__DOCS_PATH__/guides/variables) - Handle dynamic content within JSX translations
- [Branching Components Guide](__DOCS_PATH__/guides/branches) - Add conditional logic to your translations
diff --git a/docs/en-US/next/guides/dictionaries.mdx b/docs/en-US/next/guides/dictionaries.mdx
index 9ddf320..8a36ee8 100644
--- a/docs/en-US/next/guides/dictionaries.mdx
+++ b/docs/en-US/next/guides/dictionaries.mdx
@@ -305,6 +305,10 @@ function MixedApproach() {
## Next steps
+
+ **See it in action:** Check out the [dictionary pattern example app](https://github.com/gt-examples/dictionary-pattern) for a working demo — [live preview](https://dictionary-pattern.generaltranslation.dev).
+
+
- [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:
diff --git a/docs/en-US/next/guides/dynamic-content.mdx b/docs/en-US/next/guides/dynamic-content.mdx
index 185dcf6..a356ad6 100644
--- a/docs/en-US/next/guides/dynamic-content.mdx
+++ b/docs/en-US/next/guides/dynamic-content.mdx
@@ -148,6 +148,10 @@ Dynamic translation consumes API quota on every request. Use caching and error h
## Next steps
+
+ **See it in action:** Check out the [dynamic content example app](https://github.com/gt-examples/dynamic-content-tx) for a working demo of `tx()` and `` — [live preview](https://dynamic-content-tx.generaltranslation.dev).
+
+
- [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:
diff --git a/docs/en-US/next/index.mdx b/docs/en-US/next/index.mdx
index 25fa56f..c5c222c 100644
--- a/docs/en-US/next/index.mdx
+++ b/docs/en-US/next/index.mdx
@@ -344,6 +344,10 @@ For production, you need to pre-translate content since runtime translation is d
## Next steps
+
+ **See it in action:** Browse [working example apps](/docs/next/tutorials/examples) to see `gt-next` patterns in real projects, or jump straight to the [app catalog](https://app-catalog.generaltranslation.dev).
+
+
- [`` Component Guide](/docs/next/guides/t) - Deep dive into the [``](/docs/next/api/components/t) component and JSX translation
- [String Translation Guide](/docs/next/guides/strings) - Using [`useGT`](/docs/next/api/strings/use-gt) and [`getGT`](/docs/next/api/strings/get-gt)
- [Variable Components](/docs/next/guides/variables) - Handle dynamic content with [``](/docs/next/api/components/var), [``](/docs/next/api/components/num), etc.
diff --git a/docs/en-US/next/introduction.mdx b/docs/en-US/next/introduction.mdx
index 645dea4..92351a8 100644
--- a/docs/en-US/next/introduction.mdx
+++ b/docs/en-US/next/introduction.mdx
@@ -238,6 +238,10 @@ See the [useTranslations API Reference](/docs/next/api/dictionary/use-translatio
## Next steps
+
+ **See it in action:** Browse [working example apps](/docs/next/tutorials/examples) showcasing each pattern, or explore the full [app catalog](https://app-catalog.generaltranslation.dev).
+
+
- Learn about how to set up your Next.js project with the SDK: [Quickstart](/docs/next/tutorials/quickstart)
- Learn about how to translate JSX content with the [``](/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/use-gt) hook: [String Translation Guide](/docs/next/guides/strings)
From 1516e02cf683d56f5172680b632e49d7d8d5462b Mon Sep 17 00:00:00 2001
From: moss-bryophyta <261561981+moss-bryophyta@users.noreply.github.com>
Date: Thu, 5 Mar 2026 19:10:35 -0800
Subject: [PATCH 2/3] Swap T guide + dynamic content for SSG + middleware
example links
Per Ernest's feedback: SSG and middleware are more pertinent than the
guide and dynamic content guide for example app links.
---
docs/en-US/next/guides/middleware.mdx | 4 ++++
docs/en-US/next/guides/ssg.mdx | 6 +++++-
2 files changed, 9 insertions(+), 1 deletion(-)
diff --git a/docs/en-US/next/guides/middleware.mdx b/docs/en-US/next/guides/middleware.mdx
index 2b5ab81..fd3f6d3 100644
--- a/docs/en-US/next/guides/middleware.mdx
+++ b/docs/en-US/next/guides/middleware.mdx
@@ -140,6 +140,10 @@ export const config = {
## Next steps
+
+ **See it in action:** The [static site generation example app](https://github.com/gt-examples/static-site-generation) includes a full middleware setup with locale routing — [live preview](https://static-site-generation.generaltranslation.dev).
+
+
- [SSG Guide](/docs/next/guides/ssg) - Static generation with locale routing
- [RTL Support](/docs/next/guides/rtl) - Right-to-left languages
- API References:
diff --git a/docs/en-US/next/guides/ssg.mdx b/docs/en-US/next/guides/ssg.mdx
index 95e9210..90784f2 100644
--- a/docs/en-US/next/guides/ssg.mdx
+++ b/docs/en-US/next/guides/ssg.mdx
@@ -191,6 +191,10 @@ To fix this issue, make sure that all of your route segment files (so typically
## Further reading
+
+ **See it in action:** Check out the [static site generation example app](https://github.com/gt-examples/static-site-generation) for a working demo — [live preview](https://static-site-generation.generaltranslation.dev).
+
+
- Check out the [middleware guide](/docs/next/guides/middleware) required for locale routing
- Check out the [release notes](/blog/gt-next_v6_10_0) for migrating from legacy SSG pattern
-- See an example app [here](https://github.com/generaltranslation/gt/tree/main/examples/next-ssg)
+- See an example app in the monorepo [here](https://github.com/generaltranslation/gt/tree/main/examples/next-ssg)
From 8f75b47fe4314d2f5bf1acd2baeac373b1e661d4 Mon Sep 17 00:00:00 2001
From: moss-bryophyta <261561981+moss-bryophyta@users.noreply.github.com>
Date: Fri, 6 Mar 2026 09:50:36 -0800
Subject: [PATCH 3/3] docs: add TanStack Start quickstart and overview
Adds gt-tanstack-start docs:
- Overview page with API walkthrough
- Quickstart with step-by-step setup guide
- Links to companion example app in generaltranslation/gt
Added to the sidebar between React and React Native.
---
docs/en-US/meta.json | 1 +
docs/en-US/tanstack-start/index.mdx | 255 +++++++++++++++++++++
docs/en-US/tanstack-start/introduction.mdx | 134 +++++++++++
docs/en-US/tanstack-start/meta.json | 11 +
4 files changed, 401 insertions(+)
create mode 100644 docs/en-US/tanstack-start/index.mdx
create mode 100644 docs/en-US/tanstack-start/introduction.mdx
create mode 100644 docs/en-US/tanstack-start/meta.json
diff --git a/docs/en-US/meta.json b/docs/en-US/meta.json
index cb6b8b2..62c9b2f 100644
--- a/docs/en-US/meta.json
+++ b/docs/en-US/meta.json
@@ -5,6 +5,7 @@
"./platform",
"./next",
"./react",
+ "./tanstack-start",
"./react-native",
"./react-core-linter",
"./node",
diff --git a/docs/en-US/tanstack-start/index.mdx b/docs/en-US/tanstack-start/index.mdx
new file mode 100644
index 0000000..1f6da17
--- /dev/null
+++ b/docs/en-US/tanstack-start/index.mdx
@@ -0,0 +1,255 @@
+---
+title: TanStack Start Quickstart
+description: Internationalize your TanStack Start app with gt-tanstack-start
+---
+
+**Prerequisites:** TanStack Start project with React 16.8+
+
+
+ **Experimental:** `gt-tanstack-start` is under active development and not yet recommended for production use.
+
+
+## Installation
+
+Install `gt-tanstack-start`, `gt-react`, and the `gt` CLI:
+
+
+
+ ```bash
+ npm i gt-tanstack-start gt-react
+ npm i -D gt
+ ```
+
+
+ ```bash
+ yarn add gt-tanstack-start gt-react
+ yarn add --dev gt
+ ```
+
+
+ ```bash
+ bun add gt-tanstack-start gt-react
+ bun add --dev gt
+ ```
+
+
+ ```bash
+ pnpm add gt-tanstack-start gt-react
+ pnpm add --save-dev gt
+ ```
+
+
+
+
+ `gt-react` is required as a direct dependency so the `gt` CLI can detect `` components in your source code.
+
+
+## Configuration
+
+### `gt.config.json`
+
+Create a `gt.config.json` in your project root:
+
+```json title="gt.config.json"
+{
+ "defaultLocale": "en",
+ "locales": ["es", "ja"],
+ "files": {
+ "gt": {
+ "output": "src/_gt/[locale].json"
+ }
+ }
+}
+```
+
+
+ Translation files **must** be inside `src/` for Vite's dynamic imports to work. Using `public/` will not work.
+
+
+### Translation loader
+
+Create a `loadTranslations.ts` file in your project root:
+
+```ts title="loadTranslations.ts"
+export default async function loadTranslations(locale: string) {
+ const translations = await import(`./src/_gt/${locale}.json`);
+ return translations.default;
+}
+```
+
+### Root route setup
+
+Update `src/routes/__root.tsx` to initialize GT and provide translations:
+
+```tsx title="src/routes/__root.tsx"
+import {
+ HeadContent,
+ Scripts,
+ createRootRoute,
+} from '@tanstack/react-router'
+import {
+ initializeGT,
+ GTProvider,
+ getTranslations,
+ getLocale,
+ LocaleSelector,
+} from 'gt-tanstack-start'
+import gtConfig from '../../gt.config.json'
+import loadTranslations from '../../loadTranslations'
+
+// Initialize GT at the module level
+initializeGT({
+ ...gtConfig,
+ loadTranslations,
+})
+
+export const Route = createRootRoute({
+ head: () => ({
+ meta: [
+ { charSet: 'utf-8' },
+ { name: 'viewport', content: 'width=device-width, initial-scale=1' },
+ ],
+ }),
+ loader: async () => {
+ return {
+ translations: await getTranslations(),
+ locale: getLocale(),
+ }
+ },
+ shellComponent: RootDocument,
+})
+
+function RootDocument({ children }: { children: React.ReactNode }) {
+ const { translations, locale } = Route.useLoaderData()
+ return (
+
+
+
+
+
+
+
+ {children}
+
+
+
+
+ )
+}
+```
+
+## Usage
+
+Wrap content in `` to translate it. Import `` from `gt-react`:
+
+```tsx title="src/routes/index.tsx"
+import { createFileRoute } from '@tanstack/react-router'
+import { T } from 'gt-react'
+
+export const Route = createFileRoute('/')({ component: Home })
+
+function Home() {
+ return (
+
+
Welcome to our app!
+
This content is automatically translated.
+
+ )
+}
+```
+
+
+ Import `` from `gt-react` (not `gt-tanstack-start`). The `gt` CLI scans for `gt-react` imports to find translatable content.
+
+
+## Generate translations
+
+### Using General Translation (recommended)
+
+Run the `gt translate` command to generate translations:
+
+```bash
+npx gt translate
+```
+
+This sends your content to the General Translation API and downloads translated JSON files to `src/_gt/`.
+
+You'll need environment variables for the API:
+
+```bash title=".env"
+GT_API_KEY="your-api-key"
+GT_PROJECT_ID="your-project-id"
+```
+
+Get your free API keys at [dash.generaltranslation.com](https://dash.generaltranslation.com/signup) or run:
+
+```bash
+npx gt auth
+```
+
+### Manual translations
+
+If you prefer to manage translations yourself:
+
+1. Generate source language files:
+
+ ```bash
+ npx gt generate
+ ```
+
+2. Translate the generated JSON files manually
+
+3. Place them at `src/_gt/{locale}.json`
+
+## Testing
+
+Start the dev server:
+
+
+
+ ```bash
+ npm run dev
+ ```
+
+
+ ```bash
+ yarn dev
+ ```
+
+
+ ```bash
+ bun run dev
+ ```
+
+
+ ```bash
+ pnpm dev
+ ```
+
+
+
+Visit [localhost:3000](http://localhost:3000) and use the locale selector to switch languages. Translations are loaded from local JSON files, so language switching is instant.
+
+## Deployment
+
+Add the translation step to your build script:
+
+```json title="package.json"
+{
+ "scripts": {
+ "build": "npx gt translate && vite build"
+ }
+}
+```
+
+## Example app
+
+See the complete working example: [tanstack-start-basic](https://github.com/generaltranslation/gt/tree/main/examples/tanstack-start-basic)
+
+---
+
+## Next steps
+
+- Read the [overview](/docs/tanstack-start/introduction) for a deeper look at the API
+- Learn about [variable components](/docs/react/guides/variables) like ``, ``, and ``
+- Explore the [`` component](/docs/react/api/components/t) API reference
diff --git a/docs/en-US/tanstack-start/introduction.mdx b/docs/en-US/tanstack-start/introduction.mdx
new file mode 100644
index 0000000..4891ede
--- /dev/null
+++ b/docs/en-US/tanstack-start/introduction.mdx
@@ -0,0 +1,134 @@
+---
+title: Overview
+description: Overview of General Translation's TanStack Start SDK
+---
+
+## Introduction
+
+`gt-tanstack-start` is an open-source internationalization (i18n) integration for [TanStack Start](https://tanstack.com/start) applications.
+
+It brings the same developer experience as [`gt-next`](/docs/next) — wrap content in ``, and it gets translated — to the TanStack Start framework. Built on top of [`gt-react`](/docs/react), it adds TanStack Start–specific features like isomorphic locale detection and root loader integration.
+
+
+ **Experimental:** `gt-tanstack-start` is under active development. APIs may change between minor versions. It is not yet recommended for production use.
+
+
+## How it works
+
+
+
+ Initialize with [`initializeGT()`](#initialization-with-initializegt) in your root route
+
+
+ Load translations in the [root loader](#root-loader)
+
+
+ Wrap your app with [``](#the-gtprovider-component)
+
+
+ Use [``](#the-t-component) to translate content
+
+
+
+## Initialization with `initializeGT`
+
+The `initializeGT()` function configures the i18n manager. Call it at the top of your root route file:
+
+```tsx title="src/routes/__root.tsx"
+import { initializeGT } from 'gt-tanstack-start'
+import gtConfig from '../../gt.config.json'
+import loadTranslations from '../../loadTranslations'
+
+initializeGT({
+ ...gtConfig,
+ loadTranslations,
+})
+```
+
+## Root loader
+
+Use `getTranslations()` and `getLocale()` in your root route's loader to fetch the right translations for the current request:
+
+```tsx title="src/routes/__root.tsx"
+import { getTranslations, getLocale } from 'gt-tanstack-start'
+
+export const Route = createRootRoute({
+ loader: async () => {
+ return {
+ translations: await getTranslations(),
+ locale: getLocale(),
+ }
+ },
+ // ...
+})
+```
+
+## The `` component
+
+The `` provides translation context to all child components. Pass the translations and locale from the loader:
+
+```tsx title="src/routes/__root.tsx"
+import { GTProvider } from 'gt-tanstack-start'
+
+function RootDocument({ children }: { children: React.ReactNode }) {
+ const { translations, locale } = Route.useLoaderData()
+ return (
+
+
+
+
+
+
+ {children}
+
+
+
+
+ )
+}
+```
+
+## The `` component
+
+The [``](/docs/react/api/components/t) component translates JSX content. Wrap any elements and they render in the user's language:
+
+```tsx
+import { T } from 'gt-react'
+
+function Welcome() {
+ return (
+
+
Welcome to our app!
+
This content is automatically translated.
+
+ )
+}
+```
+
+
+ Import `` from `gt-react`, not from `gt-tanstack-start`. This ensures the `gt` CLI can detect your translatable content when generating translation files.
+
+
+## Locale selector
+
+Add a `` to let users switch languages:
+
+```tsx
+import { LocaleSelector } from 'gt-tanstack-start'
+
+function Nav() {
+ return (
+
+ )
+}
+```
+
+---
+
+## Next steps
+
+- Set up your project with the [quickstart guide](/docs/tanstack-start)
+- Browse the [example app](https://github.com/generaltranslation/gt/tree/main/examples/tanstack-start-basic)
+- Learn about [variable components](/docs/react/guides/variables) like ``, ``, and ``
diff --git a/docs/en-US/tanstack-start/meta.json b/docs/en-US/tanstack-start/meta.json
new file mode 100644
index 0000000..d613cbc
--- /dev/null
+++ b/docs/en-US/tanstack-start/meta.json
@@ -0,0 +1,11 @@
+{
+ "title": "TanStack Start",
+ "icon": "Layers",
+ "pages": [
+ "---Getting Started---",
+ "./introduction",
+ "./index"
+ ],
+ "root": true,
+ "description": "gt-tanstack-start"
+}