Skip to content

README for v5 of the TOS plugin #3

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
amartinell wants to merge 2 commits into
base: main
Choose a base branch
from
Open

README for v5 of the TOS plugin #3

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
080d0d1
Init README for v5 of the TOS plugin
amartinell Jan 15, 2026
e7a750c
Updated README.md
amartinell Jan 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 22 additions & 4 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,8 +49,6 @@ const fieldLevelTypes = ['blog']

// Common TranslationOS configuration
const tosCommonConfig = {
apiKey: 'YOUR_TOS_API_KEY',
env: 'staging',
supportedLanguages: languages,
customBlockTypes: ['myblock'],
}
Expand Down Expand Up @@ -105,8 +103,6 @@ Returns a `ComponentViewBuilder` to be added to the _editor views_ for specific
**Recommended**: only enable for schema types configured in your internationalization plugin.

Options:
- `env` – TranslationOS API environment (`staging`, `sandbox` or `production`)
- `apiKey` – TranslationOS API key for the above environment
- `supportedLanguages` – array of `{id, title}` language objects
- `documentLocalizationSchemaTypes` – document types for document-level translation
- `fieldLocalizationSchemaTypes` – document types for field-level translation
Expand All @@ -126,6 +122,18 @@ Options:
- `customBlockTypes` – additional block type names to treat like Sanity's `block`
- `schemaTypes` – document types to manage with bulk translation

## Authentication
The plugin requires a TranslationOS API key to function. This API key will be stored securely in your Sanity dataset.
When you first use the plugin, you will be prompted to enter your API key and select the environment (`sandbox`, or `production`).

### {{insert image}}

## Reset authentication
Please note that the authentication configuration can be changed only be a Studio admin user.

### {{insert image}}


## Known limitations

For field translation mode:
Expand Down Expand Up @@ -293,3 +301,13 @@ export default defineType({
],
})
```
# Migration from older versions to v5
If you are migrating from version 4 or older to version 5 of the `sanity-plugin-tos`, please note the following.
For a better user experience, security issues and management of the TOS API key, we built a new configuration page that will automatically popup once you update to v5.
This new configuration page requires you to slightly change your TOS plugin configuration. Please follow the steps below:

- Remove the `apiKey` and `env` options from your TOS plugin configuration in `sanity.config.ts` or `sanity.config.js`, both from the `tosPlugin` or the `translationOS` tool.
- Start your Sanity Studio, the TOS configuration page should popup automatically.
- Fill in the required fields (TOS API key, environment) and save the configuration.

The configuration will be saved in your Sanity Studio dataset as a document of type `translationOSSettings`, and the plugin will use this configuration from now on.