diff --git a/DOCS-SKILL.md b/DOCS-SKILL.md index 2eae1247e..e09f6a965 100644 --- a/DOCS-SKILL.md +++ b/DOCS-SKILL.md @@ -265,9 +265,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: 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/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/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..6000e553f --- /dev/null +++ b/docs/en-US/integrations/google-drive/guides/configuring-google-drive.mdx @@ -0,0 +1,53 @@ +--- + +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 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. + +## 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..ececac4d1 --- /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 updates text that still has a matching location in 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 until the next full-page reload. + +## 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..af44fac98 --- /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 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/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..2076ebe2d --- /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 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. + +## 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 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 + +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..83960cf50 --- /dev/null +++ b/docs/en-US/integrations/google-drive/reference/connection.mdx @@ -0,0 +1,47 @@ +--- + +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] + +| 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. 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 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 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. + +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, 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] + +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..33d0407bb --- /dev/null +++ b/docs/en-US/integrations/google-drive/reference/supported-content.mdx @@ -0,0 +1,49 @@ +--- + +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. + +## 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 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] + +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. 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] + +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, inaccessible, or in the trash, the integration creates a replacement when the active Drive identity can still copy the source. + +## 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..666750a9a 100644 --- a/docs/en-US/integrations/index.mdx +++ b/docs/en-US/integrations/index.mdx @@ -7,6 +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. -- [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. + + 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/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/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/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. 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/(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/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. 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"