@roxxel/payload-multilang 0.0.5 → 0.0.7

package/docs/configuration.md

@@ -42,7 +42,6 @@ Payload built-in localization must stay disabled. This plugin models translation
 | `collections`            | `Record<string, true \| MultilangCollectionOptions>` | Collection slugs to localize.                                                                                          |
 | `globals`                | `Record<string, true \| MultilangGlobalOptions>`     | Global slugs to localize.                                                                                              |
 | `fieldNames`             | `Partial<MultilangFieldNames>`                       | Optional custom field names used by localized collections.                                                             |
-| `duplicateExcludeFields` | `string[]`                                           | Extra top-level fields to skip when a new translation duplicates source document data.                                 |
 | `disabled`               | `boolean`                                            | Returns the Payload config unchanged when true. Useful for temporary opt-out in specific environments.                 |
 
 ## Content Model
@@ -59,6 +58,31 @@ Translated collection entries are independent Payload documents. The plugin adds
 
 Do not mark content fields as `localized: true` for this plugin model. Put translated text directly on each language document instead.
 
+## Admin UI Translations
+
+The plugin registers its own admin UI translations for English (`en`) and Ukrainian (`uk`) through Payload `i18n.translations`.
+
+Apps can override any plugin string by setting the same translation keys after installing the plugin:
+
+```ts
+export default buildConfig({
+  i18n: {
+    translations: {
+      uk: {
+        payloadMultilang: {
+          translations: 'Переклади',
+        },
+      },
+    },
+  },
+  plugins: [
+    payloadMultilang({
+      languages,
+    }),
+  ],
+})
+```
+
 ## Languages
 
 ```ts
@@ -117,11 +141,7 @@ Use collection options when you need custom translation behavior.
 ```ts
 payloadMultilang({
   collections: {
-    posts: {
-      duplicate: true,
-      duplicateExcludeFields: ['legacyId'],
-      synchronizedFields: ['featuredImage', 'author'],
-    },
+    posts: true,
   },
   languages,
 })
@@ -129,10 +149,32 @@ payloadMultilang({
 
 | Option                   | Type                           | Description                                                                                                                                                          |
 | ------------------------ | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `duplicate`              | `boolean`                      | Defaults to `true`. When creating a translation, copy source document fields into the new document. Set to `false` to create empty translation documents by default. |
-| `duplicateExcludeFields` | `string[]`                     | Additional top-level fields to skip during duplication for this collection.                                                                                          |
 | `fields`                 | `Partial<MultilangFieldNames>` | Override metadata field names for this collection.                                                                                                                   |
-| `synchronizedFields`     | `string[]`                     | Top-level fields that should stay the same across all translations in a group.                                                                                       |
+
+Mark fields that should stay shared across translations directly in the field config:
+
+```ts
+{
+  name: 'featuredImage',
+  type: 'upload',
+  relationTo: 'media',
+  custom: {
+    multilang: {
+      synchronize: true,
+    },
+  },
+}
+```
+
+`custom.multilang.synchronize: true` can be set on any data field. Scalar fields copy their value to every translation. Container fields are traversed recursively:
+
+- `group` synchronizes every child field recursively.
+- `array` and `blocks` synchronize their row or block shell and every child field recursively.
+- `tabs` are not synchronized as values, but fields inside tabs are traversed and can synchronize normally.
+
+Use `custom.multilang.synchronizePosition: true` on `array` or `blocks` when only the outer shell should follow the source document. This synchronizes row or block order, plus block type and block name for blocks, while preserving each translation's nested field values.
+
+If a container is not marked but a descendant field is marked with `synchronize: true`, existing rows or blocks are matched without changing translation-local row order or membership.
 
 ## Globals
 

package/docs/usage.md

@@ -27,6 +27,12 @@ payloadMultilang({
 
 Editors can then choose the document language in the sidebar and create or connect translations from the collection list, document sidebar, or `Translations` edit tab.
 
+## Synchronized Fields
+
+Mark shared fields with `custom.multilang.synchronize: true`. For `group`, `array`, and `blocks`, this synchronizes nested values recursively. `tabs` are only traversed; fields inside tabs can still opt in.
+
+Use `custom.multilang.synchronizePosition: true` on `array` or `blocks` to synchronize only the repeatable shell, preserving localized values inside each row or block.
+
 ## App-Level Convenience Helpers
 
 Create one app-owned helper module when you want short helper calls in RSCs, route handlers, or other trusted server code.
@@ -236,48 +242,24 @@ await multilang.updateGlobalByLanguage({
 
 ## Keep Shared Fields in Sync
 
-Use `synchronizedFields` for top-level fields that should be identical across translations, such as author, featured image, or canonical taxonomy.
-
-```ts
-payloadMultilang({
-  collections: {
-    posts: {
-      synchronizedFields: ['featuredImage', 'author', 'category'],
-    },
-  },
-  languages,
-})
-```
-
-When an editor changes one of those fields on a saved translation, the plugin updates the same field on the other linked translations.
-
-## Create Empty Translations
-
-By default, creating a translation duplicates compatible top-level source fields. To make new translations start empty:
+Set `custom.multilang.synchronize` on fields that should be identical across translations, such as author, featured image, canonical taxonomy, or a whole nested group.
 
 ```ts
-payloadMultilang({
-  collections: {
-    posts: {
-      duplicate: false,
+{
+  name: 'featuredImage',
+  type: 'upload',
+  relationTo: 'media',
+  custom: {
+    multilang: {
+      synchronize: true,
     },
   },
-  languages,
-})
+}
 ```
 
-To duplicate most fields but exclude specific ones:
+When an editor changes one of those fields on a saved translation, the plugin updates the same field on the other linked translations. For `group`, `array`, and `blocks`, `synchronize: true` applies recursively to nested fields.
 
-```ts
-payloadMultilang({
-  collections: {
-    posts: {
-      duplicateExcludeFields: ['slug', 'seoTitle', 'seoDescription'],
-    },
-  },
-  languages,
-})
-```
+Use `custom.multilang.synchronizePosition: true` on `array` or `blocks` to keep only the repeatable shell aligned while preserving localized values inside each row or block.
 
 ## Generate Types
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@roxxel/payload-multilang",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "description": "Polylang-style document localization for Payload CMS",
   "license": "MIT",
   "repository": {