diff --git a/DOCS-SKILL.md b/DOCS-SKILL.md index 2eae1247..26075c8c 100644 --- a/DOCS-SKILL.md +++ b/DOCS-SKILL.md @@ -250,12 +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. Alongside the filetree, publish two machine-readable maps at the repo root, both **generated from the** `meta.json` **filetree** (never hand-edited): +The publishing app generates two machine-readable maps from the docs source: -- `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. +- `llms.txt` — an [llmstxt.org](https://llmstxt.org/)-style index for LLMs and agents, grouped by section. +- `sitemap.xml` — the standard sitemap for every published page, including localized docs URLs. -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. +Do not add hand-written copies to this repository. When you add, rename, remove, or reorder pages, keep the `meta.json` filetree valid so the publishing app generates current output. **Only include pages that actually exist** — omit in-progress sections and manifest-only stubs, and keep every link resolvable. ### Agent-navigable by default @@ -276,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`, the sitemap, and the most useful pages for deeper detail. +6. **Links** — point to `llms.txt`, `sitemap.xml`, 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. @@ -445,7 +445,7 @@ Cover, in this order (drop any part that does not yet exist rather than inventin 1. **Intro** — one or two sentences on why General Translation is built to be agent- and LLM-friendly (open-source libraries, predictable configuration, machine-readable docs). 2. **Drop-in agent guide** — the full agent guide (what to use, setup, core usage, commands, do/don't, links) embedded in a **single copyable code block** so a developer can paste it straight into their project's `AGENTS.md`, `CLAUDE.md`, or tool instructions. Use a fenced block with a `title="AGENTS.md"` and a wider outer fence (four backticks) so the guide's own inner code fences render as literal text. -3. **Point agents at the docs** — link the machine-readable entry points (`llms.txt` and the sitemap) and show how to add the docs as context in an agent. +3. **Point agents at the docs** — link the machine-readable entry points (`llms.txt` and `sitemap.xml`) and show how to add the docs as context in an agent. 4. **MCP server and agent skills** — if a General Translation MCP server or agent skill exists, show how to install and use it; otherwise omit this part. 5. **Editor-specific tips** — short, parallel bullets for the common agents (Cursor, Claude Code, Copilot), only where the guidance genuinely differs. Use tabs when the shape is identical (see Code blocks). 6. **Best practices** — a short decision list of what to hand an agent versus what to verify by hand (for example, let it wire up `` components, but always review generated translation context and locale configuration). @@ -715,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` 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, so the publishing app can generate current `llms.txt` and `sitemap.xml` output. - 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 3e9ac2d8..8f305e1f 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 the list of locales supported by `gt-next`](/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 a9424cb5..ba57cc36 100644 --- a/blog/en-US/best-localization-software.mdx +++ b/blog/en-US/best-localization-software.mdx @@ -24,9 +24,9 @@ The library knows nothing about your translations. The TMS knows nothing about y General Translation is not a library. It's not a TMS. It's the whole pipeline, used by developer-first teams at [Cursor](https://cursor.com), [Cognition](https://cognition.ai), [Windsurf](https://windsurf.com), [Mintlify](https://mintlify.com), and [ClickHouse](https://clickhouse.com). -- **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. +- **Open-source developer libraries**: [`gt-next`](/docs/react/nextjs-quickstart), [`gt-react`](/docs/react/react-quickstart), and support for [React Native/Expo](/docs/react/react-native-quickstart). 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](/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](/docs/react/nextjs-quickstart) 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 →](/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](/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 e1baad44..651dabb2 100644 --- a/blog/en-US/i18n-without-translation-files.mdx +++ b/blog/en-US/i18n-without-translation-files.mdx @@ -66,7 +66,7 @@ function CheckoutSummary({ itemCount, discount }) { } ``` -The `` component in [`gt-react`](https://generaltranslation.com/docs/react) marks a block of JSX for translation. The English stays in your component. When a user visits in Spanish, the content inside `` is replaced with its Spanish equivalent. Structure and formatting carry over. +The `` component in [`gt-react`](/docs/react/react-quickstart) marks a block of JSX for translation. The English stays in your component. When a user visits in Spanish, the content inside `` is replaced with its Spanish equivalent. Structure and formatting carry over. There's no `t('checkout.summary.title')`, no `en.json`, no per-locale JSON files to keep in sync. @@ -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. See the full walkthrough in the [React Quickstart](/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). +`gt-react` is open source. For Next.js App Router, use [`gt-next`](/docs/react/nextjs-quickstart). For React Native, use [`gt-react-native`](/docs/react/react-native-quickstart). diff --git a/blog/en-US/multilingual-nextjs-seo.mdx b/blog/en-US/multilingual-nextjs-seo.mdx index 228b5f8b..d73c95ef 100644 --- a/blog/en-US/multilingual-nextjs-seo.mdx +++ b/blog/en-US/multilingual-nextjs-seo.mdx @@ -22,7 +22,7 @@ A multilingual site without proper SEO setup has problems: - Incorrect language shown in search result snippets **The good news:** getting multilingual SEO right in Next.js isn't complicated. -There are six things you need to get right, and this guide covers all of them using [gt-next](https://generaltranslation.com/docs/react/nextjs). +There are six things you need to get right, and this guide covers all of them using [`gt-next`](/docs/react/nextjs-quickstart). --- @@ -309,9 +309,4 @@ 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 -- [Middleware guide](/docs/react/nextjs/app-router-middleware) for routing configuration -- [SSG guide](/docs/react/nextjs) for statically generating multilingual pages -- [RTL support](/docs/react/guides/managing-locales) for right-to-left languages +Use the [`gt-next` Quickstart](/docs/react/nextjs-quickstart) to set up the full internationalization stack. Then configure routing with the [middleware guide](/docs/react/nextjs/app-router-middleware), generate multilingual pages with [static site generation](/docs/react/nextjs/app-router-static-site-generation), and add [right-to-left support](/docs/react/guides/managing-locales). 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 d4902695..e60933db 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`](/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](/docs/cli/reference/commands/init) installs dependencies, wraps your Next.js config with [`withGTConfig`](/docs/react/nextjs/config), adds [`GTProvider`](/docs/react/reference/components/gt-provider) to your root layout, creates a [`gt.config.json`](/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: @@ -79,11 +79,6 @@ In production, translations are pre-generated. } ``` -The [`translate`](https://generaltranslation.com/docs/cli/reference/commands/translate) command scans your codebase for all `` usage, generates translations, and publishes them to a CDN. When your app builds, every locale is ready. +The [`translate`](/docs/cli/reference/commands/translate) command scans your codebase for all `` usage, generates translations, and publishes them to a CDN. When your app builds, every locale is ready. -## 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 +Use [variable components](/docs/react/guides/formatting-variables) for dynamic content inside ``, and use [branching components](/docs/react/guides/handling-plurals-and-branches) for locale-aware choices. [`useGT`](/docs/react/reference/hooks/use-gt) and [`getGT`](/docs/react/nextjs/reference/functions/get-gt) translate plain strings for attributes, placeholders, and metadata. To bundle translations with your app instead of loading them from the General Translation CDN, see [Storing translations](/docs/react/guides/storing-translations). diff --git a/blog/en-US/plurals.mdx b/blog/en-US/plurals.mdx index 9b275521..f3c3a64c 100644 --- a/blog/en-US/plurals.mdx +++ b/blog/en-US/plurals.mdx @@ -99,7 +99,7 @@ Although developers often think that i18n libraries are only for multilingual in they can be very useful for plural and variable formatting even in single-language applications. Under the hood, most i18n libraries use JavaScript's built-in `Intl.PluralRules` API to determine the correct plural form for any language. -There are plenty of React i18n libraries, including ours, [gt-react](/docs/react/overview) (or [gt-next](/docs/react/nextjs) if you're using Next.js). +There are plenty of React i18n libraries, including ours, [`gt-react`](/docs/react/overview) (or [`gt-next`](/docs/react/nextjs-quickstart) if you're using Next.js). Displaying an English plural using gt-react is simple: ```jsx @@ -200,7 +200,7 @@ Almost all libraries have dedicated documentation on rendering plurals. ### Full example: plurals in a multilingual React app -If you don't already have an internationalization library, consider [gt-react](https://generaltranslation.com/docs/react)! +If you don't already have an internationalization library, consider [`gt-react`](/docs/react/react-quickstart)! gt-react's `` component: @@ -235,12 +235,6 @@ function Example({ count }) { --- -## Next steps - -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 -- [`` API reference](/docs/react/reference/components/plural) for the full component API +Set up pluralization with the [`gt-react` Quickstart](/docs/react/react-quickstart) for React apps or the [`gt-next` Quickstart](/docs/react/nextjs-quickstart) for Next.js apps. See the [`` 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/devlog/en-US/gt-next_v6_10_0.mdx b/devlog/en-US/gt-next_v6_10_0.mdx index 1fef7c0c..c4a3da63 100644 --- a/devlog/en-US/gt-next_v6_10_0.mdx +++ b/devlog/en-US/gt-next_v6_10_0.mdx @@ -95,7 +95,7 @@ export default withGTConfig(nextConfig, { }) ``` -Remove any custom `getStaticLocale`, `getStaticRegion`, or `getStaticDomain` functions in favor of custom `getLocale`, `getRegion`, or `getDomain` functions. You must add a custom `getLocale` function and disable the `getRegion` function. For more information, see the [SSG guide](/docs/react/nextjs). +Remove any custom `getStaticLocale`, `getStaticRegion`, or `getStaticDomain` functions in favor of custom `getLocale`, `getRegion`, or `getDomain` functions. You must add a custom `getLocale` function and disable the `getRegion` function. For more information, see the [SSG guide](/docs/react/nextjs/app-router-static-site-generation). ```ts title="getLocale.ts" import { locale } from "next/root-params"; diff --git a/devlog/en-US/gt-react_v10_19_0.mdx b/devlog/en-US/gt-react_v10_19_0.mdx index 398a1267..10662373 100644 --- a/devlog/en-US/gt-react_v10_19_0.mdx +++ b/devlog/en-US/gt-react_v10_19_0.mdx @@ -43,7 +43,7 @@ export default defineConfig({ }); ``` -See the [gt-react setup docs](https://generaltranslation.com/docs/react/tutorials/quickstart) for other bundlers. +See the [`gt-react` SPA Quickstart](/docs/react/react-spa-quickstart) for other bundlers. ### 2. Enable dev hot reload in `gt.config.json` diff --git a/devlog/en-US/react-core-linter_v0_1_0.mdx b/devlog/en-US/react-core-linter_v0_1_0.mdx index c3ba626b..7eb028bf 100644 --- a/devlog/en-US/react-core-linter_v0_1_0.mdx +++ b/devlog/en-US/react-core-linter_v0_1_0.mdx @@ -81,7 +81,4 @@ Future versions will expand rule coverage and add auto-fixing for other common v --- -## Further reading - -- [Variable Components](/docs/react/guides/formatting-variables) - Handle dynamic content in translations -- [String Translation](/docs/react/guides/translating-strings) - Translate plain text strings +Use [variable components](/docs/react/guides/formatting-variables) for dynamic content and [string translation](/docs/react/guides/translating-strings) for plain text strings. diff --git a/docs/en-US/cli/guides/using-auto-jsx.mdx b/docs/en-US/cli/guides/using-auto-jsx.mdx index 91f1d1b6..2a624fc1 100644 --- a/docs/en-US/cli/guides/using-auto-jsx.mdx +++ b/docs/en-US/cli/guides/using-auto-jsx.mdx @@ -13,13 +13,39 @@ related: Automatic JSX injection makes the compiler wrap translatable JSX text in [``](/docs/react/reference/components/t) components at build time, so you do not have to add them by hand. -Automatic JSX injection is disabled by default. - -*Note: Automatic JSX injection currently works only with the i18n-context system and single-page React apps.* +Automatic JSX injection is disabled by default. It works in React single-page apps (SPAs) and Next.js webpack builds. ## Enable automatic JSX injection [#enable] -Set `enableAutoJsxInjection` under `files.gt.parsingFlags` in `gt.config.json`. +Install the compiler: + + + + ```bash + npm install @generaltranslation/compiler + ``` + + + + ```bash + yarn add @generaltranslation/compiler + ``` + + + + ```bash + bun add @generaltranslation/compiler + ``` + + + + ```bash + pnpm add @generaltranslation/compiler + ``` + + + +Set `enableAutoJsxInjection` under `files.gt.parsingFlags` in `gt.config.json`. This keeps CLI extraction and compiler transforms in sync. ```json title="gt.config.json" { @@ -33,12 +59,39 @@ Set `enableAutoJsxInjection` under `files.gt.parsingFlags` in `gt.config.json`. } ``` +## Configure the build [#configure-build] + +The `gt.config.json` flag takes effect when the General Translation compiler runs. + +### React SPAs + +Add `@generaltranslation/compiler` to your Vite, webpack, Rollup, or esbuild configuration. See [Developing SPA translations](/docs/react/guides/developing-spa-translations#2-add-the-compiler-plugin) for each bundler setup. + +### Next.js + +Configure `gt-next` to use the Babel-based webpack compiler: + +```ts title="next.config.ts" +import { withGTConfig } from 'gt-next/config'; + +const nextConfig = {}; + +export default withGTConfig(nextConfig, { + experimentalCompilerOptions: { + type: 'babel', + enableAutoJsxInjection: true, + }, +}); +``` + +Run Next.js with webpack. Turbopack disables the Babel compiler, warns that automatic injection will be skipped, and leaves JSX unwrapped. See [Next.js compiler options](/docs/react/nextjs/config#compiler-options). + ## 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 ( @@ -49,6 +102,8 @@ function Welcome() { } ``` +Next.js projects import `` from `gt-next` instead. + With injection enabled, the compiler detects the translatable text and wraps it automatically at build time. ```jsx diff --git a/docs/en-US/cli/reference/formats/gt-jsx-files.mdx b/docs/en-US/cli/reference/formats/gt-jsx-files.mdx index 7fbbb3ba..8e380d11 100644 --- a/docs/en-US/cli/reference/formats/gt-jsx-files.mdx +++ b/docs/en-US/cli/reference/formats/gt-jsx-files.mdx @@ -42,6 +42,7 @@ The `gt` entry accepts a `parsingFlags` object that controls how the CLI parses "gt": { "parsingFlags": { "autoderive": true, + "devHotReload": true, "enableAutoJsxInjection": true, "includeSourceCodeContext": true, "legacyGtReactImportSource": false @@ -52,6 +53,7 @@ The `gt` entry accepts a `parsingFlags` object that controls how the CLI parses ``` - `autoderive` — parses interpolated values in `t()`, `gt()`, and `msg()` calls and expressions inside `` components as if wrapped in `derive()`, generating a separate translation entry per possible value. Accepts `true` or an object such as `{ "jsx": true, "strings": false }`. See [Auto-derive translations](/docs/cli/guides/using-autoderive). +- `devHotReload` — enables runtime translation for new content during development. `true` enables string translation; use an object such as `{ "strings": true, "jsx": true }` to control string and JSX handling separately. - `enableAutoJsxInjection` — wraps translatable JSX text in `` components at build time so you do not have to add them by hand. See [Automatic JSX injection](/docs/cli/guides/using-auto-jsx). - `includeSourceCodeContext` — includes the surrounding source code lines as extra context for each translation. Replaces the deprecated top-level `files.gt.includeSourceCodeContext` key. - `legacyGtReactImportSource` — makes compiler-injected `gt-react` imports resolve to `gt-react/browser`, for projects that need the legacy import path. 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 00000000..75fa85a3 --- /dev/null +++ b/docs/en-US/integrations/google-drive/guides/managing-translations.mdx @@ -0,0 +1,50 @@ +--- + +title: Managing translations +description: "How to keep Google Drive translations up to date with General Translation: this guide covers applying source changes, forcing retranslation, reconnecting access, and unlinking files." +related: + links: + - /docs/integrations/google-drive/guides/translating-content + +--- + +After the first translation, use the Google Drive integration to update the existing locale copies. General Translation reuses reviewed translations by default and offers force retranslation when you need a clean pass. + +## Apply source changes [#apply-changes] + +When a source Google Doc or Google Slides file changes: + +1. Open **Project > Integrations > Google Drive**. +2. Select the changed files. +3. Choose the target locales. +4. Click **Apply changes**. + +General Translation reads the latest source and the existing target copy. It reuses existing translated content where possible, translates new or changed content, and updates that same target copy. + +If the source and target structures have drifted, the integration applies content that still has a matching location. Review the copy after each update, especially when slides, tables, or other structural elements changed. + +## Force retranslation [#force] + +Use force retranslation when you want to discard reusable translations and generate the selected file-locales again from scratch. + +1. Select at least one file that has a translated version. +2. Check **Force retranslation**. +3. Click **Retranslate**. +4. Confirm **Force retranslation** in the warning dialog. + +Force retranslation overwrites translations in the existing copies and incurs additional usage. The confirmation dialog can be dismissed for the rest of the current browser session. + +## Manage Drive access [#drive-access] + +Access depends on the mode selected when the Project integration was connected: + +- **Personal accounts:** each user connects a Google account. The integration can access files that the user selected and files it created. If access expires or the required permission is missing, click **Connect account** again. +- **Organization shared drives:** an Organization admin manages one shared drive connection under **Organization > Settings > Integrations**. The Project can only browse shared drives available to that connection. + +The Google account or Organization connection must be able to edit an existing locale copy. If a copy cannot be edited, General Translation stops that file-locale instead of creating an unrelated duplicate. + +## Unlink a source file [#unlink] + +Open the file's menu and choose **Remove** to unlink it from the Project integration. + +Unlinking does not delete the source file or any translated copies from Google Drive. You can add the source file again later. 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 00000000..c95c5c51 --- /dev/null +++ b/docs/en-US/integrations/google-drive/guides/meta.json @@ -0,0 +1,8 @@ +{ + "title": "guides", + "description": "Translate Google Drive files and keep their translated copies up to date with General Translation.", + "pages": [ + "./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 00000000..329f7cb1 --- /dev/null +++ b/docs/en-US/integrations/google-drive/guides/translating-content.mdx @@ -0,0 +1,57 @@ +--- + +title: Translating content +description: "How to translate Google Docs and Google Slides files with General Translation: this guide covers selecting files and locales, starting translation, and finding translated copies." +related: + links: + - /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 writes translated content to Drive copies, leaving the source files unchanged. + +## Select files [#select-files] + +Open **Project > Integrations > Google Drive**, then select one or more linked files. + +Each selected file keeps its own source locale. When selected files use different source locales, General Translation groups them into separate translation runs and excludes each source locale from that file's targets. + +To add another source file, click **Add files**. The picker accepts Google Docs and Google Slides files. See [Supported content](/docs/integrations/google-drive/reference/supported-content). + +## Select target locales [#select-locales] + +Use **Translate into** to choose one or more target locales. + +- If no locale is selected, the action reads **Select locales** and opens the locale selector. +- A source locale cannot also be a target for the same file. +- You can add a Project target locale from the selector without leaving the integration. + +You must select at least one file and one applicable target locale before translation can start. + +## Start translation [#start] + +The action label describes what the run will do: + +- **Translate:** none of the selected files has a translated copy yet. +- **Apply changes:** at least one selected file already has a translated copy. General Translation reuses existing translations where possible and updates the copy. +- **Retranslate:** **Force retranslation** is selected. General Translation ignores reusable translations and translates from scratch. + +Click the action. The Dashboard starts one background job for each selected file and target locale. + +## Monitor progress [#progress] + +The Dashboard reports progress by file and locale. Google Slides runs include a formatting phase after text translation so the translated deck can be adjusted for the new text. + +You can leave the page while jobs run. If some files or locales cannot start, the Dashboard reports a partial failure instead of marking the whole selection as started. + +## Find translated copies [#copies] + +The first successful run creates one Drive copy per source file and target locale. By default, the copy is named: + +```text + [] +``` + +For example, translating `Launch plan` into `fr` creates `Launch plan [fr]`. + +Later **Apply changes** and **Retranslate** runs update the same copy. If the stored copy was deleted or moved to trash, the integration creates a new one on the next successful run. 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 00000000..7b24633b --- /dev/null +++ b/docs/en-US/integrations/google-drive/meta.json @@ -0,0 +1,9 @@ +{ + "title": "Google Drive", + "description": "Translate Google Docs and Google Slides files from the General Translation 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 00000000..bbd94d03 --- /dev/null +++ b/docs/en-US/integrations/google-drive/quickstart.mdx @@ -0,0 +1,65 @@ +--- + +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/translating-content + - /docs/integrations/google-drive/guides/managing-translations + +--- + +Use the Google Drive integration to translate Google Docs and Google Slides files from the General Translation Dashboard. General Translation creates one translated Drive copy per target locale and updates that same 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 to connect the integration. +- `translations:content:write` permission to add, remove, or translate files. +- A Google account with access to the source files, unless your Organization has configured a shared drive connection. + +The integration supports Google Docs and Google Slides. See [Supported content](/docs/integrations/google-drive/reference/supported-content) for access and output details. + +## Quickstart [#quickstart] + +### 1. Connect Google Drive + +In the General Translation Dashboard, go to **Project > Integrations**, open the catalog, find **Google Drive**, and click **Connect**. + +If your Organization has a shared drive connection, choose how the Project accesses Drive: + +- **Use the org shared drive connection:** everyone with Project access can browse connected shared drives without connecting a personal Google account. +- **Each user connects their own Google account:** each person can browse files available to their connected account. + +Otherwise, the Project uses personal Google accounts. + +### 2. Authorize a personal account + +For personal access, click **Connect account** and authorize Google Drive. General Translation requests access to files you select or that it creates; it does not request access to every file in your Drive. + +Organization shared drive access does not require this step. + +### 3. Add source files + +Click **Add files** and select one or more Google Docs or Google Slides files. + +- Personal access opens Google Picker. You can select files from My Drive or shared drives that your account can access. +- Organization access opens the configured shared drive browser. + +The integration records each file's source locale from the Project default locale. Removing a file later unlinks it from the integration without deleting it from Google Drive. + +### 4. Select files and locales + +Select one or more linked files. Under **Translate into**, choose target locales that differ from each file's source locale. + +If the Project has no target locales yet, click **Select locales** and add them from the locale selector. + +### 5. Translate + +Click **Translate**. Translation and formatting continue in the background, and the Dashboard shows progress for each file and locale. + +For each target locale, General Translation creates a copy beside the source file named ` []`. Later runs update that copy instead of creating another one. + +See [Translating content](/docs/integrations/google-drive/guides/translating-content) for the full workflow and [Managing translations](/docs/integrations/google-drive/guides/managing-translations) for updates and forced retranslation. 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 00000000..8e5f7439 --- /dev/null +++ b/docs/en-US/integrations/google-drive/reference/meta.json @@ -0,0 +1,7 @@ +{ + "title": "reference", + "description": "Browse Reference pages for the General Translation Google Drive integration.", + "pages": [ + "./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 00000000..4a1afcdd --- /dev/null +++ b/docs/en-US/integrations/google-drive/reference/supported-content.mdx @@ -0,0 +1,67 @@ +--- + +title: Supported content +description: Learn which Google Drive files General Translation translates and how access and translated copies work. Reference for Google Drive supported content. + +--- + +The Google Drive integration translates native Google Docs and Google Slides files. It reads each source file, sends translatable text to General Translation, and applies the result to a Drive copy for each target locale. + +## Overview [#overview] + +| Topic | Description | +| --- | --- | +| [Supported file types](#file-types) | Native Drive files accepted by the integration. | +| [Access modes](#access-modes) | Personal-account and Organization shared drive access. | +| [Dashboard permissions](#permissions) | Permissions required to connect and run the integration. | +| [Translated copies](#translated-copies) | How locale copies are created and updated. | +| [Update behavior](#update-behavior) | Reuse, force retranslation, and structure changes. | + +## Supported file types [#file-types] + +| File type | MIME type | Supported | +| --- | --- | --- | +| Google Docs | `application/vnd.google-apps.document` | Yes | +| Google Slides | `application/vnd.google-apps.presentation` | Yes | + +The picker excludes other file types, including Google Sheets, PDFs, Microsoft Office files, images, and folders. + +Google Docs translation preserves the document structure while replacing translatable text. Google Slides translation applies text to a copy and runs a background formatting phase for the translated deck. + +## Access modes [#access-modes] + +| Mode | Google scope | Available files | +| --- | --- | --- | +| Personal account | `drive.file` | Files the user selects with Google Picker and files the integration creates. | +| Organization shared drives | `drive` | Shared drives that include the Organization's connected translation account. | + +Personal access is per user. Disconnecting a personal account removes that user's stored authorization but does not delete linked files or translated copies. + +Organization shared drive access is managed under **Organization > Settings > Integrations** and requires the shared drive feature on the Organization's plan. Projects using this mode do not require each user to connect a personal Google account. + +## Dashboard permissions [#permissions] + +| Action | Required permission | +| --- | --- | +| Connect the Project integration | `project:write` | +| Add or unlink files | `translations:content:write` | +| Start or force translation | `translations:content:write` | + +All actions are also limited by Project access and plan features. + +## Translated copies [#translated-copies] + +The integration creates one target copy for each source file and target locale. Its default name is ` []`, such as `Launch plan [fr]`. + +Later runs resolve the recorded target copy and update it in place. If the copy is trashed or no longer available, the integration creates a replacement on a later successful run. + +The active Google account or Organization connection must be able to create the first copy and edit later copies. A permission failure stops that file-locale; it does not silently create a duplicate. + +## Update behavior [#update-behavior] + +| Mode | Existing translations | Target copy | +| --- | --- | --- | +| **Apply changes** | Imported and reused where possible. | Updated in place. | +| **Force retranslation** | Ignored; content is translated from scratch. | Updated in place and overwritten. | + +The integration maps content between the current source and the existing copy. When their structures differ, it updates matching content. Google Slides also attempts to add, remove, and reorder whole slides before applying text; structural updates are best-effort, so review the resulting copy. diff --git a/docs/en-US/integrations/index.mdx b/docs/en-US/integrations/index.mdx index f6e81164..b38f59f1 100644 --- a/docs/en-US/integrations/index.mdx +++ b/docs/en-US/integrations/index.mdx @@ -7,6 +7,20 @@ 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. -- [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 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. + + + + Quickstart to connect Google Drive to General Translation and translate a Google Doc or Google Slides presentation from the Dashboard. + + diff --git a/docs/en-US/integrations/meta.json b/docs/en-US/integrations/meta.json index b3b093b6..76e42a90 100644 --- a/docs/en-US/integrations/meta.json +++ b/docs/en-US/integrations/meta.json @@ -3,5 +3,5 @@ "icon": "Plug", "root": true, "description": "CMS, Docs Frameworks", - "pages": ["./index", "./mintlify", "./sanity", "./storyblok"] + "pages": ["./index", "./mintlify", "./sanity", "./storyblok", "./google-drive"] } diff --git a/docs/en-US/integrations/mintlify/quickstart.mdx b/docs/en-US/integrations/mintlify/quickstart.mdx index 6261522f..793cd266 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 45dabcd0..c9aaf1bb 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 1eaa9d5c..63ac2449 100644 --- a/docs/en-US/overview/for-coding-agents.mdx +++ b/docs/en-US/overview/for-coding-agents.mdx @@ -155,7 +155,7 @@ Don't: ## Links - [`llms.txt`](/llms.txt) — short, machine-readable docs index. -- [`sitemap.md`](/sitemap.md) — map of every docs page. +- [`sitemap.xml`](/sitemap.xml) — map of every published 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. ```` @@ -165,7 +165,7 @@ Don't: 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. +- [`sitemap.xml`](/sitemap.xml) — a machine-readable map of every published page. 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/overview/key-concepts.mdx b/docs/en-US/overview/key-concepts.mdx index b1dcb07e..c0008f46 100644 --- a/docs/en-US/overview/key-concepts.mdx +++ b/docs/en-US/overview/key-concepts.mdx @@ -1,7 +1,7 @@ --- title: Key concepts -description: "Understanding the core concepts behind General Translation: including internationalization, localization, translation, locales, and context" +description: "Understand the core concepts behind General Translation, including internationalization, localization, translation, locales, and context." --- diff --git a/docs/en-US/platform/dashboard/get-started.mdx b/docs/en-US/platform/dashboard/get-started.mdx index 1d8ca5a3..f462fe92 100644 --- a/docs/en-US/platform/dashboard/get-started.mdx +++ b/docs/en-US/platform/dashboard/get-started.mdx @@ -59,6 +59,6 @@ If you do not see a page, check that you are in the right Organization or Projec **How do I update existing translations after changing the Glossary?** Select relevant terms and use Apply Glossary to update existing translations that contain selected Glossary terms. See [Define translation context](/docs/platform/dashboard/guides/adding-translation-context). -**How do I regenerate translations?** Use the CLI or Locadex to run a new translation pass. The Dashboard does not currently support full-file retranslation. +**How do I regenerate translations?** For code and uploaded translation files, use the CLI or Locadex to run a new translation pass; the Dashboard's **Translations** page does not run full-file retranslation. Linked Google Drive files can be regenerated with **Force retranslation** from the [Google Drive integration](/docs/integrations/google-drive/guides/managing-translations#force). **How do I sync Dashboard edits back to GitHub?** Use Locadex to create pull requests for Dashboard changes, such as manual translation edits or Apply Glossary updates. \ No newline at end of file diff --git a/docs/en-US/platform/dashboard/reference/supported-locales.mdx b/docs/en-US/platform/dashboard/reference/supported-locales.mdx index 1f452236..d1456e17 100644 --- a/docs/en-US/platform/dashboard/reference/supported-locales.mdx +++ b/docs/en-US/platform/dashboard/reference/supported-locales.mdx @@ -7,14 +7,10 @@ description: Search the locales supported by the General Translation platform. A list of the 110+ locales currently supported by General Translation. A machine-readable list is available at [`/locales.json`](/locales.json). +For the underlying standard, see the [IETF Language Tag Registry](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry), the [BCP 47 specification](https://www.rfc-editor.org/rfc/rfc5646.html), and the [W3C language-tag guide](https://www.w3.org/International/articles/language-tags/). + ## Search locales [#search-locales] Below is a searchable list of all the [locales](/docs/platform/core/guides/locale-codes) currently supported by the General Translation platform. - - -## Further reading [#further-reading] - -- Refer to the official [IETF Language Tag Registry](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry) - and the [BCP 47 / RFC 5646 specification](https://www.rfc-editor.org/rfc/rfc5646.html) for more information. -- See also the [W3C guide on language tags](https://www.w3.org/International/articles/language-tags/) for a practical overview. \ No newline at end of file + \ No newline at end of file diff --git a/docs/en-US/platform/index.mdx b/docs/en-US/platform/index.mdx index 4e73b1f7..d926ea77 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/(frameworks)/nextjs/config.mdx b/docs/en-US/react/(frameworks)/nextjs/config.mdx index 08965440..ff3cfd4a 100644 --- a/docs/en-US/react/(frameworks)/nextjs/config.mdx +++ b/docs/en-US/react/(frameworks)/nextjs/config.mdx @@ -226,7 +226,7 @@ Settings for the compiler plugin that analyzes your source at build time. Fields | `disableBuildChecks` | Disable build-time validation checks. | `boolean` | `false` | | `enableAutoJsxInjection` | Automatically wrap translatable JSX at build time. | `boolean` | `false` | -Set `enableAutoJsxInjection` here or under `files.gt.parsingFlags` in `gt.config.json`. Prefer `gt.config.json` to keep CLI extraction and compiler transforms in sync; see [Using automatic JSX injection](/docs/cli/guides/using-auto-jsx). In either case, configure `gt-next` to use the Babel-based webpack compiler: +Install `@generaltranslation/compiler`, then set `enableAutoJsxInjection` here or under `files.gt.parsingFlags` in `gt.config.json`. Prefer `gt.config.json` to keep CLI extraction and compiler transforms in sync; see [Using automatic JSX injection](/docs/cli/guides/using-auto-jsx). In either case, `type: 'babel'` is required so `gt-next` loads the compiler: ```ts title="next.config.ts" export default withGTConfig(nextConfig, { @@ -237,6 +237,8 @@ export default withGTConfig(nextConfig, { }); ``` +Automatic JSX injection only runs in webpack builds. Turbopack disables the Babel compiler, and `type: 'swc'` or `type: 'none'` does not support injection. In each case, `gt-next` warns that injection was skipped. + ### `headersAndCookies` [#headers-and-cookies] **Type** `object` · **Optional** diff --git a/docs/en-US/react/react-spa-quickstart.mdx b/docs/en-US/react/react-spa-quickstart.mdx index ff724683..4cc4a2cf 100644 --- a/docs/en-US/react/react-spa-quickstart.mdx +++ b/docs/en-US/react/react-spa-quickstart.mdx @@ -121,8 +121,7 @@ import gtConfig from '../gt.config.json'; import loadTranslations from './loadTranslations'; await initializeGTSPA({ - defaultLocale: gtConfig.defaultLocale, - locales: gtConfig.locales, + ...gtConfig, loadTranslations, }); @@ -137,7 +136,15 @@ CommonJS does not support top-level await. Wrap initialization in an async start ```js title="src/index.js" const { initializeGTSPA } = require('gt-react'); const gtConfig = require('../gt.config.json'); -const loadTranslations = require('./loadTranslations'); + +async function loadTranslations(locale) { + try { + return require(`./_gt/${locale}.json`); + } catch (error) { + console.warn(`No translations found for ${locale}`); + return {}; + } +} async function start() { await initializeGTSPA({ diff --git a/docs/en-US/react/reference/components/t.mdx b/docs/en-US/react/reference/components/t.mdx index 4bf4f52c..e29e893d 100644 --- a/docs/en-US/react/reference/components/t.mdx +++ b/docs/en-US/react/reference/components/t.mdx @@ -22,7 +22,7 @@ Wrap any static JSX in `` and it is translated into the active locale. Use va ``` -*Note: `` must be rendered inside a [``](/docs/react/reference/components/gt-provider) so it can access translations. For standalone strings, use [`useGT`](/docs/react/reference/hooks/use-gt) instead.* +*Note: Server-rendered `gt-react` apps provide translations through [``](/docs/react/reference/components/gt-provider). React SPAs initialized with [`initializeGTSPA`](/docs/react/reference/config#initialize-spa) do not need a provider; `gt-next` apps use the framework's ``.* ## How it works [#how-it-works]