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/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/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/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) 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) 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" +}