![\"General](\"https://generaltranslation.com/brand/gt-logo-dark.svg\"){kind=logo}
\n \n \n \n
\n Documentation · Report Bug\n
\n\n# gt-sanity\n\nGeneral Translation plugin for Sanity Studio v3.\n\n## Installation\n\n```bash\nnpm install gt-sanity\n```\n\n## Quick Start\n\n```ts\nimport { defineConfig } from 'sanity';\nimport { gtPlugin } from 'gt-sanity';\n\nexport default defineConfig({\n plugins: [\n gtPlugin({\n sourceLocale: 'en',\n locales: ['es', 'fr'],\n // Initialize translated document slugs with a unique locale suffix,\n // e.g. \"hello-world\" -> \"hello-world-es\".\n dedupeFields: [{ fields: [{ property: '$.slug' }] }],\n }),\n ],\n});\n```\n\nSee the [full documentation](https://generaltranslation.com/docs/sanity) for guides and API reference.\n\n## Field-Level Localization\n\nField-level localization is powered by\n[`sanity-plugin-internationalized-array`](https://github.com/sanity-io/sanity-plugin-internationalized-array) —\nthe reference Sanity plugin. `gtPlugin` configures it for you from your\nlocales; gt-sanity does not ship its own field-level UI, so Studio behavior\nalways matches the native plugin.\n\n```ts\ngtPlugin({\n sourceLocale: 'en',\n locales: ['es', 'fr'],\n translateDocuments: ['post'],\n // Documents matched above are localized in place with\n // internationalized arrays instead of per-locale documents.\n translationLevel: 'internationalizedArray',\n fieldLevelLocalization: {\n enabled: true,\n fieldTypes: ['string', 'text'],\n },\n});\n```\n\nThen use the generated types in your schemas\n(`type: 'internationalizedArrayString'`, etc.).\n\n### Bringing your own plugin instance\n\nAlready registering `sanity-plugin-internationalized-array` yourself? Keep\nyour setup — GT translation only reads and writes the stored\n`{ _key, _type, language, value }` data, regardless of who registered the\nschema types. Leave `fieldLevelLocalization` disabled so the types are only\nregistered once, and just opt the documents into field-level translation:\n\n```ts\nplugins: [\n internationalizedArray({\n languages: [\n { id: 'en', title: 'English' },\n { id: 'es', title: 'Spanish' },\n ],\n fieldTypes: ['string'],\n }),\n gtPlugin({\n sourceLocale: 'en',\n locales: ['es'],\n translateDocuments: ['post'],\n translationLevel: 'internationalizedArray',\n // No fieldLevelLocalization — your plugin instance owns the types.\n }),\n],\n```\n\nTo verify: open a document of a matched type, run Translate from the\ndocument actions menu (or the Translations tool), and confirm each localized\nfield gains items for the target locales while the Studio UI (per-language\nadd buttons, language labels) stays exactly as your plugin configures it.\n\n## Excluding Fields from Translation\n\nMark fields in your schema instead of maintaining a list in the plugin\nconfig. gt-sanity honors its own `options.gt.exclude` plus the exclusion\noptions of the standard Sanity localization plugins:\n\n```ts\ndefineField({\n name: 'internalNotes',\n type: 'string',\n options: {\n gt: { exclude: true }, // excluded from GT translation\n // Also honored:\n // documentInternationalization: { exclude: true }, // @sanity/document-internationalization\n // aiAssist: { exclude: true }, // @sanity/assist\n },\n});\n```\n\nExclusion applies at any depth, including fields of nested object types, and\ncan also be set on a custom type definition's `options` to exclude every\noccurrence of that type (matching the native plugins' \"field or type\"\nsemantics). The legacy `localize: false` field property is still supported. For id-based or\ncross-document rules (e.g. slug deduplication), the plugin-level\n`ignoreFields` / `skipFields` / `dedupeFields` options remain available.\n\n## Preserving Edits to Translations\n\nTranslated content often gets touched up in the Studio after it comes back from\nGeneral Translation, and a later translation run would normally regenerate it.\nThe **Save local edits** toggle in the Translations tool changes that:\nwith it on, the translations currently in Sanity are uploaded to General\nTranslation before a translation run, so content whose source text has not\nchanged is reused from the Sanity version instead of being regenerated.\n\nThis is **off by default**; turning it on shows an explanation of the trade-off\nfirst, and the choice is remembered for that project and dataset. Turning it on means local\ncontent overwrites whatever General Translation holds for that source version —\nincluding a completed translation that has not been imported into Sanity yet.\nImport pending translations before enabling it if that matters to you.\n\nSet the initial state of the toggle from plugin config:\n\n```ts\ngtPlugin({\n // ...\n preserveExistingTranslations: true,\n});\n```\n\nTo upload the translations already in Sanity without starting a translation run\n— useful when adopting the plugin on a project that was translated elsewhere —\nuse **Save Local Edits**. It uploads the source files it needs, but does not\nenqueue any translation.\n\nTo regenerate translations and deliberately discard existing ones for a single\nrun, use **Retranslate from scratch** in the Translate All dialog.\n\n## Automatic Actions\n\nThe Translate dialog on a document can refresh status, import a translation as\nsoon as it lands, repoint references, and publish the result. Each is a switch\nin that dialog, and each has a plugin-level default:\n\n```ts\ngtPlugin({\n // ...\n autoRefresh: true, // poll for completed translations\n autoImport: true, // import a translation as soon as it completes\n autoPatchReferences: false, // repoint references after import\n autoPublish: false, // publish translated documents after import\n});\n```\n\nThe defaults turn on what only reads or writes drafts, and leave off anything\nthat can reach readers:\n\n- `autoRefresh` only polls for status, and auto-import depends on it.\n- `autoImport` writes drafts, which are cheap to discard.\n- `autoPatchReferences` usually writes a draft too, but when a translated\n document is already published and has no draft, the reference rewrite is\n applied to a draft seeded from it rather than to the published document.\n Still opt-in, because it edits documents you may consider finished.\n- `autoPublish` publishes, and turning the switch back off unpublishes nothing.\n\nThese are starting points, not locks. Whatever the user sets in the Studio is\nremembered in `localStorage` for that project and dataset, and is preferred\nover the config on their next visit. The **Save local edits** toggle\n(`preserveExistingTranslations`) is remembered the same way; enabling it still\nshows its explanation first.\n\nTranslated documents are always created as **drafts**. With `autoPublish` off\nthey stay that way until someone publishes them — so if a translation seems\nmissing after a run, check the Drafts perspective before assuming it wasn't\ncreated.\n\n## Browsing Translations by Locale\n\nBy default a translated document sits in the same list as its source, so a\ntype's list grows by one entry per locale. `gtStructureItems` groups them\ninstead: each translatable type expands into a pane per locale.\n\n```ts\nimport { structureTool } from 'sanity/structure';\nimport { gtStructureItems } from 'gt-sanity';\n\nstructureTool({\n structure: (S, context) =>\n S.list()\n .title('Content')\n .items([\n ...gtStructureItems(S, context),\n S.divider(),\n ...S.documentTypeListItems(),\n ]),\n});\n```\n\nThis is opt-in: the structure tool's layout belongs to `structureTool()` in\nyour Studio config, so a plugin cannot set it for you. Use `gtStructure()` for\nthe whole structure when you have no other list items:\n\n```ts\nimport { gtStructure } from 'gt-sanity';\n\nstructureTool({ structure: gtStructure() });\n```\n\nThe source pane includes documents whose language field is unset, since content\nthat predates the plugin has no language. Types localized in place with\ninternationalized arrays are skipped — their translations live inside the source\ndocument, so there is nothing to group. Pass `types` to override which types are\ngrouped, and `sourceTitle` / `localeTitle` to change the pane titles.\n\n## Debug Info\n\nThe Translations tool footer shows the installed plugin version and a **Debug\ninfo** button. It opens the plugin's effective configuration — resolved source\nand target locales, `translationLevel`, which documents are matched, field\nrules, the active preferences, and whether the secrets document was found — with\na button to copy it for a support request.\n\nThe API key is never included, only whether one is set.\n","readmeFilename":"README.md"}