From a634245c3334a7c5adfb6c83d2e6552f1f6384fb Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Fri, 17 Jul 2026 23:41:01 +0000 Subject: [PATCH 1/6] fix: correct post-refactor documentation links --- DOCS-SKILL.md | 13 ++++++------- blog/en-US/ai-chatbot.mdx | 2 +- blog/en-US/best-localization-software.mdx | 8 ++++---- blog/en-US/i18n-without-translation-files.mdx | 2 +- blog/en-US/multilingual-nextjs-seo.mdx | 4 ++-- .../nextjs-i18n-code-is-the-source-of-truth.mdx | 12 ++++++------ blog/en-US/plurals.mdx | 4 ++-- docs/en-US/integrations/mintlify/quickstart.mdx | 2 +- .../integrations/mintlify/reference/locales.mdx | 2 +- docs/en-US/overview/for-coding-agents.mdx | 4 +--- docs/en-US/platform/index.mdx | 2 +- docs/en-US/react/nextjs-quickstart.mdx | 4 ++-- 12 files changed, 28 insertions(+), 31 deletions(-) diff --git a/DOCS-SKILL.md b/DOCS-SKILL.md index 2eae1247e..bb89f38e6 100644 --- a/DOCS-SKILL.md +++ b/DOCS-SKILL.md @@ -250,12 +250,11 @@ The **overview** section doubles as a **landing hub**: its `meta.json` lists the ### Machine-readable outputs -The docs are written to be consumed by LLMs and agents, not only humans. Alongside the filetree, publish two machine-readable maps at the repo root, both **generated from the** `meta.json` **filetree** (never hand-edited): +The docs are written to be consumed by LLMs and agents, not only humans. Publish `llms.txt` at the site root, generated from the `meta.json` filetree and never hand-edited: - `llms.txt` — an [llmstxt.org](https://llmstxt.org/)-style index for LLMs and agents: an H1, a one-line blockquote summary, then per-section lists of `- [Title](url): description` links. -- `sitemap.md` — a linked, hierarchical map of every published page in navigation order. -Regenerate both whenever you add, rename, remove, or reorder pages, so they stay in sync with the `meta.json` filetree. **Only include pages that actually exist** — omit in-progress sections and manifest-only stubs, and keep every link resolvable. +Regenerate it whenever you add, rename, remove, or reorder pages, so it stays in sync with the `meta.json` filetree. **Only include pages that actually exist** — omit in-progress sections and manifest-only stubs, and keep every link resolvable. ### Agent-navigable by default @@ -265,9 +264,9 @@ Beyond the two maps above, the docs follow these agent best practices so an agen Document these entry points for developers on the **Overview → For coding agents** page (see For coding agents page). -### AGENTS.md (for product users' agents) +### Drop-in AGENTS.md guide -Publish a root `AGENTS.md` aimed at the **coding agents of developers who use General Translation** — *not* at agents editing this docs repo. A developer drops it (or its contents) into their own project so their agent knows how to add and run General Translation correctly. Keep it self-contained, imperative, and short enough to fit an agent's context window. +Embed a copyable `AGENTS.md` guide on the **For coding agents** page, aimed at the **coding agents of developers who use General Translation** — *not* at agents editing this docs repo. A developer drops its contents into their own project so their agent knows how to add and run General Translation correctly. Keep it self-contained, imperative, and short enough to fit an agent's context window. Structure it in this order: @@ -276,7 +275,7 @@ Structure it in this order: 3. **Core usage** — the canonical patterns the agent should follow (for example, wrap user-facing strings in ``, use `useGT()` for dynamic strings, keep locale configuration in one place). Show minimal, commented code. 4. **Commands** — a short cheat-sheet of the CLI commands the agent will run (`npx gt configure`, `npx gt translate`, and so on) and when to run each. 5. **Rules — do and don't** — explicit guardrails: what to always do (wrap new copy, run `gt translate` before committing) and what never to do (hardcode translated strings, hand-edit generated translation files). -6. **Links** — point to `llms.txt`, the sitemap, and the most useful pages for deeper detail. +6. **Links** — point to `llms.txt` and the most useful pages for deeper detail. Document only capabilities that exist, and resolve anything uncertain against the codebase (see Source of truth and best judgement). This file is written by an agent connected to the product codebase; this guide defines its **shape**, not its exact contents. @@ -715,5 +714,5 @@ These patterns are **blocked by CI** and will fail the build, so never use them - Reference descriptions end with a second sentence: `API reference for X.` for API/library pages, or `Reference for X.` for non-API reference pages (ending with a period). - No broken internal links (verify the target file exists). - `related.links` follow the page-type rule: quickstart/entry pages point to four of that section's guides (or all if the section has fewer than four); guide pages link **all** the section's other guides, trimming to the four most relevant only when there are more than four others; neither links reference pages or quickstarts (the guide-less OpenAPI section is the only exception). -- **Machine-readable outputs are in sync:** every entry in each `meta.json` `pages` array resolves to a real file, and `llms.txt` and `sitemap.md` have been regenerated so they list only existing pages. +- **Machine-readable outputs are in sync:** every entry in each `meta.json` `pages` array resolves to a real file, and `llms.txt` has been regenerated so it lists only existing pages. - No typos; body prose sentences end with periods, and so do descriptions (a description that is a question ends with `?`; section-root tab subtitles take no period). diff --git a/blog/en-US/ai-chatbot.mdx b/blog/en-US/ai-chatbot.mdx index 3e9ac2d87..932830b0f 100644 --- a/blog/en-US/ai-chatbot.mdx +++ b/blog/en-US/ai-chatbot.mdx @@ -91,7 +91,7 @@ export default withGTConfig(nextConfig, { I could've added more locales, but I just wanted to test the chatbot with a few different languages. Feel free to add as many locales as you want! -[Here's a list of all of the ones supported by gt-next](https://generaltranslation.com/docs/platform/supported-locales). +[Here's a list of all of the ones supported by gt-next](https://generaltranslation.com/docs/platform/dashboard/reference/supported-locales). ### How it works diff --git a/blog/en-US/best-localization-software.mdx b/blog/en-US/best-localization-software.mdx index a9424cb5f..136f52623 100644 --- a/blog/en-US/best-localization-software.mdx +++ b/blog/en-US/best-localization-software.mdx @@ -26,7 +26,7 @@ General Translation is not a library. It's not a TMS. It's the whole pipeline, u - **Open-source developer libraries**: [`gt-next`](https://generaltranslation.com/docs/react/nextjs), [`gt-react`](https://generaltranslation.com/docs/react), and support for [React Native/Expo](https://generaltranslation.com/docs/react/react-native). Drop-in SDKs with full TypeScript support. - **An AI-first translation platform** that understands your codebase, your product, and your terminology. Not generic machine translation bolted on top. -- **Locadex, the AI agent**: an [automated internationalization engineer](https://generaltranslation.com/docs/locadex) that scans your codebase, internationalizes your code, creates translations, and opens pull requests on every push. +- **Locadex, the AI agent**: an [automated internationalization engineer](https://generaltranslation.com/docs/platform/locadex/quickstart) that scans your codebase, internationalizes your code, creates translations, and opens pull requests on every push. Building both the library and the translation engine together makes localization ten times easier. No JSON export/import, no file management, no agencies to coordinate. Translations flow directly from your source code to production. @@ -58,7 +58,7 @@ At 10 languages and 500 keys, that's 5,000 entries to maintain. At 50 languages ## How General Translation closes the loop -**1. Install and write code.** Run the [setup wizard](https://generaltranslation.com/docs/next/quickstart) and wrap content in `` components. No key extraction. No JSON files. +**1. Install and write code.** Run the [setup wizard](https://generaltranslation.com/docs/cli/reference/commands/init) and wrap content in `` components. No key extraction. No JSON files. ```tsx import { T } from 'gt-next'; @@ -75,9 +75,9 @@ export default function Home() { **2. Develop.** Translations appear on-demand. Switch languages and see results immediately. -**3. Ship.** One command generates all translations at build time. They're pre-generated, cached, and delivered via CDN. Sub-50ms globally. [See the deploy guide →](https://generaltranslation.com/docs/next/quickstart#deploy) +**3. Ship.** One command generates all translations at build time. They're pre-generated, cached, and delivered via CDN. Sub-50ms globally. [See the deploy guide →](https://generaltranslation.com/docs/react/nextjs-quickstart#11-deploy-to-production) -**4. Automate.** [Locadex](https://generaltranslation.com/docs/locadex) monitors your repo. When you push code, it scans for changes, internationalizes new content, generates translations, and opens a PR. No human in the loop unless you want one. If you do, the translation editor gives you side-by-side diffs with the ability to edit before or after content goes live. +**4. Automate.** [Locadex](https://generaltranslation.com/docs/platform/locadex/quickstart) monitors your repo. When you push code, it scans for changes, internationalizes new content, generates translations, and opens a PR. No human in the loop unless you want one. If you do, the translation editor gives you side-by-side diffs with the ability to edit before or after content goes live. ## Why most translation AI gets it wrong diff --git a/blog/en-US/i18n-without-translation-files.mdx b/blog/en-US/i18n-without-translation-files.mdx index e1baad441..a38ec237c 100644 --- a/blog/en-US/i18n-without-translation-files.mdx +++ b/blog/en-US/i18n-without-translation-files.mdx @@ -118,6 +118,6 @@ But most developers are already thinking in one language when they build UI. The npx gt@latest init ``` -The setup wizard configures your project, installs dependencies, and sets up translation hot reloading for development. Full walkthrough in the [quickstart guide](https://generaltranslation.com/docs/react). +The setup wizard configures your project, installs dependencies, and sets up translation hot reloading for development. Full walkthrough in the [quickstart guide](https://generaltranslation.com/docs/react/react-quickstart). `gt-react` is open source. For Next.js App Router, there's [`gt-next`](https://generaltranslation.com/docs/react/nextjs). For React Native, there's [`gt-react-native`](https://generaltranslation.com/docs/react/react-native). diff --git a/blog/en-US/multilingual-nextjs-seo.mdx b/blog/en-US/multilingual-nextjs-seo.mdx index 228b5f8be..1a30847bb 100644 --- a/blog/en-US/multilingual-nextjs-seo.mdx +++ b/blog/en-US/multilingual-nextjs-seo.mdx @@ -311,7 +311,7 @@ Here's a quick summary of everything covered: ## Next steps -- [gt-next quickstart](https://generaltranslation.com/docs/react/nextjs) to set up the full i18n stack +- [gt-next quickstart](https://generaltranslation.com/docs/react/nextjs-quickstart) to set up the full i18n stack - [Middleware guide](/docs/react/nextjs/app-router-middleware) for routing configuration -- [SSG guide](/docs/react/nextjs) for statically generating multilingual pages +- [SSG guide](/docs/react/nextjs/app-router-static-site-generation) for statically generating multilingual pages - [RTL support](/docs/react/guides/managing-locales) for right-to-left languages diff --git a/blog/en-US/nextjs-i18n-code-is-the-source-of-truth.mdx b/blog/en-US/nextjs-i18n-code-is-the-source-of-truth.mdx index d49026952..2f7421c6f 100644 --- a/blog/en-US/nextjs-i18n-code-is-the-source-of-truth.mdx +++ b/blog/en-US/nextjs-i18n-code-is-the-source-of-truth.mdx @@ -38,13 +38,13 @@ No keys. No JSON files. No cross-referencing. The source of truth is your code. ## Setup -The syntax above comes from [gt-next](https://generaltranslation.com/docs/react/nextjs), an open-source i18n library for Next.js App Router. Getting started takes one command: +The syntax above comes from [gt-next](https://generaltranslation.com/docs/react/nextjs-quickstart), an open-source i18n library for Next.js App Router. Getting started takes one command: ```bash copy npx gt@latest init ``` -The [setup wizard](https://generaltranslation.com/docs/cli/init) installs dependencies, wraps your Next.js config with [`withGTConfig`](https://generaltranslation.com/docs/next/api/config/with-gt-config), adds [`GTProvider`](https://generaltranslation.com/docs/react/reference/components/gt-provider) to your root layout, creates a [`gt.config.json`](https://generaltranslation.com/docs/cli/reference/config) with your locales, sets up dev API keys for translation hot reloading, and configures CDN translation storage — all interactively. +The [setup wizard](https://generaltranslation.com/docs/cli/reference/commands/init) installs dependencies, wraps your Next.js config with [`withGTConfig`](https://generaltranslation.com/docs/react/nextjs/config), adds [`GTProvider`](https://generaltranslation.com/docs/react/reference/components/gt-provider) to your root layout, creates a [`gt.config.json`](https://generaltranslation.com/docs/cli/reference/config) with your locales, sets up dev API keys for translation hot reloading, and configures CDN translation storage — all interactively. Once that's done, wrap content in ``, run your dev server, and use the [``](https://generaltranslation.com/docs/react/reference/components/locale-selector) component to switch between languages: @@ -83,7 +83,7 @@ The [`translate`](https://generaltranslation.com/docs/cli/reference/commands/tra ## Next steps -- [Variable components](https://generaltranslation.com/docs/react/guides/format-variables) — handle dynamic content inside `` with [``](https://generaltranslation.com/docs/react/reference/components/var), [``](https://generaltranslation.com/docs/react/reference/components/num), and [``](https://generaltranslation.com/docs/react/reference/components/currency) -- [Branching components](https://generaltranslation.com/docs/react/guides/plurals-and-branches) — conditionally render content based on locale with [``](https://generaltranslation.com/docs/react/reference/components/plural) and [``](https://generaltranslation.com/docs/react/reference/components/branch) -- [`useGT`](https://generaltranslation.com/docs/react/reference/hooks/use-gt) and [`getGT`](https://generaltranslation.com/docs/react/reference/functions/get-gt) — translate plain strings for attributes, placeholders, and metadata -- [Standalone mode](https://generaltranslation.com/docs/react/guides/local-translations) — use gt-next without the General Translation platform +- [Variable components](https://generaltranslation.com/docs/react/guides/formatting-variables) — handle dynamic content inside `` with [``](https://generaltranslation.com/docs/react/reference/components/var), [``](https://generaltranslation.com/docs/react/reference/components/num), and [``](https://generaltranslation.com/docs/react/reference/components/currency) +- [Branching components](https://generaltranslation.com/docs/react/guides/handling-plurals-and-branches) — conditionally render content based on locale with [``](https://generaltranslation.com/docs/react/reference/components/plural) and [``](https://generaltranslation.com/docs/react/reference/components/branch) +- [`useGT`](https://generaltranslation.com/docs/react/reference/hooks/use-gt) and [`getGT`](https://generaltranslation.com/docs/react/nextjs/reference/functions/get-gt) — translate plain strings for attributes, placeholders, and metadata +- [Bring your own translations](https://generaltranslation.com/docs/react/guides/translating-with-dictionaries) — use `gt-next` with an existing dictionary diff --git a/blog/en-US/plurals.mdx b/blog/en-US/plurals.mdx index 9b2755213..ce3fbcfdf 100644 --- a/blog/en-US/plurals.mdx +++ b/blog/en-US/plurals.mdx @@ -239,8 +239,8 @@ function Example({ count }) { Ready to handle plurals properly in your React app? Check out our quickstart guides: -- [gt-react quickstart](https://generaltranslation.com/docs/react) for React apps -- [gt-next quickstart](https://generaltranslation.com/docs/react/nextjs) for Next.js apps +- [gt-react quickstart](https://generaltranslation.com/docs/react/react-quickstart) for React apps +- [gt-next quickstart](https://generaltranslation.com/docs/react/nextjs-quickstart) for Next.js apps - [`` API reference](/docs/react/reference/components/plural) for the full component API Pluralization is one of the most common i18n challenges in React — getting it right from the start saves significant refactoring later. diff --git a/docs/en-US/integrations/mintlify/quickstart.mdx b/docs/en-US/integrations/mintlify/quickstart.mdx index 6261522fc..793cd2663 100644 --- a/docs/en-US/integrations/mintlify/quickstart.mdx +++ b/docs/en-US/integrations/mintlify/quickstart.mdx @@ -1,6 +1,6 @@ --- -title: Quickstart +title: Quickstart description: Quickstart to translate a Mintlify documentation site with General Translation. related: links: diff --git a/docs/en-US/integrations/mintlify/reference/locales.mdx b/docs/en-US/integrations/mintlify/reference/locales.mdx index 45dabcd09..c9aaf1bb3 100644 --- a/docs/en-US/integrations/mintlify/reference/locales.mdx +++ b/docs/en-US/integrations/mintlify/reference/locales.mdx @@ -1,6 +1,6 @@ --- -title: Locales +title: Locales description: Reference for the language codes Mintlify supports and how General Translation locales map onto them. Reference for Mintlify locale handling. --- diff --git a/docs/en-US/overview/for-coding-agents.mdx b/docs/en-US/overview/for-coding-agents.mdx index 1eaa9d5c3..4dff5e383 100644 --- a/docs/en-US/overview/for-coding-agents.mdx +++ b/docs/en-US/overview/for-coding-agents.mdx @@ -155,17 +155,15 @@ Don't: ## Links - [`llms.txt`](/llms.txt) — short, machine-readable docs index. -- [`sitemap.md`](/sitemap.md) — map of every docs page. - Quickstarts: [React](/docs/react/react-quickstart), [Node](/docs/node/quickstart), [Core library](/docs/platform/core/quickstart), and the [CLI](/docs/cli/quickstart). - [Key concepts](/docs/overview/key-concepts) — locales, context, and static vs. dynamic content. ```` ## Point agents at the docs [#point-agents] -Give your agent direct access to the docs so its answers stay accurate. General Translation publishes several machine-readable entry points at the site root: +Give your agent direct access to the docs so its answers stay accurate. General Translation publishes a machine-readable index at the site root: - [`llms.txt`](/llms.txt) — a short, [llmstxt.org](https://llmstxt.org/)-style index of the docs. -- [`sitemap.md`](/sitemap.md) — a linked map of every page in navigation order. Every docs page is also available as **raw Markdown**: append `.md` to any page URL (for example, `/docs/cli/quickstart.md`) to fetch the clean source instead of parsing rendered HTML. diff --git a/docs/en-US/platform/index.mdx b/docs/en-US/platform/index.mdx index 4e73b1f74..d926ea779 100644 --- a/docs/en-US/platform/index.mdx +++ b/docs/en-US/platform/index.mdx @@ -1,6 +1,6 @@ --- -title: Platform +title: Platform description: Browse docs for the General Translation Platform, including the Dashboard, Locadex, Core library, and OpenAPI. --- diff --git a/docs/en-US/react/nextjs-quickstart.mdx b/docs/en-US/react/nextjs-quickstart.mdx index 623530656..d27b4c7ee 100644 --- a/docs/en-US/react/nextjs-quickstart.mdx +++ b/docs/en-US/react/nextjs-quickstart.mdx @@ -331,10 +331,10 @@ That's it — your app is now multilingual. 🎉 This is expected. In development, translations happen on-demand (your content is translated in real time via the API). This delay **does not exist in production** — all translations are pre-generated by `npx gt translate`. - Ambiguous text can lead to inaccurate translations. For example, "apple" could mean the fruit or the company. Add a `context` prop to help: + Ambiguous text can lead to inaccurate translations. For example, "apple" could mean the fruit or the company. Add a `$context` prop to help: ```jsx - Apple + Apple ``` Both ``, `useGT()`, and `getGT()` support the `context` option. From 6dd0d5537f16716ae16f49ecd5b68c768d2053b1 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Fri, 17 Jul 2026 23:42:19 +0000 Subject: [PATCH 2/6] docs: align compiler guidance with shipped packages --- docs/en-US/cli/guides/using-auto-jsx.mdx | 20 +++++++++++-- docs/en-US/node/reference/config.mdx | 23 +++++++++++++-- .../react/(frameworks)/nextjs/config.mdx | 4 +++ docs/en-US/react/reference/config.mdx | 28 +++++++++++++++++++ 4 files changed, 71 insertions(+), 4 deletions(-) diff --git a/docs/en-US/cli/guides/using-auto-jsx.mdx b/docs/en-US/cli/guides/using-auto-jsx.mdx index 91f1d1b69..d6d98827f 100644 --- a/docs/en-US/cli/guides/using-auto-jsx.mdx +++ b/docs/en-US/cli/guides/using-auto-jsx.mdx @@ -15,7 +15,7 @@ Automatic JSX injection makes the compiler wrap translatable JSX text in [``] Automatic JSX injection is disabled by default. -*Note: Automatic JSX injection currently works only with the i18n-context system and single-page React apps.* +*Note: Automatic JSX injection works with React single-page apps and Next.js webpack builds. The `gt-next` SWC compiler and Turbopack do not support it.* ## Enable automatic JSX injection [#enable] @@ -33,12 +33,28 @@ Set `enableAutoJsxInjection` under `files.gt.parsingFlags` in `gt.config.json`. } ``` +React SPA build plugins read this flag directly. In Next.js, also enable the Babel-based compiler in `next.config`: + +```ts title="next.config.ts" +import { withGTConfig } from 'gt-next/config'; + +const nextConfig = {}; + +export default withGTConfig(nextConfig, { + experimentalCompilerOptions: { + type: 'babel', + }, +}); +``` + +Build the Next.js app with webpack, for example with `next build --webpack`. When you build with Turbopack, `gt-next` warns and skips automatic JSX injection. + ## How it works [#how] Without injection, you wrap translatable text yourself. ```jsx -import { T } from 'gt-next'; +import { T } from 'gt-react'; function Welcome() { return ( diff --git a/docs/en-US/node/reference/config.mdx b/docs/en-US/node/reference/config.mdx index 61d8c0b7e..c64190d6f 100644 --- a/docs/en-US/node/reference/config.mdx +++ b/docs/en-US/node/reference/config.mdx @@ -30,7 +30,26 @@ import gtConfig from './gt.config.json' with { type: 'json' }; initializeGT(gtConfig); ``` -The configuration type is `InitializeGTParams`, the combination of the locale-resolution options and the translation-cache options. +Import `InitializeGTParams` from `gt-node/types` to type the runtime object. The same entry point re-exports `GTConfig`, the complete shared `gt.config.json` shape, so a typed config can be spread into `initializeGT` without removing CLI-only fields: + +```ts +import { initializeGT } from 'gt-node'; +import type { GTConfig } from 'gt-node/types'; + +const gtConfig = { + defaultLocale: 'en', + locales: ['es', 'fr'], + files: { + gt: { + output: 'src/_gt/[locale].json', + }, + }, +} satisfies GTConfig; + +initializeGT(gtConfig); +``` + +The runtime ignores the `files` field; the CLI and compiler consume it. ## Options [#options] @@ -52,7 +71,7 @@ The configuration type is `InitializeGTParams`, the combination of the locale-re | [`batchConfig`](#batch-config) | Runtime translation batching limits. | `object` | Yes | — | | [`modelProvider`](#model-provider) | Model provider key mirrored from `gt.config.json`. Not consumed by the runtime. | `string` | Yes | — | -*Note: `initializeGT` also accepts internal, underscore-prefixed keys (`_versionId`, `_branchId`, `_disableDevHotReload`) and a `files` object used by the CLI compiler. These are not part of the stable public surface and are omitted here.* +*Note: `initializeGT` also accepts internal, underscore-prefixed keys (`_versionId`, `_branchId`, `_disableDevHotReload`). These are not part of the stable public surface and are omitted here.* ## `defaultLocale` [#default-locale] diff --git a/docs/en-US/react/(frameworks)/nextjs/config.mdx b/docs/en-US/react/(frameworks)/nextjs/config.mdx index 089654407..c24fdad93 100644 --- a/docs/en-US/react/(frameworks)/nextjs/config.mdx +++ b/docs/en-US/react/(frameworks)/nextjs/config.mdx @@ -237,6 +237,10 @@ export default withGTConfig(nextConfig, { }); ``` + + Automatic JSX injection runs only in webpack builds with the Babel-based compiler. The SWC compiler does not support injection, and Turbopack disables the Babel compiler; in either case, `gt-next` warns and continues the build without injecting wrappers. + + ### `headersAndCookies` [#headers-and-cookies] **Type** `object` · **Optional** diff --git a/docs/en-US/react/reference/config.mdx b/docs/en-US/react/reference/config.mdx index f60449ba9..a3bf4899f 100644 --- a/docs/en-US/react/reference/config.mdx +++ b/docs/en-US/react/reference/config.mdx @@ -65,6 +65,7 @@ Both functions accept the fields below. They share the same options, except that | `region` | Initial region code for region-aware formatting. | `string` | Yes | — | | `enableI18n` | Translate content. When `false`, renders the source locale. | `boolean` | Yes | `true` | | `htmlTagOptions` | Whether to sync the `` `lang` and `dir` attributes on locale change. | `object` | Yes | — | +| `files` | Complete CLI file configuration accepted when spreading `gt.config.json`; ignored by the runtime. | `object` | Yes | — | ### `initializeGT` [#initialize] @@ -195,6 +196,33 @@ See the [CLI configuration reference](/docs/cli/reference/config) for the comple Internal identifier the CLI uses to track the translation version, which allows rolling back to previous translations. It is autogenerated — do not edit it. Keys prefixed with an underscore are internal. +## TypeScript config types [#config-types] + +Import the shared `gt.config.json` types from `generaltranslation/types` when defining a config in TypeScript or typing a config loader. + +| Type | Description | +| --- | --- | +| `GTConfig` | Complete shared `gt.config.json` shape accepted by the CLI, compiler, and runtime initializers. | +| `GTFilesConfig` | The `files` map, including `files.gt` and additional file-format entries. | +| `GTOutputFileConfig` | The `files.gt` output, publishing, and parsing settings. | +| `GTParsingFlags` | The compiler flags under `files.gt.parsingFlags`. | + +```ts title="gt.config.ts" +import type { GTConfig } from 'generaltranslation/types'; + +export const gtConfig = { + defaultLocale: 'en', + locales: ['es', 'fr'], + files: { + gt: { + parsingFlags: { + enableAutoJsxInjection: true, + }, + }, + }, +} satisfies GTConfig; +``` + ## Examples [#examples] ```json title="gt.config.json" From a8415695642baf76dd2df222bf8d1330510e80cf Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Fri, 17 Jul 2026 23:45:01 +0000 Subject: [PATCH 3/6] docs: document Google Drive integration --- .../guides/configuring-google-drive.mdx | 52 ++++++++++++++++ .../guides/managing-translations.mdx | 46 ++++++++++++++ .../google-drive/guides/meta.json | 9 +++ .../guides/translating-content.mdx | 49 +++++++++++++++ .../en-US/integrations/google-drive/meta.json | 5 ++ .../integrations/google-drive/quickstart.mdx | 60 +++++++++++++++++++ .../google-drive/reference/connection.mdx | 45 ++++++++++++++ .../google-drive/reference/meta.json | 5 ++ .../reference/supported-content.mdx | 38 ++++++++++++ docs/en-US/integrations/index.mdx | 1 + docs/en-US/integrations/meta.json | 8 ++- docs/en-US/platform/dashboard/get-started.mdx | 1 + 12 files changed, 318 insertions(+), 1 deletion(-) create mode 100644 docs/en-US/integrations/google-drive/guides/configuring-google-drive.mdx create mode 100644 docs/en-US/integrations/google-drive/guides/managing-translations.mdx create mode 100644 docs/en-US/integrations/google-drive/guides/meta.json create mode 100644 docs/en-US/integrations/google-drive/guides/translating-content.mdx create mode 100644 docs/en-US/integrations/google-drive/meta.json create mode 100644 docs/en-US/integrations/google-drive/quickstart.mdx create mode 100644 docs/en-US/integrations/google-drive/reference/connection.mdx create mode 100644 docs/en-US/integrations/google-drive/reference/meta.json create mode 100644 docs/en-US/integrations/google-drive/reference/supported-content.mdx diff --git a/docs/en-US/integrations/google-drive/guides/configuring-google-drive.mdx b/docs/en-US/integrations/google-drive/guides/configuring-google-drive.mdx new file mode 100644 index 000000000..de18ec90a --- /dev/null +++ b/docs/en-US/integrations/google-drive/guides/configuring-google-drive.mdx @@ -0,0 +1,52 @@ +--- + +title: Configuring Google Drive +description: "How to connect Google Drive to General Translation: this guide covers personal accounts, Organization shared drives, and file access." +related: + links: + - /docs/integrations/google-drive/guides/translating-content + - /docs/integrations/google-drive/guides/managing-translations + +--- + +Connect a Google account or an Organization shared-drive connection before adding files to a Project. The access mode controls which files users can browse and which identity creates translated copies. + +## Before you start [#before-start] + +Connecting Google Drive requires: + +- `project:write` permission on the Project. +- A plan that includes Project integrations. +- Permission in Drive to copy each source file and edit its translated copies. + +## Choose an access mode [#access-mode] + +When an Organization shared-drive connection is available, the Dashboard asks how the Project should access Drive. + +- **Organization shared drive:** everyone on the Project uses one translation account. An Organization admin sets up the connection under **Organization > Settings > Integrations**, adds the translation account to each shared drive as a **Content manager**, and verifies access. +- **Personal Google account:** each user connects their own Google account. Users browse only files their account can access, and General Translation requests file-specific access for the files they select. + +If no Organization connection is available, the Project uses personal accounts. + +## Connect the Project [#connect-project] + +1. Open **Project > Integrations** in the Dashboard. +2. Open the catalog and find **Google Drive**. +3. Click **Connect**. +4. Choose an access mode when prompted. + +The catalog shows **Installed** after the integration is connected. Click **Manage** to add files, translate them, or reconnect an account. + +## Connect or reconnect a personal account [#personal-account] + +On the management page, click **Connect account** and complete the Google authorization flow. When you click **Add files**, choose Google Docs or Google Slides in the Google Picker. + +If the picker cannot show your files, reload and allow Google's cookie prompt. In Safari, you may need to turn off **Prevent cross-site tracking** temporarily, then reload and try again. + +Disconnecting removes your stored Google credentials. It does not delete the Project's linked files, but they remain hidden and cannot be translated until you reconnect. Other Project members keep access through their own accounts. + +## Manage linked files [#linked-files] + +Click **Add files** whenever you need to link more content. Removing a file from the integration only removes the Project link; it does not delete the source file or translated copies from Google Drive. + +For an Organization connection, add the translation account to another shared drive and verify access from **Organization > Settings > Integrations** before browsing files from that drive. diff --git a/docs/en-US/integrations/google-drive/guides/managing-translations.mdx b/docs/en-US/integrations/google-drive/guides/managing-translations.mdx new file mode 100644 index 000000000..7df146224 --- /dev/null +++ b/docs/en-US/integrations/google-drive/guides/managing-translations.mdx @@ -0,0 +1,46 @@ +--- + +title: Managing translations +description: "How to keep Google Drive translations current with General Translation: this guide covers applying source changes, reusing translations, and forcing retranslation." +related: + links: + - /docs/integrations/google-drive/guides/configuring-google-drive + - /docs/integrations/google-drive/guides/translating-content + +--- + +After the first run, use the Google Drive integration to apply source changes to the existing translated copies. General Translation reuses translations when it can and updates each target copy in place. + +## Apply source changes [#apply-changes] + +When a linked Google Doc or Google Slides presentation changes: + +1. Open **Project > Integrations > Google Drive**. +2. Select the changed files. +3. Choose the target locales under **Translate into**. +4. Click **Apply changes**. + +General Translation reads the latest source and the existing target copy. It reuses matching translations, translates new or changed text, and applies the result to that copy. + +## Reuse existing translations [#reuse] + +Every normal run imports translations from the existing target copy and reuses matching content. This preserves reviewed edits and avoids translating unchanged text again. + +If a source file has changed across several saved versions, General Translation can also reuse matching translations from older ancestor versions. No additional setup is required. + +## Force a full retranslation [#force] + +Use **Force retranslation** when you intentionally want to ignore reused and cached translations. + +1. Select at least one file that already has a translated copy. +2. Check **Force retranslation**. +3. Click **Retranslate**. +4. Confirm the warning. + +Force retranslation starts from the source again, overwrites existing translations in the target copy, and incurs additional usage. The warning opens when you click **Retranslate**, not when you select the checkbox. You can suppress it for the rest of the current browser session. + +## Remove or reconnect files [#remove-reconnect] + +Removing a linked file does not delete the source file or its translated copies from Drive. + +If a personal Google account is disconnected, its linked files are hidden until that user reconnects. With an Organization connection, an Organization admin must restore or verify the shared-drive connection before the Project can browse or translate its files. diff --git a/docs/en-US/integrations/google-drive/guides/meta.json b/docs/en-US/integrations/google-drive/guides/meta.json new file mode 100644 index 000000000..9e6e220be --- /dev/null +++ b/docs/en-US/integrations/google-drive/guides/meta.json @@ -0,0 +1,9 @@ +{ + "title": "guides", + "description": "Connect Drive, translate files, and keep translated copies current.", + "pages": [ + "./configuring-google-drive", + "./translating-content", + "./managing-translations" + ] +} diff --git a/docs/en-US/integrations/google-drive/guides/translating-content.mdx b/docs/en-US/integrations/google-drive/guides/translating-content.mdx new file mode 100644 index 000000000..64f712a89 --- /dev/null +++ b/docs/en-US/integrations/google-drive/guides/translating-content.mdx @@ -0,0 +1,49 @@ +--- + +title: Translating content +description: How to translate Google Docs and Google Slides from the General Translation Dashboard and review the translated Drive copies. +related: + links: + - /docs/integrations/google-drive/guides/configuring-google-drive + - /docs/integrations/google-drive/guides/managing-translations + +--- + +Use the Google Drive integration's management page to translate linked files into one or more target locales. General Translation copies each source file, translates supported text, and writes the result into the copy. + +## Add files [#add-files] + +Open **Project > Integrations > Google Drive**, then click **Add files**. + +- With a personal account, select Google Docs or Google Slides through the Google Picker. You can select multiple files from My Drive or shared drives. +- With an Organization connection, choose a shared drive, browse or search its folders, and select the files to add. + +The file's source locale is the Project's default locale when you add it. + +## Select files and locales [#select-locales] + +1. Select one or more linked files. Use the checkbox in the table header to select all. +2. Under **Translate into**, choose the target locales. The source locale is excluded automatically. +3. Add a locale from the selector if it is not already configured on the Project. + +If no target locale is selected, the action reads **Select locales** and opens the locale selector. + +## Start translation [#start] + +Click **Translate** for a file that has not been translated before. General Translation: + +1. Reads the current Google Doc or Google Slides content. +2. Extracts supported text and starts one translation job per target locale. +3. Creates a translated copy in the source file's folder. +4. Writes translated text into the copy. +5. Runs a layout pass for Google Slides. + +The jobs continue in the background. Active files stay pinned to the top of the table, and the Dashboard refreshes their progress while the run is active. + +## Review the copies [#review] + +Each target copy uses the source name followed by the locale in brackets, such as `Quarterly plan [fr]`. Open the copy in Google Drive and review the translated text and layout. + +Later runs update the same copy when it is still available and editable. If the target copy was deleted or moved to trash, General Translation creates a new copy. + +See [Supported content](/docs/integrations/google-drive/reference/supported-content) for the text and file types the integration handles. diff --git a/docs/en-US/integrations/google-drive/meta.json b/docs/en-US/integrations/google-drive/meta.json new file mode 100644 index 000000000..3e6ee8b77 --- /dev/null +++ b/docs/en-US/integrations/google-drive/meta.json @@ -0,0 +1,5 @@ +{ + "title": "Google Drive", + "description": "Translate Google Docs and Google Slides from the Dashboard.", + "pages": ["./quickstart", "./guides", "./reference"] +} diff --git a/docs/en-US/integrations/google-drive/quickstart.mdx b/docs/en-US/integrations/google-drive/quickstart.mdx new file mode 100644 index 000000000..928f5e445 --- /dev/null +++ b/docs/en-US/integrations/google-drive/quickstart.mdx @@ -0,0 +1,60 @@ +--- + +title: Quickstart +description: Quickstart to connect Google Drive to General Translation and translate a Google Doc or Google Slides presentation from the Dashboard. +related: + links: + - /docs/integrations/google-drive/guides/configuring-google-drive + - /docs/integrations/google-drive/guides/translating-content + - /docs/integrations/google-drive/guides/managing-translations + +--- + +Use the Google Drive integration to translate Google Docs and Google Slides from the General Translation Dashboard. General Translation creates one translated copy per target locale in Drive and updates that copy on later runs. + +## Before you start [#before-start] + +You need: + +- A General Translation [Project](/docs/platform/dashboard/get-started) on a plan that includes Project integrations. +- `project:write` permission on that Project. +- Permission to copy the source file and edit its translated copies in Google Drive. + +Your Organization may also provide a shared-drive connection. See [Connection modes](/docs/integrations/google-drive/reference/connection) for the difference between personal and Organization access. + +## Quickstart [#quickstart] + +### 1. Connect Google Drive + +In the Dashboard, go to **Project > Integrations**, open the catalog, and find **Google Drive**. Click **Connect**. + +If your Organization has a shared-drive connection, choose how the Project accesses Drive: + +- **Use the Organization shared-drive connection** so everyone on the Project can browse the connected shared drives. +- **Connect personal Google accounts** so each user can select files their own account can access. + +### 2. Connect your Google account + +Skip this step if the Project uses an Organization shared-drive connection. + +On the Google Drive management page, click **Connect account** and authorize access. General Translation uses Drive's file-specific permission, so it can access files you select rather than your entire Drive. + +### 3. Add files + +Click **Add files** and select one or more Google Docs or Google Slides presentations. + +With a personal account, the Google Picker shows files from My Drive and shared drives that your account can access. With an Organization connection, browse the shared drives available to the translation account. + +### 4. Choose locales and translate + +1. Select the files to translate. +2. Under **Translate into**, choose one or more target locales. +3. Click **Translate**. + +Translation and, for Slides, layout processing continue in the background. Files with active jobs stay at the top of the table. + +### 5. Review the translated copies + +General Translation creates a copy named with the target locale, such as `Product overview [es]`, in the source file's folder. Open each translated copy from Drive and review it before sharing or publishing it. + +When the source changes, select the file and click **Apply changes**. See [Managing translations](/docs/integrations/google-drive/guides/managing-translations) for reuse and full retranslation behavior. diff --git a/docs/en-US/integrations/google-drive/reference/connection.mdx b/docs/en-US/integrations/google-drive/reference/connection.mdx new file mode 100644 index 000000000..7d8b6799e --- /dev/null +++ b/docs/en-US/integrations/google-drive/reference/connection.mdx @@ -0,0 +1,45 @@ +--- + +title: Connection +description: Connect Google Drive to a General Translation Project with a personal account or an Organization shared-drive connection. Reference for Google Drive connection modes. + +--- + +The Google Drive integration supports personal accounts and Organization shared-drive connections. Both modes are managed from **Project > Integrations**, but they use different identities and file scopes. + +## Overview [#overview] + +| Mode | Identity | Available files | Setup | +| --- | --- | --- | --- | +| [Personal account](#personal-account) | Each Dashboard user | Files that user's Google account can access and select | Connect from the Project integration page. | +| [Organization shared drive](#organization-shared-drive) | Organization translation account | Files in shared drives where the translation account is a member | Set up and verify under Organization settings first. | + +Both modes require a plan with Project integrations and `project:write` permission to connect or run the integration. + +## Personal account [#personal-account] + +Each user authorizes their own Google account. General Translation requests the Google Drive file scope and receives access to files selected through the Google Picker rather than the user's entire Drive. + +The Project keeps its linked-file records when a user disconnects. Those files are hidden from that user until they reconnect, while other Project members can continue using their own authorized accounts. + +## Organization shared drive [#organization-shared-drive] + +An Organization admin creates a shared-drive connection under **Organization > Settings > Integrations**. The Dashboard provides a translation account email to add as a **Content manager** on each shared drive, then verifies that the account can access it. + +Projects using this mode do not require each user to connect a personal Google account. The integration can browse only shared drives available to the translation account. + +Organization shared drives require the Google shared-drive feature on the Organization's plan. If the connection is unavailable or no longer verified, Project users cannot browse or translate files until an Organization admin restores it. + +## Required Drive capabilities [#drive-capabilities] + +The active identity must be able to: + +- Read and copy each source Google Doc or Google Slides presentation. +- Create a translated copy in the source file's folder. +- Edit an existing translated copy on later runs. + +If General Translation cannot copy the source or edit the target copy, that file and locale fail without changing the Drive file. + +## Switching modes [#switching] + +A Project cannot switch from an Organization shared-drive connection to personal accounts while shared-drive files remain linked. Remove the linked files first, then reconnect the integration with personal access. diff --git a/docs/en-US/integrations/google-drive/reference/meta.json b/docs/en-US/integrations/google-drive/reference/meta.json new file mode 100644 index 000000000..a31f3047f --- /dev/null +++ b/docs/en-US/integrations/google-drive/reference/meta.json @@ -0,0 +1,5 @@ +{ + "title": "reference", + "description": "Reference for Google Drive access modes and supported content.", + "pages": ["./connection", "./supported-content"] +} diff --git a/docs/en-US/integrations/google-drive/reference/supported-content.mdx b/docs/en-US/integrations/google-drive/reference/supported-content.mdx new file mode 100644 index 000000000..fa28b9c8d --- /dev/null +++ b/docs/en-US/integrations/google-drive/reference/supported-content.mdx @@ -0,0 +1,38 @@ +--- + +title: Supported content +description: Review the Google Drive file types and text structures General Translation can translate. Reference for supported Google Drive content. + +--- + +The Google Drive integration translates native Google Docs and Google Slides files. Other Drive file types cannot be added to the integration. + +## Supported file types [#file-types] + +| File type | Translated content | Output | +| --- | --- | --- | +| Google Docs | Paragraphs and table cells | One Google Doc copy per target locale. | +| Google Slides | Text in shapes, table cells, and speaker notes | One Google Slides copy per target locale, followed by a layout pass. | + +## Formatting and structure [#formatting] + +General Translation writes translations into a copy of the source file so the original remains unchanged. It preserves supported paragraph and text styling, links, lists, tables, slide structure, and speaker-note structure. + +For Google Slides, a layout pass adjusts translated text after it is applied. The Dashboard shows per-locale progress while translation and layout processing run. + +## Target copies [#target-copies] + +The first run creates a copy in the source file's folder named with the target locale, such as `Launch deck [ja]`. General Translation records the relationship between the source and target copy. + +Later runs update that copy instead of creating another one. If the recorded copy is missing or in the trash, the integration creates a replacement. + +## Skipped content [#skipped-content] + +The integration skips content that has no translatable text or cannot be represented safely, including: + +- Empty text. +- Unsupported structural elements or document regions. +- Rich content without a supported text representation. +- Text ranges that cannot be resolved in the source structure. + +Images, videos, charts, and other non-text Drive content are not translated. diff --git a/docs/en-US/integrations/index.mdx b/docs/en-US/integrations/index.mdx index f6e811643..dc66f46eb 100644 --- a/docs/en-US/integrations/index.mdx +++ b/docs/en-US/integrations/index.mdx @@ -7,6 +7,7 @@ description: Use General Translation with third-party content platforms and plug Connect General Translation to third-party content platforms so you can translate content where it already lives. Each integration is a plugin with its own Quickstart, Guides, and Reference. +- [Google Drive](/docs/integrations/google-drive/quickstart): Translate Google Docs and Google Slides from the General Translation Dashboard with personal or Organization shared-drive access. - [Mintlify](/docs/integrations/mintlify/quickstart): Translate a Mintlify documentation site through GitHub with Locadex, the General Translation AI agent — no plugin to install. - [Sanity](/docs/integrations/sanity/quickstart): Translate Sanity documents from inside Sanity Studio with the `gt-sanity` plugin. - [Storyblok](/docs/integrations/storyblok/quickstart): Translate Storyblok stories from the General Translation Dashboard by connecting a space with credentials. diff --git a/docs/en-US/integrations/meta.json b/docs/en-US/integrations/meta.json index b3b093b60..a3db979c4 100644 --- a/docs/en-US/integrations/meta.json +++ b/docs/en-US/integrations/meta.json @@ -3,5 +3,11 @@ "icon": "Plug", "root": true, "description": "CMS, Docs Frameworks", - "pages": ["./index", "./mintlify", "./sanity", "./storyblok"] + "pages": [ + "./index", + "./google-drive", + "./mintlify", + "./sanity", + "./storyblok" + ] } diff --git a/docs/en-US/platform/dashboard/get-started.mdx b/docs/en-US/platform/dashboard/get-started.mdx index 1d8ca5a3d..f70ff9c26 100644 --- a/docs/en-US/platform/dashboard/get-started.mdx +++ b/docs/en-US/platform/dashboard/get-started.mdx @@ -19,6 +19,7 @@ The Dashboard is the web app for reviewing translations, guiding the AI with con - **Define context and key terms for translation:** use Context Groups to guide terminology and style across Projects. See [Define translation context](/docs/platform/dashboard/guides/adding-translation-context). - **Review and edit translations:** compare locales, make manual edits, and inspect version history. See [Reviewing and editing translations](/docs/platform/dashboard/guides/reviewing-translations). - **Add annotations:** label entries, add notes, and discuss translation decisions with your team. See [Adding annotations](/docs/platform/dashboard/guides/adding-annotations). +- **Translate Google Drive content:** connect Google Drive and translate Google Docs or Google Slides from the Dashboard. See the [Google Drive Quickstart](/docs/integrations/google-drive/quickstart). - **Automate the whole process:** see [Locadex](/docs/platform/locadex/quickstart) to automate localization setup and maintenance. From ff6c7a8b7e97b003bd24a5272f41c78b44549912 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Fri, 17 Jul 2026 23:53:09 +0000 Subject: [PATCH 4/6] fix: tighten Google Drive documentation accuracy --- .../guides/configuring-google-drive.mdx | 3 ++- .../guides/managing-translations.mdx | 4 ++-- .../guides/translating-content.mdx | 2 +- .../integrations/google-drive/quickstart.mdx | 6 +++--- .../google-drive/reference/connection.mdx | 16 +++++++++------- .../reference/supported-content.mdx | 19 +++++++++++++++---- docs/en-US/integrations/index.mdx | 18 ++++++++++++++---- 7 files changed, 46 insertions(+), 22 deletions(-) diff --git a/docs/en-US/integrations/google-drive/guides/configuring-google-drive.mdx b/docs/en-US/integrations/google-drive/guides/configuring-google-drive.mdx index de18ec90a..6000e553f 100644 --- a/docs/en-US/integrations/google-drive/guides/configuring-google-drive.mdx +++ b/docs/en-US/integrations/google-drive/guides/configuring-google-drive.mdx @@ -15,7 +15,8 @@ Connect a Google account or an Organization shared-drive connection before addin Connecting Google Drive requires: -- `project:write` permission on the Project. +- `project:write` permission to connect the integration. +- `translations:content:write` permission to add, remove, or translate files. - A plan that includes Project integrations. - Permission in Drive to copy each source file and edit its translated copies. diff --git a/docs/en-US/integrations/google-drive/guides/managing-translations.mdx b/docs/en-US/integrations/google-drive/guides/managing-translations.mdx index 7df146224..ececac4d1 100644 --- a/docs/en-US/integrations/google-drive/guides/managing-translations.mdx +++ b/docs/en-US/integrations/google-drive/guides/managing-translations.mdx @@ -20,7 +20,7 @@ When a linked Google Doc or Google Slides presentation changes: 3. Choose the target locales under **Translate into**. 4. Click **Apply changes**. -General Translation reads the latest source and the existing target copy. It reuses matching translations, translates new or changed text, and applies the result to that copy. +General Translation reads the latest source and the existing target copy. It reuses matching translations, translates new or changed text, and updates text that still has a matching location in that copy. ## Reuse existing translations [#reuse] @@ -37,7 +37,7 @@ Use **Force retranslation** when you intentionally want to ignore reused and cac 3. Click **Retranslate**. 4. Confirm the warning. -Force retranslation starts from the source again, overwrites existing translations in the target copy, and incurs additional usage. The warning opens when you click **Retranslate**, not when you select the checkbox. You can suppress it for the rest of the current browser session. +Force retranslation starts from the source again, overwrites existing translations in the target copy, and incurs additional usage. The warning opens when you click **Retranslate**, not when you select the checkbox. You can suppress it until the next full-page reload. ## Remove or reconnect files [#remove-reconnect] diff --git a/docs/en-US/integrations/google-drive/guides/translating-content.mdx b/docs/en-US/integrations/google-drive/guides/translating-content.mdx index 64f712a89..af44fac98 100644 --- a/docs/en-US/integrations/google-drive/guides/translating-content.mdx +++ b/docs/en-US/integrations/google-drive/guides/translating-content.mdx @@ -44,6 +44,6 @@ The jobs continue in the background. Active files stay pinned to the top of the Each target copy uses the source name followed by the locale in brackets, such as `Quarterly plan [fr]`. Open the copy in Google Drive and review the translated text and layout. -Later runs update the same copy when it is still available and editable. If the target copy was deleted or moved to trash, General Translation creates a new copy. +Later runs update the same copy when it is still available and editable. If the target copy is missing, inaccessible, or in the trash, General Translation creates a new copy when the active Drive identity can still copy the source. See [Supported content](/docs/integrations/google-drive/reference/supported-content) for the text and file types the integration handles. diff --git a/docs/en-US/integrations/google-drive/quickstart.mdx b/docs/en-US/integrations/google-drive/quickstart.mdx index 928f5e445..2076ebe2d 100644 --- a/docs/en-US/integrations/google-drive/quickstart.mdx +++ b/docs/en-US/integrations/google-drive/quickstart.mdx @@ -17,7 +17,7 @@ Use the Google Drive integration to translate Google Docs and Google Slides from You need: - A General Translation [Project](/docs/platform/dashboard/get-started) on a plan that includes Project integrations. -- `project:write` permission on that Project. +- `project:write` permission to connect the integration and `translations:content:write` permission to add or translate files. - Permission to copy the source file and edit its translated copies in Google Drive. Your Organization may also provide a shared-drive connection. See [Connection modes](/docs/integrations/google-drive/reference/connection) for the difference between personal and Organization access. @@ -30,8 +30,8 @@ In the Dashboard, go to **Project > Integrations**, open the catalog, and find * If your Organization has a shared-drive connection, choose how the Project accesses Drive: -- **Use the Organization shared-drive connection** so everyone on the Project can browse the connected shared drives. -- **Connect personal Google accounts** so each user can select files their own account can access. +- **Use the org shared drive connection** so Project members with translation write permission can browse the connected shared drives. +- **Each user connects their own Google account** so each user can select files their own account can access. ### 2. Connect your Google account diff --git a/docs/en-US/integrations/google-drive/reference/connection.mdx b/docs/en-US/integrations/google-drive/reference/connection.mdx index 7d8b6799e..45605a775 100644 --- a/docs/en-US/integrations/google-drive/reference/connection.mdx +++ b/docs/en-US/integrations/google-drive/reference/connection.mdx @@ -9,22 +9,24 @@ The Google Drive integration supports personal accounts and Organization shared- ## Overview [#overview] -| Mode | Identity | Available files | Setup | -| --- | --- | --- | --- | -| [Personal account](#personal-account) | Each Dashboard user | Files that user's Google account can access and select | Connect from the Project integration page. | -| [Organization shared drive](#organization-shared-drive) | Organization translation account | Files in shared drives where the translation account is a member | Set up and verify under Organization settings first. | +| Area | Identity or behavior | Required access | +| --- | --- | --- | +| [Personal account](#personal-account) | Each Dashboard user selects files through their Google account. | Google `drive.file` OAuth scope. | +| [Organization shared drive](#organization-shared-drive) | One Organization translation account accesses configured shared drives. | Google `drive` OAuth scope and shared-drive membership. | +| [Drive capabilities](#drive-capabilities) | The active identity copies sources and edits translated copies. | Copy access on the source and edit access on the target. | +| [Switching modes](#switching) | Linked Organization files must be removed before switching to personal access. | `project:write`. | -Both modes require a plan with Project integrations and `project:write` permission to connect or run the integration. +Both modes require a plan with Project integrations. Connecting requires `project:write`; browsing, adding, removing, and translating files require `translations:content:write`. ## Personal account [#personal-account] -Each user authorizes their own Google account. General Translation requests the Google Drive file scope and receives access to files selected through the Google Picker rather than the user's entire Drive. +Each user authorizes their own Google account with the `https://www.googleapis.com/auth/drive.file` OAuth scope. General Translation receives access to files selected through the Google Picker rather than the user's entire Drive. The Project keeps its linked-file records when a user disconnects. Those files are hidden from that user until they reconnect, while other Project members can continue using their own authorized accounts. ## Organization shared drive [#organization-shared-drive] -An Organization admin creates a shared-drive connection under **Organization > Settings > Integrations**. The Dashboard provides a translation account email to add as a **Content manager** on each shared drive, then verifies that the account can access it. +An Organization admin creates a shared-drive connection under **Organization > Settings > Integrations**. The translation account uses the `https://www.googleapis.com/auth/drive` OAuth scope. The Dashboard provides its email to add as a **Content manager** on each shared drive, then verifies that the account can access it. Projects using this mode do not require each user to connect a personal Google account. The integration can browse only shared drives available to the translation account. diff --git a/docs/en-US/integrations/google-drive/reference/supported-content.mdx b/docs/en-US/integrations/google-drive/reference/supported-content.mdx index fa28b9c8d..c4eebac10 100644 --- a/docs/en-US/integrations/google-drive/reference/supported-content.mdx +++ b/docs/en-US/integrations/google-drive/reference/supported-content.mdx @@ -7,24 +7,35 @@ description: Review the Google Drive file types and text structures General Tran The Google Drive integration translates native Google Docs and Google Slides files. Other Drive file types cannot be added to the integration. -## Supported file types [#file-types] +## Overview [#overview] + +| Topic | Behavior | +| --- | --- | +| [File types](#file-types) | Native Google Docs and Google Slides files. | +| [Formatting and structure](#formatting) | Supported text and formatting in a copy of the source, with best-effort updates after source structure changes. | +| [Target copies](#target-copies) | One managed Drive copy per file and target locale. | +| [Skipped content](#skipped-content) | Empty, non-text, or unsupported structures remain unchanged. | + +## File types [#file-types] | File type | Translated content | Output | | --- | --- | --- | -| Google Docs | Paragraphs and table cells | One Google Doc copy per target locale. | +| Google Docs | Paragraphs and table cells in the body, tabs and child tabs, headers, footers, and footnotes | One Google Doc copy per target locale. | | Google Slides | Text in shapes, table cells, and speaker notes | One Google Slides copy per target locale, followed by a layout pass. | ## Formatting and structure [#formatting] -General Translation writes translations into a copy of the source file so the original remains unchanged. It preserves supported paragraph and text styling, links, lists, tables, slide structure, and speaker-note structure. +The first translated file is a copy of the source, so the original remains unchanged and its Drive structure is retained. General Translation applies supported paragraph styling, text styling, links, and lists to translated text. For Google Slides, a layout pass adjusts translated text after it is applied. The Dashboard shows per-locale progress while translation and layout processing run. +When the source structure changes after the copy was created, updates are best-effort. General Translation updates text whose structural location still exists in the target. It can recreate plain text shapes on a newly added slide, but it does not recreate new table cells or speaker notes in that slide. Other source-only structures with no matching location in the target are not applied. + ## Target copies [#target-copies] The first run creates a copy in the source file's folder named with the target locale, such as `Launch deck [ja]`. General Translation records the relationship between the source and target copy. -Later runs update that copy instead of creating another one. If the recorded copy is missing or in the trash, the integration creates a replacement. +Later runs update that copy instead of creating another one. If the recorded copy is missing, inaccessible, or in the trash, the integration creates a replacement when the active Drive identity can still copy the source. ## Skipped content [#skipped-content] diff --git a/docs/en-US/integrations/index.mdx b/docs/en-US/integrations/index.mdx index dc66f46eb..666750a9a 100644 --- a/docs/en-US/integrations/index.mdx +++ b/docs/en-US/integrations/index.mdx @@ -7,7 +7,17 @@ description: Use General Translation with third-party content platforms and plug Connect General Translation to third-party content platforms so you can translate content where it already lives. Each integration is a plugin with its own Quickstart, Guides, and Reference. -- [Google Drive](/docs/integrations/google-drive/quickstart): Translate Google Docs and Google Slides from the General Translation Dashboard with personal or Organization shared-drive access. -- [Mintlify](/docs/integrations/mintlify/quickstart): Translate a Mintlify documentation site through GitHub with Locadex, the General Translation AI agent — no plugin to install. -- [Sanity](/docs/integrations/sanity/quickstart): Translate Sanity documents from inside Sanity Studio with the `gt-sanity` plugin. -- [Storyblok](/docs/integrations/storyblok/quickstart): Translate Storyblok stories from the General Translation Dashboard by connecting a space with credentials. + + + Quickstart to connect Google Drive to General Translation and translate a Google Doc or Google Slides presentation from the Dashboard. + + + Quickstart to translate a Mintlify documentation site with General Translation. + + + Install `gt-sanity`, add the General Translation plugin to Sanity Studio, and translate your first document. + + + Quickstart to connect a Storyblok space to General Translation and translate your first story from the Dashboard. + + From f65a2a08052ace26e7c88f94247ff45b17c05a64 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Fri, 17 Jul 2026 23:57:11 +0000 Subject: [PATCH 5/6] fix: clarify Google Drive replacement behavior --- docs/en-US/integrations/google-drive/reference/connection.mdx | 2 +- .../integrations/google-drive/reference/supported-content.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/en-US/integrations/google-drive/reference/connection.mdx b/docs/en-US/integrations/google-drive/reference/connection.mdx index 45605a775..83960cf50 100644 --- a/docs/en-US/integrations/google-drive/reference/connection.mdx +++ b/docs/en-US/integrations/google-drive/reference/connection.mdx @@ -40,7 +40,7 @@ The active identity must be able to: - Create a translated copy in the source file's folder. - Edit an existing translated copy on later runs. -If General Translation cannot copy the source or edit the target copy, that file and locale fail without changing the Drive file. +If General Translation cannot copy the source, that file and locale fail. A readable target copy without edit permission also fails. If the recorded target is missing or inaccessible, the integration treats it as stale and creates a replacement when the active identity can copy the source. ## Switching modes [#switching] diff --git a/docs/en-US/integrations/google-drive/reference/supported-content.mdx b/docs/en-US/integrations/google-drive/reference/supported-content.mdx index c4eebac10..33d0407bb 100644 --- a/docs/en-US/integrations/google-drive/reference/supported-content.mdx +++ b/docs/en-US/integrations/google-drive/reference/supported-content.mdx @@ -29,7 +29,7 @@ The first translated file is a copy of the source, so the original remains uncha For Google Slides, a layout pass adjusts translated text after it is applied. The Dashboard shows per-locale progress while translation and layout processing run. -When the source structure changes after the copy was created, updates are best-effort. General Translation updates text whose structural location still exists in the target. It can recreate plain text shapes on a newly added slide, but it does not recreate new table cells or speaker notes in that slide. Other source-only structures with no matching location in the target are not applied. +When the source structure changes after the copy was created, updates are best-effort. General Translation updates text whose structural location still exists in the target. On a newly added slide, it can recreate images and plain text shapes, but it does not recreate new table cells or speaker notes. Other new text structures with no matching location in the target are not applied. ## Target copies [#target-copies] From d29afe777320c3441241822131e1ee8f9e59bc78 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Sat, 18 Jul 2026 00:19:25 +0000 Subject: [PATCH 6/6] fix: restore machine-readable sitemap links --- DOCS-SKILL.md | 9 +++++---- docs/en-US/overview/for-coding-agents.mdx | 4 +++- 2 files changed, 8 insertions(+), 5 deletions(-) diff --git a/DOCS-SKILL.md b/DOCS-SKILL.md index bb89f38e6..e09f6a965 100644 --- a/DOCS-SKILL.md +++ b/DOCS-SKILL.md @@ -250,11 +250,12 @@ The **overview** section doubles as a **landing hub**: its `meta.json` lists the ### Machine-readable outputs -The docs are written to be consumed by LLMs and agents, not only humans. Publish `llms.txt` at the site root, generated from the `meta.json` filetree and never hand-edited: +The docs are written to be consumed by LLMs and agents, not only humans. Alongside the filetree, publish two machine-readable maps at the repo root, both **generated from the** `meta.json` **filetree** (never hand-edited): - `llms.txt` — an [llmstxt.org](https://llmstxt.org/)-style index for LLMs and agents: an H1, a one-line blockquote summary, then per-section lists of `- [Title](url): description` links. +- `sitemap.md` — a linked, hierarchical map of every published page in navigation order. -Regenerate it whenever you add, rename, remove, or reorder pages, so it stays in sync with the `meta.json` filetree. **Only include pages that actually exist** — omit in-progress sections and manifest-only stubs, and keep every link resolvable. +Regenerate both whenever you add, rename, remove, or reorder pages, so they stay in sync with the `meta.json` filetree. **Only include pages that actually exist** — omit in-progress sections and manifest-only stubs, and keep every link resolvable. ### Agent-navigable by default @@ -275,7 +276,7 @@ Structure it in this order: 3. **Core usage** — the canonical patterns the agent should follow (for example, wrap user-facing strings in ``, use `useGT()` for dynamic strings, keep locale configuration in one place). Show minimal, commented code. 4. **Commands** — a short cheat-sheet of the CLI commands the agent will run (`npx gt configure`, `npx gt translate`, and so on) and when to run each. 5. **Rules — do and don't** — explicit guardrails: what to always do (wrap new copy, run `gt translate` before committing) and what never to do (hardcode translated strings, hand-edit generated translation files). -6. **Links** — point to `llms.txt` and the most useful pages for deeper detail. +6. **Links** — point to `llms.txt`, the sitemap, and the most useful pages for deeper detail. Document only capabilities that exist, and resolve anything uncertain against the codebase (see Source of truth and best judgement). This file is written by an agent connected to the product codebase; this guide defines its **shape**, not its exact contents. @@ -714,5 +715,5 @@ These patterns are **blocked by CI** and will fail the build, so never use them - Reference descriptions end with a second sentence: `API reference for X.` for API/library pages, or `Reference for X.` for non-API reference pages (ending with a period). - No broken internal links (verify the target file exists). - `related.links` follow the page-type rule: quickstart/entry pages point to four of that section's guides (or all if the section has fewer than four); guide pages link **all** the section's other guides, trimming to the four most relevant only when there are more than four others; neither links reference pages or quickstarts (the guide-less OpenAPI section is the only exception). -- **Machine-readable outputs are in sync:** every entry in each `meta.json` `pages` array resolves to a real file, and `llms.txt` has been regenerated so it lists only existing pages. +- **Machine-readable outputs are in sync:** every entry in each `meta.json` `pages` array resolves to a real file, and `llms.txt` and `sitemap.md` have been regenerated so they list only existing pages. - No typos; body prose sentences end with periods, and so do descriptions (a description that is a question ends with `?`; section-root tab subtitles take no period). diff --git a/docs/en-US/overview/for-coding-agents.mdx b/docs/en-US/overview/for-coding-agents.mdx index 4dff5e383..1eaa9d5c3 100644 --- a/docs/en-US/overview/for-coding-agents.mdx +++ b/docs/en-US/overview/for-coding-agents.mdx @@ -155,15 +155,17 @@ Don't: ## Links - [`llms.txt`](/llms.txt) — short, machine-readable docs index. +- [`sitemap.md`](/sitemap.md) — map of every docs page. - Quickstarts: [React](/docs/react/react-quickstart), [Node](/docs/node/quickstart), [Core library](/docs/platform/core/quickstart), and the [CLI](/docs/cli/quickstart). - [Key concepts](/docs/overview/key-concepts) — locales, context, and static vs. dynamic content. ```` ## Point agents at the docs [#point-agents] -Give your agent direct access to the docs so its answers stay accurate. General Translation publishes a machine-readable index at the site root: +Give your agent direct access to the docs so its answers stay accurate. General Translation publishes several machine-readable entry points at the site root: - [`llms.txt`](/llms.txt) — a short, [llmstxt.org](https://llmstxt.org/)-style index of the docs. +- [`sitemap.md`](/sitemap.md) — a linked map of every page in navigation order. Every docs page is also available as **raw Markdown**: append `.md` to any page URL (for example, `/docs/cli/quickstart.md`) to fetch the clean source instead of parsing rendered HTML.