docs: sync gt-sanity 3.1.4 behavior

devlog/en-US/gt-sanity_v3_1_0.mdx

@@ -9,7 +9,7 @@ tags: ['gt-sanity', 'v3.1.0', 'sanity', 'cms', 'translation', 'minor']
 
 Translated content rarely stays exactly as it arrives. Editors fix a term, tighten a headline, adjust tone for a market — and until now, the next translation run regenerated all of it.
 
-`gt-sanity` v3.1 adds **Save local edits**: the translations Sanity already holds are uploaded to General Translation before a translation run, so content whose source text has not changed keeps its existing wording. It is off by default and opt-in per Studio session.
+`gt-sanity` v3.1 adds **Save local edits**: the translations Sanity already holds are uploaded to General Translation before a translation run, so content whose source text has not changed keeps its existing wording. It is off by default. Since v3.1.4, the plugin remembers the editor's choice for each Sanity project and dataset.
 
 The release also adds a **Save Local Edits** action for uploading existing translations without starting a run, and a **Retranslate from scratch** option for deliberately regenerating everything.
 
@@ -41,7 +41,7 @@ export default defineConfig({
 });
 ```
 
-`preserveExistingTranslations` seeds the toggle when the Studio loads. Editors can flip it for their session from the UI.
+`preserveExistingTranslations` seeds the toggle when the Studio loads. Editors can change it from the UI; since v3.1.4, that choice is stored in the browser and takes precedence over the configured default on later visits.
 
 ### Sanity becomes the source of truth
 

docs/en-US/cli/reference/commands/translate.mdx

@@ -20,8 +20,8 @@ npx gt translate
 1. Reads `gt.config.json` to determine the target locales, the files to translate, and their output paths.
 2. For `gt-next`, `gt-react`, `gt-react-native`, and `gt-tanstack-start` projects, scans your `src` globs for inline content — [`<T>`](/docs/react/reference/components/t) components and [`useGT`](/docs/react/reference/hooks/use-gt) calls — and includes your dictionary file.
 3. Auto-detects a third-party i18n library from `package.json` — `next-intl` or `i18next` (with `i18next-icu` support) — and translates its JSON files while respecting that library's syntax.
-4. Detects local edits to previously downloaded translations and saves them to the platform. Pass `--no-save-local` to skip this step.
-5. Stages the collected content and downloads the results in one step. Internally this is [`gt stage`](/docs/cli/reference/commands/stage) followed by [`gt download`](/docs/cli/reference/commands/download); use the split commands to run those parts separately. Because Lottie layout processing is asynchronous, a project with `.lottie` files exits here when `stageTranslations` is `false` and directs you to the split flow.
+4. Stages the collected content with [`gt stage`](/docs/cli/reference/commands/stage): it uploads sources, detects and saves local edits to previous translations unless `--no-save-local` is set, then enqueues translation jobs.
+5. Downloads the results with [`gt download`](/docs/cli/reference/commands/download). Use the split commands to run staging and download separately. Because Lottie layout processing is asynchronous, a project with `.lottie` files exits here when `stageTranslations` is `false` and directs you to the split flow.
 6. Saves translations to your codebase, and to the CDN when `--publish` or the [`publish`](/docs/cli/reference/config#publish) config key is set.
 
 By default, the CLI syncs local translation edits before starting new work and does not overwrite them unless the source content has changed. Use `--force` to re-translate everything, or `--force-download` to re-download without re-translating.

docs/en-US/integrations/sanity/guides/configuring-sanity.mdx

@@ -33,6 +33,48 @@ export default defineConfig({
 });
 ```
 
