sanity-plugin-studio-smartling 2.0.6 → 3.0.0-beta-private

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Sanity.io
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,146 +1,276 @@
+> This is a **Sanity Studio v3** plugin.
+
+## Installation
+
+```sh
+npm install sanity-plugin-studio-smartling
+```
+
+## Usage
 
 # Studio Plugin for Sanity & Smartling
 
 ![smartling gif](https://user-images.githubusercontent.com/3969996/125689321-bf37021f-ba55-4147-83eb-1745eb8acb1f.gif)
 
-
 We're proud to be partnered with Smartling and their [official connector](https://help.smartling.com/hc/en-us/articles/1260803085050-Sanity-Connector-Overview-) makes it quick and easy to get your studio content into your Smartling project.
 
 This is a separate plugin, and differs in that it provides editors a visual progress bar for ongoing translations and a way to import translations back into your content at either the document or field level. Feel free to try it out and see which solution works for you!
 
 # Table of Contents
-- [Plugin features](#plugin-features)
-- [Assumptions](#assumptions)
+
 - [Quickstart](#quickstart)
+- [Assumptions](#assumptions)
 - [Studio experience](#studio-experience)
 - [Overriding defaults](#overriding-defaults)
-- [v1 to v2 changes](#v1-to-v2-changes)
+- [License](#license)
+- [Develop and test](#develop-and-test)
+
+## Quickstart
 
-## Plugin features
+1. In your studio folder, run:
 
-This plugin comes with (and exposes to the developer) the following items:
-- An `Adapter` that connects to the Smartling API with methods to create a new translation job, upload and assign a file to that translation job, check the progress of an ongoing translation, and retrieve a translated file.
-- A `Serializer` that transforms your content into HTML (we found this was the most efficient way to maintain your document structure, no matter how deeply nested, while remaining readable to translators in Smartling). The `Serializer` takes in optional arguments: `stopTypes`, which prevents certain types from being sent to your translatiors and `customSerializers`, which are rules you can use to have full control over how individual fields on your document get serialized.
-- A `Deserializer` that deserializes translated text back to Sanity's format.
-- A `Patcher` which determines how your content gets patched back into its destination document or field.
-- A `TranslationsTab`, a React element that allows a non-technical user to import, export, and monitor Smartling progress.
+```sh
+npm install sanity-plugin-studio-smartling
+```
+
+2. Because of Smartling CORS restrictions, you will need to set up a proxy endpoint to funnel requests to Smartling. We've provided a tiny Next.js app you can set up [here](https://github.com/sanity-io/example-sanity-smartling-proxy). If that's not useful, the important thing to pay attention to is that this endpoint handles requests with an `X-URL` header that contains the Smartling URL configured by the plugin, and can parse a data file to an HTML string and send it back to the adapter.
 
-To make life easier, we also include `defaultFieldLevelConfig` and `defaultDocumentLevelConfig`, which bundles all of the above up to get you up and running quickly. 
+3. Ensure the plugin has access to your Smartling project token. You'll want to create a document that includes your project name, organization name, and a token with appropriate access.
+
+[Please refer to the Smartling documentation on creating a token if you don't have one already.](https://help.smartling.com/hc/en-us/articles/115004187694-API-Tokens)
+
+In your Studio folder, create a file called `populateSmartlingSecrets.js` with the following contents:
+
+```javascript
+// ./populateSmartlingSecrets.js
+// Do not commit this file to your repository
+
+import {getCliClient} from 'sanity/cli'
+
+const client = getCliClient({apiVersion: '2023-02-15'})
+
+client.createOrReplace({
+  // The `.` in this _id will ensure the document is private
+  // even in a public dataset!
+  _id: 'translationService.secrets',
+  _type: 'smartlingSettings',
+  //replace these with your values
+  organization: 'YOUR_SMARTLING_ORGANIZATION_HERE',
+  project: 'YOUR_SMARTLING_PROJECT_HERE',
+  secret: '{"userIdentifier":"xxxxxx","userSecret":"xxxx"}', //in this format from Smartling when you press the button "copy token" on creation
+  proxy: 'my-proxy-endpoint.com/api/proxy' //the endpoint you set up in step 2
+})
+```
+
+On the command line, run the file:
+
+```sh
+npx sanity exec populateSmartlingSecrets.js --with-user-token
+```
+
+Verify that the document was created using the Vision Tool in the Studio and query `*[_id == 'translationService.secrets']`. Note: If you have multiple datasets, you'll have to do this across all of them.
+
+If the document was found in your dataset(s), delete `populateSmartlingSecrets.js`.
+
+If you have concerns about this being exposed to authenticated users of your studio, you can control access to this path with [role-based access control](https://www.sanity.io/docs/access-control).
+
+4. Get the Smartling tab on your desired document type, using whatever pattern you like. You'll use the [desk structure](https://www.sanity.io/docs/structure-builder-introduction) for this. The options for translation will be nested under this desired document type's views. Here's an example:
+
+```javascript
+import {DefaultDocumentNodeResolver} from 'sanity/desk'
+//...your other desk structure imports...
+import {TranslationsTab, defaultDocumentLevelConfig} from 'sanity-plugin-studio-smartling'
+
+export const getDefaultDocumentNode: DefaultDocumentNodeResolver = (S, {schemaType}) => {
+  if (schemaType === 'myTranslatableDocumentType') {
+    return S.document().views([
+      S.view.form(),
+      //...my other views -- for example, live preview, document pane, etc.,
+      S.view.component(TranslationsTab).title('Smartling').options(defaultDocumentLevelConfig)
+    ])
+  }
+  return S.document()
+}
+```
+
+And that should do it! Go into your studio, click around, and check the document in Smartling (it should be under its Sanity `_id` by default, but you can override this). Once it's translated, check the import by clicking the `Import` button on your Smartling tab!
 
 ## Assumptions
-To use the default config mentioned above, we assume that you are following the conventions we outline in [our documentation on localization](https://www.sanity.io/docs/localization). 
 
+To use the default config mentioned above, we assume that you are following the conventions we outline in [our documentation on localization](https://www.sanity.io/docs/localization).
 
 ### Field-level translations
+
 If you are using field-level translation, we assume any fields you want translated exist in the multi-locale object form we recommend.
 For example, on a document you don't want to be translated, you may have a "title" field that's a flat string: `title: 'My title is here.'` For a field you want to include many languages for, your title may look like
-        ```
-        { title: {
-            en: 'My title is here.',
-            es: 'Mi título está aquí.',
-            etc...
-          }
-        }
-        ```
-*Important*: Smartling's locale representation includes hyphens, like `fr-FR`. These aren't valid as Sanity field names, so ensure that on your fields you change the hyphens to underscores (like `fr_FR`).
+`    
+{ 
+  title: {
+    en: 'My title is here.',
+    es: 'Mi título está aquí.',
+    etc...
+  }
+}
+   `
+_Important_: Smartling's locale representation includes hyphens, like `fr-FR`. These aren't valid as Sanity field names, so ensure that on your fields you change the hyphens to underscores (like `fr_FR`).
 
 ### Document level translations
+
 Since we often find users want to use the [Document internationalization plugin](https://www.sanity.io/plugins/document-internationalization) if they're using document-level translations, we assume that any documents you want in different languages will follow the pattern `{id-of-base-language-document}__i18n_{locale}`
 
 ### Final note
+
 It's okay if your data doesn't follow these patterns and you don't want to change them! You will simply have to override how the plugin gets and patches back information from your documents. Please see [Overriding defaults](#overriding-defaults).
 
 ## Quickstart
-1. Install this plugin with `npm install sanity-plugin-studio-smartling`
-
-2. Because of Smartling CORS restrictions, you will need to set up a proxy endpoint to funnel requests to Smartling. We've provided a tiny Next.js app you can set up [here](https://github.com/sanity-io/example-sanity-smartling-proxy). If that's not useful, the important thing to pay attention to is that this endpoint handles requests with an `X-URL` header that contains the Smartling URL configured by the plugin, and can parse a data file to an HTML string and send it back to the adapter.
 
-3. Once your proxy is set up, ensure that endpoint is available to your Sanity studio by placing it in the appropriate `.env` file (if you're developing locally, that's `.env.development`). That file should look like this:
-```
-#any other environment variables...
-SANITY_STUDIO_SMARTLING_PROXY=http://your-proxy-url.com
-```
+1. Install this plugin with `npm install sanity-plugin-studio-smartling`
 
-4. Ensure the plugin has access to your Smartling token secret. You'll want to create a document that includes your project name and a token secret with appropriate access. [Please refer to the Smartling documentation on creating a token if you don't have one already.](https://help.smartling.com/hc/en-us/articles/115004187694-API-Tokens-)
-    * In your studio, create a file called `populateSmartlingSecrets.js`.
-    * Place the following in the file and fill out the correct values.
+2. Ensure the plugin has access to your Smartling token secret. You'll want to create a document that includes your project name and a token secret with appropriate access. [Please refer to the Smartling documentation on creating a token if you don't have one already.](https://help.smartling.com/hc/en-us/articles/115004187694-API-Tokens-)
+   - In your studio, create a file called `populateSmartlingSecrets.js`.
+   - Place the following in the file and fill out the correct values.
 
 ```javascript
 import sanityClient from 'part:@sanity/base/client'
 
-const client = sanityClient.withConfig({ apiVersion: '2021-03-25' })
+const client = sanityClient.withConfig({apiVersion: '2021-03-25'})
 
 client.createOrReplace({
-_id: 'translationService.secrets',
-_type: 'smartlingSettings',
-organization: 'YOUR_ORG_HERE',
-project: 'YOUR_PROJECT_HERE',
-secret: '{"userIdentifier":"xxxxxx","userSecret":"xxxx"}', //in this format from Smartling
+  _id: 'translationService.secrets',
+  _type: 'smartlingSettings',
+  organization: 'YOUR_ORG_HERE',
+  project: 'YOUR_PROJECT_HERE',
+  secret: '{"userIdentifier":"xxxxxx","userSecret":"xxxx"}' //in this format from Smartling
 })
 ```
 
-   * On the command line, run the file with `sanity exec populateSmartlingSecrets.js --with-user-token`. 
-   Verify that everything went well by using Vision in the studio to query `*[_id == 'translationService.secrets']`. (NOTE: If you have multiple datasets, you'll have to do this across all of them, since it's a document!)
-   * If everything looks good, go ahead and delete `populateSmartlingSecrets.js` so you don't commit it. 
-   Because the document's `_id` is on a path (`translationService`), it won't be exposed to the outside world, even in a public dataset. If you have concerns about this being exposed to authenticated users of your studio, you can control access to this path with [role-based access control](https://www.sanity.io/docs/access-control).
+- On the command line, run the file with `sanity exec populateSmartlingSecrets.js --with-user-token`.
+  Verify that everything went well by using Vision in the studio to query `*[_id == 'translationService.secrets']`. (NOTE: If you have multiple datasets, you'll have to do this across all of them, since it's a document!)
+- If everything looks good, go ahead and delete `populateSmartlingSecrets.js` so you don't commit it.
+  Because the document's `_id` is on a path (`translationService`), it won't be exposed to the outside world, even in a public dataset. If you have concerns about this being exposed to authenticated users of your studio, you can control access to this path with [role-based access control](https://www.sanity.io/docs/access-control).
 
 5.  Now it's time to get the Smartling tab on your desired document type, using whatever pattern you like. You'll use the [desk structure](https://www.sanity.io/docs/structure-builder-introduction) for this. The options for translation will be nested under this desired document type's views. Here's an example:
 
 ```javascript
-import S from '@sanity/desk-tool/structure-builder'
+import {DefaultDocumentNodeResolver} from 'sanity/desk'
 //...your other desk structure imports...
-import { TranslationsTab, defaultDocumentLevelConfig } from 'sanity-plugin-studio-smartling'
-
+import {TranslationsTab, defaultDocumentLevelConfig} from 'sanity-plugin-studio-smartling'
 
-export const getDefaultDocumentNode = (props) => {
-  if (props.schemaType === 'myTranslatableDocumentType') {
+export const getDefaultDocumentNode: DefaultDocumentNodeResolver = (S, {schemaType}) => {
+  if (schemaType === 'myTranslatableDocumentType') {
     return S.document().views([
       S.view.form(),
       //...my other views -- for example, live preview, the i18n plugin, etc.,
-      S.view.component(TranslationsTab).title('Smartling').options(
-        defaultDocumentLevelConfig  
-      )
+      S.view.component(TranslationsTab).title('Smartling').options(defaultDocumentLevelConfig)
     ])
   }
-  return S.document();
-};
+  return S.document()
+}
+```
+
+And that should do it! Go into your studio, click around, and check the document in Smartling (it should be a job under its Sanity `_id`). Once it's translated, check the import by clicking the `Import` button on your Smartling tab!
+
+## Assumptions
+
+To use the default config mentioned above, we assume that you are following the conventions we outline in [our documentation on localization](https://www.sanity.io/docs/localization).
+
+### Field-level translations
+
+If you are using field-level translation, we assume any fields you want to be translated exist in the multi-locale object form we recommend.
+
+For example, on a document you don't want to be translated, you may have a "title" field that's a flat string: `title: 'My title is here.'` For a field you want to include many languages for your title may look like:
+
+```javascript
+{
+  //...other document fields,
+  title: {
+    en: 'My title is here.',
+    es: 'Mi título está aquí.',
+    etc...
+  }
+}
 ```
 
-And that should do it! 
+### Document level translations
+
+Since we often find users want to use the [Document internationalization plugin](https://www.sanity.io/plugins/document-internationalization) if they're using document-level translations, we assume that any documents you want in different languages will follow the pattern `{id-of-base-language-document}__i18n_{locale}`
+
+### Final note
+
+It's okay if your data doesn't follow these patterns and you don't want to change them! You will simply have to override how the plugin gets and patches back information from your documents. Please see [Overriding defaults](#overriding-defaults).
 
 ## Studio experience
-By adding the `TranslationsTab` to your desk structure, your users should now have an additional view. The boxes at the top of the tab can be used to send translations off to Smartling, and once those jobs are started, they should see progress bars monitoring the progress of the jobs. They can import a partial or complete job back.
+
+By adding the `TranslationsTab` to your desk structure, your users should now have an additional view on their document. The boxes at the top of the tab can be used to send translations off to Smartling, and once those jobs are started, they should see progress bars monitoring the progress of the jobs. They can import a partial or complete job back. They can also re-send a document, which should update the existing job.
 
 ## Overriding defaults
 
 To personalize this configuration it's useful to know what arguments go into `TranslationsTab` as options (the `defaultConfigs` are just wrappers for these):
-  * `exportForTranslation`: a function that takes your document id and returns an object with `name`: the field you want to use identify your doc in Smartling (by default this is `_id` and `content`: a serialized HTML string of all the fields in your document to be translated.
-  * `importTranslation`: a function that takes in `id` (your document id) `localeId` (the locale of the imported language) and `document` the translated HTML from Smartling. It will deserialize your document back into an object that can be patched into your Sanity data, and then executes that patch.
-  * `Adapter`: An interface with methods to send things over to Smartling. You likely don't want to override this!
 
-There are a number of reasons to override these functions. More general cases are often around ensuring documents serialize and deserialize correctly. Since the serialization fucntions are used across all our translation plugins currently, you can find some frequently encountered scenarios at [their repository here](https://github.com/sanity-io/sanity-naive-html-serializer), along with code examples for new config. 
+- `exportForTranslation`: a function that takes your document id and returns an object like:
 
-This plugin is in early stages. We plan on improving some of the user-facing chrome, sorting out some quiet bugs, figuring out where things don't fail elegantly, etc. Please be a part of our development process!
+```javascript
+{
+ `name`: /*the field you want to use identify your doc in Smartling (by default this is `_id`) */
+ `content`: /* a serialized HTML string of all the fields in your document to be translated. */
+}
+```
 
-## V1 to V2 changes
+- `importTranslation`: a function that takes in `id` (your document id), `localeId` (the locale of the imported language), and `document` (the translated HTML from Smartling). It will deserialize your document back into an object that can be patched into your Sanity data, and then executes that patch.
+- `Adapter`: An interface with methods to send things over to Smartling. You likely don't want to override this!
 
-Most users will not encounter issues in upgrading to v2. The breaking changes are as follows:
+There are several reasons to override these functions. Generally, developers will customize to ensure documents serialize and deserialize correctly. Since the serialization functions are used across all our translation plugins currently, you can find some frequently encountered scenarios at [their repository here](https://github.com/sanity-io/sanity-naive-html-serializer), along with code examples for customized configurations.
 
-1. **Change to document-level localization id structure.** Since the [Internationalization input plugin](https://www.sanity.io/plugins/sanity-plugin-intl-input) was deprecated, the default pattern `i18n.{id-of-base-language-document}.{locale}` was deprecated in favor of `{id-of-base-language-document}__i18n_{locale}`. If you would like to maintain that pattern, please add the `idStructure` param to your tab config, like:
-```javascript
-S.view.component(TranslationsTab).title('Smartling').options(
-  {...defaultDocumentLevelConfig, idStructure: 'subpath'}
-)
-```
-2. **Underlying changes in serializers.** Serializers were updated to a) take advantage of the newer [Portable Text to HTML package](https://github.com/portabletext/to-html) and allow for explicit schema closures. If you were overriding serialization methods, that means invocation of `BaseDocumentSerializer` will change from:
-```javascript
-BaseDocumentSerializer.serializeDocument(id, 'serialization-level')
+## Migrating to Sanity Studio v3
+
+There is one major breaking change in this plugin's migration to Sanity Studio v3: the proxy was set in an environment variable, and now it should be part of the `secrets` document.
+
+In v2, you would set the proxy in a `.env` file, like so:
+
+```env
+SANITY_STUDIO_SMARTLING_PROXY=https://my-proxy-endpoint.com/api/proxy
 ```
 
-to:
+In v3, you should set the proxy in the `secrets` document. If you have an existing secrets document, you can patch it like so:
+
 ```javascript
-import schemas from 'part:@sanity/base/schema'
+// ./patchSmartlingSecrets.js
+// Do not commit this file to your repository
+
+import {getCliClient} from 'sanity/cli'
 
-BaseDocumentSerializer(schemas).serializeDocument(id, 'serialization-level')
+const client = getCliClient({apiVersion: '2023-02-15'})
+
+client.patch('translationService.secrets').set({proxy: 'https://my-proxy.com/api/proxy'}).commit()
 ```
 
+and run the script with `sanity exec patchSmartlingSecrets.js --with-user-token`.
+
+Alternatively, you can re-run the `populateSmartlingSecrets` script in [Quickstart](#quickstart) to create a new secrets document with the proxy set.
+
+We apologize for the inconvenience. Because of the new embeddability of the studio, developers may find that their v3 Studio is built and deployed in different ways, with access to different environments. Keeping this setting in `secrets` allows developers to set it in a way that works for their deployment and reduce complexity.
+
+Otherwise, you should not have to do anything to migrate to Sanity Studio v3. If you are using the default configs, you should be able to upgrade without any changes. If you are using custom serialization, you may need to update how `BaseDocumentSerializer` receives your schema.
+
+These are outlined in the serializer README [here](https://github.com/sanity-io/sanity-naive-html-serializer#v2-to-v3-changes).
+
+## License
+
+[MIT](LICENSE) © Sanity.io
+
+## Develop & test
+
+This plugin is in early stages. We plan on improving some of the user-facing chrome, sorting out some quiet bugs, figuring out where things don't fail elegantly, etc. Please be a part of our development process!
+
+This plugin uses [@sanity/plugin-kit](https://github.com/sanity-io/plugin-kit)
+with default configuration for build & watch scripts.
+
+See [Testing a plugin in Sanity Studio](https://github.com/sanity-io/plugin-kit#testing-a-plugin-in-sanity-studio)
+on how to run this plugin with hotreload in the studio.
+
+### Release new version
+
+Run ["CI & Release" workflow](https://github.com/sanity-io/sanity-plugin-transifex/actions/workflows/main.yml).
+Make sure to select the main branch and check "Release new version".
+
+Semantic release will only release on configured branches, so it is safe to run release on any branch.

package/dist/index.d.ts

@@ -1,11 +1,53 @@
-import { TranslationsTab, findLatestDraft, BaseDocumentDeserializer, BaseDocumentSerializer, BaseDocumentMerger, defaultStopTypes, customSerializers, Adapter, documentLevelPatch, fieldLevelPatch } from 'sanity-translations-tab';
-import { SmartlingAdapter } from './adapter';
-interface ConfigOptions {
-    adapter: Adapter;
-    secretsNamespace: string | null;
-    exportForTranslation: (id: string) => Promise<Record<string, any>>;
-    importTranslation: (id: string, localeId: string, doc: string) => Promise<void>;
-}
-declare const defaultDocumentLevelConfig: ConfigOptions;
-declare const defaultFieldLevelConfig: ConfigOptions;
-export { TranslationsTab, findLatestDraft, documentLevelPatch, fieldLevelPatch, BaseDocumentDeserializer, BaseDocumentSerializer, BaseDocumentMerger, defaultStopTypes, customSerializers, SmartlingAdapter, defaultDocumentLevelConfig, defaultFieldLevelConfig, };
+import {Adapter} from 'sanity-translations-tab'
+import {BaseDocumentDeserializer} from 'sanity-translations-tab'
+import {BaseDocumentMerger} from 'sanity-translations-tab'
+import {BaseDocumentSerializer} from 'sanity-translations-tab'
+import {customSerializers} from 'sanity-translations-tab'
+import {defaultStopTypes} from 'sanity-translations-tab'
+import {documentLevelPatch} from 'sanity-translations-tab'
+import {fieldLevelPatch} from 'sanity-translations-tab'
+import {findLatestDraft} from 'sanity-translations-tab'
+import {SerializedDocument} from 'sanity-naive-html-serializer'
+import {TranslationFunctionContext} from 'sanity-translations-tab'
+import {TranslationsTab} from 'sanity-translations-tab'
+
+export {BaseDocumentDeserializer}
+
+export {BaseDocumentMerger}
+
+export {BaseDocumentSerializer}
+
+declare interface ConfigOptions {
+  adapter: Adapter
+  secretsNamespace: string | null
+  exportForTranslation: (
+    id: string,
+    context: TranslationFunctionContext
+  ) => Promise<SerializedDocument>
+  importTranslation: (
+    id: string,
+    localeId: string,
+    doc: string,
+    context: TranslationFunctionContext
+  ) => Promise<void>
+}
+
+export {customSerializers}
+
+export declare const defaultDocumentLevelConfig: ConfigOptions
+
+export declare const defaultFieldLevelConfig: ConfigOptions
+
+export {defaultStopTypes}
+
+export {documentLevelPatch}
+
+export {fieldLevelPatch}
+
+export {findLatestDraft}
+
+export declare const SmartlingAdapter: Adapter
+
+export {TranslationsTab}
+
+export {}