From cbc0862f5f4e4a68411e730257c66103a8b2c554 Mon Sep 17 00:00:00 2001 From: JoshKappler Date: Sun, 19 Jul 2026 14:58:00 -0700 Subject: [PATCH 1/4] docs(python): fix quickstart version claim, CLI invocation, and run instructions --- docs/en-US/python/quickstart.mdx | 21 ++++++++++++++++++--- 1 file changed, 18 insertions(+), 3 deletions(-) diff --git a/docs/en-US/python/quickstart.mdx b/docs/en-US/python/quickstart.mdx index 266c68700..f7eaff9b8 100644 --- a/docs/en-US/python/quickstart.mdx +++ b/docs/en-US/python/quickstart.mdx @@ -16,7 +16,7 @@ The General Translation Python SDK translates user-facing strings in Flask and F Install the integration for your framework: `gt-flask` for Flask, `gt-fastapi` for FastAPI. Both build on the shared `gt-i18n` runtime, which you can also use directly in a non-framework project. - The Python SDK is **experimental and unstable** — `gt-i18n`, `gt-flask`, and `gt-fastapi` are all at version 0.3.0 and may have breaking changes. It requires Python 3.10 or later. + The Python SDK is **experimental and unstable**. `gt-i18n`, `gt-flask`, and `gt-fastapi` are still in early development and may have breaking changes between releases. It requires Python 3.10 or later. ## What the Python SDK does [#overview] @@ -59,6 +59,8 @@ Create a `gt.config.json` at your project root with your Project ID and locales. } ``` +With the placeholder `projectId`, the app still runs and the request locale still changes, but every string comes back in the source language. That is expected until you set your own Project ID and publish translations. + ### 3. Initialize with your app Call `initialize_gt(app)` once at startup. It reads `gt.config.json`, registers per-request locale detection, and eager-loads translations. There is no API key parameter — CDN loading uses `project_id` and `cache_url`. @@ -76,6 +78,12 @@ Call `initialize_gt(app)` once at startup. It reads `gt.config.json`, registers def index(): return {"message": t("Hello, world!"), "locale": get_locale()} ``` + + Run it with: + + ```bash + flask --app app run + ``` @@ -90,6 +98,13 @@ Call `initialize_gt(app)` once at startup. It reads `gt.config.json`, registers def index(): return {"message": t("Hello, world!"), "locale": get_locale()} ``` + + FastAPI needs a separate ASGI server. Install Uvicorn and start the app with: + + ```bash + pip install "uvicorn[standard]" + uvicorn main:app + ``` @@ -103,10 +118,10 @@ t("Hello, {name}!", name="Alice") ### 5. Generate translations -Use the [General Translation CLI](/docs/cli/quickstart) to translate your content before you deploy, so translations are available at runtime. +Use the [General Translation CLI](/docs/cli/quickstart) to translate your content before you deploy, so translations are available at runtime. The CLI is a Node tool, so it needs Node installed and runs through `npx`. ```bash -gt translate +npx gt translate ``` ## Use the core library without a framework [#core] From cba7f142b29dc3bd7af5056836f9441b7839713a Mon Sep 17 00:00:00 2001 From: JoshKappler Date: Sun, 19 Jul 2026 15:03:06 -0700 Subject: [PATCH 2/4] docs(react): warn that _gt files must be generated before first run --- docs/en-US/react/nextjs-pages-router-quickstart.mdx | 4 ++++ docs/en-US/react/nextjs-quickstart.mdx | 4 ++++ docs/en-US/react/react-native-quickstart.mdx | 4 ++++ docs/en-US/react/tanstack-start-quickstart.mdx | 4 ++++ 4 files changed, 16 insertions(+) diff --git a/docs/en-US/react/nextjs-pages-router-quickstart.mdx b/docs/en-US/react/nextjs-pages-router-quickstart.mdx index b8881c9b1..f99ca248e 100644 --- a/docs/en-US/react/nextjs-pages-router-quickstart.mdx +++ b/docs/en-US/react/nextjs-pages-router-quickstart.mdx @@ -117,6 +117,10 @@ export default async function loadTranslations(locale: string) { } ``` + + **Note:** These translation files do not exist until you create them with `npx gt generate` (no API key needed) or `npx gt translate` (with credentials). Until then the bundler warns about the missing `public/_gt` directory, and the `try`/`catch` above returns `{}` so the app still runs with untranslated content. + + `withGTConfig` automatically detects a `loadTranslations.[js|ts]` file in your project root or `src/` directory — no additional configuration needed. diff --git a/docs/en-US/react/nextjs-quickstart.mdx b/docs/en-US/react/nextjs-quickstart.mdx index 623530656..264281551 100644 --- a/docs/en-US/react/nextjs-quickstart.mdx +++ b/docs/en-US/react/nextjs-quickstart.mdx @@ -113,6 +113,10 @@ export default async function loadTranslations(locale: string) { } ``` + + **Warning:** These translation files do not exist until you create them, so the first `npm run dev` fails to compile and the page returns HTTP 500. Run `npx gt generate` (no API key needed) or `npx gt translate` (with credentials), or add empty `{}` files at `public/_gt/[locale].json`. + + `withGTConfig` automatically detects a `loadTranslations.[js|ts]` file in your `src/` directory or project root — no additional configuration needed. diff --git a/docs/en-US/react/react-native-quickstart.mdx b/docs/en-US/react/react-native-quickstart.mdx index 464d6b02f..c1dbf0809 100644 --- a/docs/en-US/react/react-native-quickstart.mdx +++ b/docs/en-US/react/react-native-quickstart.mdx @@ -145,6 +145,10 @@ export function loadTranslations(locale: string) { The CLI generates these files when you run `npx gt translate`. + + **Warning:** These files do not exist until you create them, and Metro will not bundle your app until they do. Run `npx gt generate` (no API key needed) or `npx gt translate` (with credentials) before starting the app. + + ### 5. Initialize General Translation and add the provider Call [`initializeGT`](/docs/node/reference/functions/initialize-gt) once at your app's entry point, before rendering, then wrap your app in `GTProvider`. Unlike the web packages, `GTProvider` loads translations internally, so you do not pass a `translations` prop and normally do not need to pass `locale` either — it is auto-detected. An optional `locale` prop is still accepted if you need to override detection. diff --git a/docs/en-US/react/tanstack-start-quickstart.mdx b/docs/en-US/react/tanstack-start-quickstart.mdx index bcb1a5dfe..13399a214 100644 --- a/docs/en-US/react/tanstack-start-quickstart.mdx +++ b/docs/en-US/react/tanstack-start-quickstart.mdx @@ -139,6 +139,10 @@ function RootDocument({ children }: { children: React.ReactNode }) { `parseLocale` reads the locale from the request cookie and headers on the server, and from the cookie in the browser. `GTProvider` requires both `locale` and `translations`. + + **Warning:** These translation files (`src/_gt/[locale].json`) do not exist until you create them. The default locale still renders, but selecting a target locale in the language switcher returns HTTP 500 until the files exist. Run `npx gt generate` (no API key needed) or `npx gt translate` (with credentials) to create them first. + + ### 5. Mark content for translation Wrap JSX in the `` component to translate it in place. Import `` and [`useGT`](/docs/react/reference/hooks/use-gt) from `gt-react` so the CLI detects them when scanning your source. From 900c683e975a986b3a0886a10c1f59323272beff Mon Sep 17 00:00:00 2001 From: JoshKappler Date: Sun, 19 Jul 2026 15:01:08 -0700 Subject: [PATCH 3/4] docs(cli): document non-interactive setup for CI --- docs/en-US/cli/quickstart.mdx | 50 +++++++++++++++++++++++++++++++++-- 1 file changed, 48 insertions(+), 2 deletions(-) diff --git a/docs/en-US/cli/quickstart.mdx b/docs/en-US/cli/quickstart.mdx index a0fc2a178..bb36a21dd 100644 --- a/docs/en-US/cli/quickstart.mdx +++ b/docs/en-US/cli/quickstart.mdx @@ -34,7 +34,7 @@ Use the CLI when you want to: - Keep translations in version control alongside your source content. ## Quickstart [#quickstart] -Install `gt`, configure your project, and run your first translation. +Install `gt`, configure your project, and run your first translation. You need an existing project with a `package.json` and Node.js installed. ### 1. Install `gt` @@ -74,13 +74,19 @@ Run the setup wizard to detect your framework, create a `gt.config.json`, and ge npx gt init ``` + + **Warning:** `gt init` is an interactive wizard and needs a terminal. In CI or any non-interactive shell it cannot prompt, so it may exit without creating `gt.config.json` or writing credentials, sometimes with a success exit code. For those environments, use [Non-interactive setup for CI](#ci-setup). + + The wizard sets your default locale and target locales, chooses where translations are stored, and writes your API key and Project ID to `.env.local`. See [Configuring the CLI](/docs/cli/guides/configuring) to set this up in detail, or [`gt init`](/docs/cli/reference/commands/init) for the full command. +*Note: You should now have a `gt.config.json` at your project root and a `.env.local` file containing `GT_API_KEY` and `GT_PROJECT_ID`.* + ### 3. Add your production API key The [`translate`](/docs/cli/reference/commands/translate) command requires a production API key and Project ID. The wizard can generate these for you, or create them on the [API Keys page](https://generaltranslation.com/dashboard). Set them as environment variables so the CLI can read them. -```bash title=".env" +```bash title=".env.local" GT_API_KEY=your-api-key GT_PROJECT_ID=your-project-id ``` @@ -96,3 +102,43 @@ npx gt translate ``` Translations are saved to your codebase, ready to commit. Run this in your CI pipeline before you build for production. See [Generating translations](/docs/cli/guides/generating-translations) for the full workflow. + +## Non-interactive setup for CI [#ci-setup] + +The setup wizard needs an interactive terminal, so it cannot run in CI or other non-interactive environments. Set those up by hand: commit a `gt.config.json`, provide your credentials as environment variables, and run `translate` against that config. + +### 1. Add a `gt.config.json` + +Write the file yourself and commit it so the CLI knows what to translate. A minimal config sets the source and target locales and a `files` entry so `translate` has something to work on. The `gt` entry below stores framework translations (from `gt-next`, `gt-react`, or `gt-react-native`) locally at the given path. + +```json title="gt.config.json" +{ + "$schema": "https://assets.gtx.dev/config-schema.json", + "defaultLocale": "en", + "locales": ["fr", "es"], + "files": { + "gt": { + "output": "public/i18n/[locale].json" + } + } +} +``` + +To translate standalone files instead, add a file type such as `json` or `mdx` with an `include` glob in place of (or alongside) the `gt` entry. See [Configuring the CLI](/docs/cli/guides/configuring) for the file and storage options, and the [configuration reference](/docs/cli/reference/config) for every field. + +### 2. Set your credentials + +Set your production API key and Project ID as environment variables in your CI provider's secret settings, not in a committed file. Create them on the [API Keys page](https://generaltranslation.com/dashboard). + +```bash +GT_API_KEY=your-api-key +GT_PROJECT_ID=your-project-id +``` + +### 3. Run the translate command + +Run `translate` before you build for production. Pass `--config` to point at your config file. + +```bash +npx gt translate --config gt.config.json +``` From 66afde02e489eda5fa207c6f4406e7240fb1932e Mon Sep 17 00:00:00 2001 From: JoshKappler Date: Sun, 19 Jul 2026 15:02:21 -0700 Subject: [PATCH 4/4] docs(node): make quickstart runnable end to end --- docs/en-US/node/quickstart.mdx | 40 +++++++++++++++++++++++++++------- 1 file changed, 32 insertions(+), 8 deletions(-) diff --git a/docs/en-US/node/quickstart.mdx b/docs/en-US/node/quickstart.mdx index c3dbba349..df4343289 100644 --- a/docs/en-US/node/quickstart.mdx +++ b/docs/en-US/node/quickstart.mdx @@ -31,34 +31,36 @@ Install the library, initialize it, bind a locale per request, and translate a s ### 1. Install `gt-node` -Install `gt-node` as a dependency and the [`gt` CLI](/docs/cli/quickstart) as a dev dependency. +Install `gt-node` and Express as dependencies and the [`gt` CLI](/docs/cli/quickstart) as a dev dependency. ```bash - npm install gt-node && npm install gt --save-dev + npm install gt-node express && npm install gt --save-dev ``` ```bash - yarn add gt-node && yarn add --dev gt + yarn add gt-node express && yarn add --dev gt ``` ```bash - bun add gt-node && bun add --dev gt + bun add gt-node express && bun add --dev gt ``` ```bash - pnpm add gt-node && pnpm add --save-dev gt + pnpm add gt-node express && pnpm add --save-dev gt ``` +*Note: The server code below uses ES module `import` syntax. Set `"type": "module"` in your `package.json` so Node.js can run it.* + ### 2. Initialize the library Call [`initializeGT`](/docs/node/reference/functions/initialize-gt) once at startup, before handling requests. Pass your locales and credentials — `gt-node` does not read `gt.config.json` or environment variables automatically. @@ -77,7 +79,7 @@ initializeGT({ Wrap each request in `withGT` so translation functions know the target locale. Use [`getRequestLocale`](/docs/node/reference/functions/get-request-locale) to detect it from the `Accept-Language` header. -```ts title="server.js" +```js title="server.js" import express from 'express'; import { withGT, getRequestLocale } from 'gt-node'; @@ -89,16 +91,36 @@ app.use((req, res, next) => withGT(getRequestLocale(req), () => next())); Inside a handler, await `getGT` to get a translation function for the request's locale, then translate strings. Interpolate values with ICU placeholders. -```ts title="server.js" +```js title="server.js" import { getGT } from 'gt-node'; app.get('/api/greeting', async (req, res) => { const gt = await getGT(); res.json({ message: gt('Hello, {name}!', { name: 'Alice' }) }); }); + +app.listen(3000, () => console.log('Listening on http://localhost:3000')); +``` + +### 5. Run and verify + +Start the server and request the endpoint. Before you generate translations, the handler returns your source string, which confirms the service is wired up correctly. + +```bash +node server.js +``` + +In another terminal, send a request: + +```bash +curl http://localhost:3000/api/greeting +``` + +```json title="Output" +{"message":"Hello, Alice!"} ``` -### 5. Generate translations +### 6. Generate translations Run the CLI before you deploy to production so translations are available at runtime. @@ -106,4 +128,6 @@ Run the CLI before you deploy to production so translations are available at run npx gt translate ``` +*Note: `gt translate` reads a `gt.config.json` and requires a Project ID and API key. Run [`npx gt init`](/docs/cli/quickstart) first to create them.* + See [Translating strings](/docs/node/guides/translating-strings) for when to use `getGT`, `msg`, and `tx`, and [Configuring gt-node](/docs/node/guides/configuring) for credentials and delivery.