+## Browse translations by locale [#browse-locales]
+
+Sanity normally lists translated documents alongside their source. Use `gtStructureItems` to group each translatable document type into one pane per locale while keeping your other structure items.
+
+```ts title="sanity.config.ts"
+import { defineConfig } from 'sanity';
+import { structureTool } from 'sanity/structure';
+import { gtPlugin, gtStructureItems } from 'gt-sanity';
+
+export default defineConfig({
+  plugins: [
+    gtPlugin({
+      sourceLocale: 'en',
+      locales: ['es', 'zh', 'ja'],
+      translateDocuments: [{ type: 'article' }, { type: 'page' }],
+    }),
+    structureTool({
+      structure: (S, context) =>
+        S.list()
+          .title('Content')
+          .items([
+            ...gtStructureItems(S, context),
+            S.divider(),
+            ...S.documentTypeListItems(),
+          ]),
+    }),
+  ],
+});
+```
+
+The source-locale pane includes documents with no language field, so content created before the plugin still appears. Types localized in place with internationalized arrays are skipped because their translations stay in the source document.
+
+If the Studio needs only the locale-grouped types, pass the complete `gtStructure()` resolver to `structureTool`:
+
+```ts
+import { gtStructure } from 'gt-sanity';
+
+structureTool({ structure: gtStructure() });
+```
+
+Pass `types` to either helper to override which document types are grouped. Use `sourceTitle` to rename the source pane, or `localeTitle` to build custom target-pane titles. See the [structure helper reference](/docs/integrations/sanity/reference/plugin-configuration#structure-helpers).
+
 ## Set source and target locales [#set-locales]
 
 Use `sourceLocale` for the source language and `locales` for the target languages.

docs/en-US/integrations/sanity/guides/managing-translations.mdx

@@ -26,7 +26,7 @@ The plugin registers a site-wide **Translations** tool that lists every translat
 - Patch references across translated documents (**Patch References**).
 - Publish translated documents whose source document is published (**Publish Translations**).
 
-Turn on **Auto-refresh** to poll translation status, or use **Refresh** to check once.
+Auto-refresh and auto-import are on by default. Auto-patch and auto-publish are off. Changes to these switches and **Save local edits** are remembered in browser storage for the current Sanity project and dataset.
 
 *Note: **Import Missing**, **Patch References**, and **Publish Translations** depend on document-level `translation.metadata`. For field-level localization, use **Import All** or import a locale from its status row, then review and publish the source document through Sanity's normal workflow.*
 
@@ -43,12 +43,22 @@ Generated translations must be imported into Sanity. For document-level localiza
 
 Translated documents may reference other documents. Reference patching rewrites each reference `_ref` to point to the referenced document's translation for the same locale, when one exists. The plugin resolves these from the `translation.metadata` documents.
 
-Use **Patch References** on the Translations tool to run this across existing translated documents. In the single-document dialog, it also runs automatically after import (auto-patch is on by default there).
+Use **Patch References** on the Translations tool to run this across existing translated documents, or turn on **Auto-patch after import** in the single-document dialog. Auto-patch is off by default.
+
+If a translated document is already published and has no draft, patching creates a draft from the published document and updates that draft. It does not change the published document directly.
 
 ## Publish translations [#publish]
 
 Use **Publish Translations** to publish translated documents in bulk. The plugin publishes only translation documents whose source document is published. This is useful after importing many translations or patching references across a locale.
 
+Imported document-level translations are created as drafts. Turn on **Auto-publish after import** to publish them automatically, or leave the default off to review them before publishing.
+
+## Inspect debug information [#debug-info]
+
+The footer of the **Translations** tool and document dialog shows the installed `gt-sanity` version. Click **Debug info** to inspect and copy the plugin's effective setup for a support request.
+
+The output includes resolved locales, translation mode, document and field rules, current preference values, translation counts, the Sanity project and dataset, and whether the secrets document was found. It never includes the API key, only whether one is configured.
+
 ## Manage field behavior [#field-behavior]
 
 Use field matchers when some fields should not be translated normally. Each matcher targets fields with a JSONPath `property` expression and, optionally, a document `_id`.

docs/en-US/integrations/sanity/guides/querying-translations.mdx

@@ -88,7 +88,7 @@ If your plugin config sets `languageField: 'locale'`, query `locale` instead of
 
 ### Query translated references
 
-After references are patched, translated documents point to the translated versions of referenced documents. Query them as you normally would.
+Reference patching updates the translated document's draft, creating one from the published state when needed. Publish the patched draft before querying from the published perspective. The translated document then points to translated versions of referenced documents.
 
 ```text
 *[_type == "article" && language == "es"]{

docs/en-US/integrations/sanity/guides/translating-content.mdx

@@ -23,7 +23,9 @@ The **Translate** action is available on every document, but the translation too
 3. Under **Translate**, select the target locales.
 4. Click **Translate**.
 
-Once translations are generated, the dialog polls for progress under **Translation Status**. For document-level localization, the plugin imports each locale document, patches its references, and publishes it because auto-import, auto-patch, and auto-publish are enabled by default. You can toggle each behavior, import a locale manually from its status row, or use **Import All**, **Patch References**, and **Publish Translations**.
+The dialog shows each locale as **Not translated**, **Translating…**, **Ready to import**, or **Imported** under **Translation Status**. While a run is outstanding, the **Translate** button stays disabled.
+
+For document-level localization, auto-refresh and auto-import are on by default, so translations that finish while the dialog is open are imported as drafts. Auto-patch and auto-publish are off by default. You can toggle each behavior, import a locale manually from its status row, or use **Import All**, **Patch References**, and **Publish Translations**. A translation that was already complete when you opened the dialog is not re-imported automatically, which preserves edits to its Sanity document.
 
 For field-level localization, import merges the translated values into `internationalizedArray*` fields on the same document. Review and publish that document in Sanity. Reference patching and the translation publishing controls apply only to document-level translations.
 
@@ -54,7 +56,7 @@ Turn on **Save local edits** to keep them. With the toggle on, each translation
 
 The toggle is in the **Translations** tool, and on the document tab as **Save local edits before translating**. It is off by default. Turning it on asks for confirmation first; turning it off takes effect immediately.
 
-The toggle applies to translation runs started from the current Studio session and resets when the Studio reloads. Set the state it starts from with [`preserveExistingTranslations`](/docs/integrations/sanity/reference/plugin-configuration#preserve-existing-translations).
+The plugin remembers this choice in browser storage for the current Sanity project and dataset. It takes precedence over the configured [`preserveExistingTranslations`](/docs/integrations/sanity/reference/plugin-configuration#preserve-existing-translations) default on later visits.
 
 Both localization strategies are covered. Document-level translations are read through `translation.metadata`, preferring drafts over published documents so unpublished edits count. Field-level translations are read from the source document's internationalized arrays. Locales with no existing content are skipped.
 
@@ -97,7 +99,7 @@ Slug fields are *not* stopped by default, so a slug's `current` value is sent fo
 
 Document-level translations can reference other documents. The plugin looks up each referenced document's translation and rewrites the reference to point to the correct locale version, when one exists.
 
-This runs automatically after import in the document dialog, and on demand with **Patch References** on the Translations page. See [Manage translations](/docs/integrations/sanity/guides/managing-translations#patch-references).
+Turn on **Auto-patch after import** to run this after each import, or use **Patch References** on demand. Auto-patch is off by default. See [Manage translations](/docs/integrations/sanity/guides/managing-translations#patch-references).
 
 ## Handle slugs and copied fields [#slugs-fields]
 

docs/en-US/integrations/sanity/quickstart.mdx

@@ -146,7 +146,9 @@ If you use multiple datasets, repeat this for each dataset. After verifying, del
 3. Select target locales.
 4. Click **Translate**.
 
-With this document-level setup, the plugin polls for completed translations and imports them automatically. After import, it patches document references and publishes the translated documents because auto-import, auto-patch, and auto-publish are on by default in this dialog.
+With this document-level setup, the plugin polls for completed translations and imports them automatically as drafts. Reference patching and publishing are off by default; use the dialog controls or configure their initial state with [`autoPatchReferences`](/docs/integrations/sanity/reference/plugin-configuration#auto-patch-references) and [`autoPublish`](/docs/integrations/sanity/reference/plugin-configuration#auto-publish).
+
+Review the imported documents in Sanity's **Drafts** perspective, then publish them before querying from a published-only frontend.
 
 See the full guides to [translate content](/docs/integrations/sanity/guides/translating-content) and [manage translations](/docs/integrations/sanity/guides/managing-translations).