@roxxel/payload-multilang 0.0.4 → 0.0.6

package/docs/usage.md

@@ -27,14 +27,69 @@ 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.
 
+## 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.
+
+```ts
+// src/lib/multilang.ts
+import { createMultilangHelpers } from '@roxxel/payload-multilang'
+import { getPayload } from 'payload'
+import config from '@payload-config'
+
+export const multilang = createMultilangHelpers({
+  getPayload: () => getPayload({ config }),
+})
+```
+
+Then use it from your app:
+
+```tsx
+import { multilang } from '@/lib/multilang'
+
+export const LanguageSwitcher = async ({ id }: { id: string }) => {
+  const state = await multilang.getDocumentTranslations<{ id: string; slug?: string }>({
+    collection: 'posts',
+    id,
+  })
+
+  return (
+    <nav>
+      {Object.entries(state.translations).map(([language, doc]) => (
+        <a href={`/${language}/posts/${doc.slug || doc.id}`} key={language}>
+          {language.toUpperCase()}
+        </a>
+      ))}
+    </nav>
+  )
+}
+```
+
+## Request-Scoped Code
+
+Use `WithPayload` helpers when you already have `req.payload` or need user-scoped access control.
+
+```ts
+import { getDocumentTranslationsWithPayload } from '@roxxel/payload-multilang'
+
+export const getPostTranslations = async (req: PayloadRequest, id: string) =>
+  getDocumentTranslationsWithPayload({
+    collection: 'posts',
+    id,
+    payload: req.payload,
+    req,
+    overrideAccess: false,
+  })
+```
+
 ## Query Documents for One Language
 
 Use `withLanguage()` with the Local API.
 
 ```ts
+import { withLanguage } from '@roxxel/payload-multilang'
 import { getPayload } from 'payload'
 import config from '@payload-config'
-import { withLanguage } from '@roxxel/payload-multilang'
 
 export const getPosts = async (language: string) => {
   const payload = await getPayload({ config })
@@ -73,62 +128,64 @@ const where = withLanguage({
 })
 ```
 
-## Get Translations for a Document
+## Localized Slug Lookups
 
-Use `getDocumentTranslations()` when you have a document ID and need every linked translation.
+Use `localizedSlugQuery()` for the common language + slug + status lookup.
 
 ```ts
-import { getDocumentTranslations } from '@roxxel/payload-multilang'
+import { localizedSlugQuery } from '@roxxel/payload-multilang'
 
-const state = await getDocumentTranslations({
+const { docs } = await payload.find({
   collection: 'posts',
-  id: post.id,
+  limit: 1,
+  ...localizedSlugQuery({
+    slug: 'hello-world',
+    language: 'uk',
+    status: 'published',
+  }),
 })
-
-const english = state.translations.en
-const ukrainian = state.translations.uk
-```
-
-The returned object is keyed by language code:
-
-```ts
-type TranslationState<TDoc> = {
-  group?: string
-  language?: string
-  source?: TDoc
-  translations: Record<string, TDoc>
-}
 ```
 
-Use `getDocumentTranslation()` when you only need one target language.
+For draft previews:
 
 ```ts
-import { getDocumentTranslation } from '@roxxel/payload-multilang'
+const query = localizedSlugQuery({
+  slug,
+  language,
+  status: 'draft',
+})
 
-const ukrainianPost = await getDocumentTranslation({
+await payload.find({
   collection: 'posts',
-  id: post.id,
-  language: 'uk',
+  limit: 1,
+  ...query,
 })
 ```
 
-## Access Control in Server Code
+## Admin Preview URLs
 
-The document translation helpers resolve Payload from `@payload-config` and use the default Local API access behavior. When you need user-scoped collection reads, query with Payload directly and pass `overrideAccess: false`.
+Use `getMultilangDocumentLanguage()` to derive the selected language from unsaved form data first, then the saved document.
 
 ```ts
-const { docs } = await req.payload.find({
-  collection: 'posts',
-  overrideAccess: false,
-  req,
-  where: withLanguage({
-    language: 'uk',
-  }),
-})
+import { getMultilangDocumentLanguage } from '@roxxel/payload-multilang'
+
+export const Posts = {
+  slug: 'posts',
+  admin: {
+    preview: ({ data, doc }) => {
+      const language = getMultilangDocumentLanguage({
+        data,
+        doc,
+        fallback: 'en',
+      })
+
+      return `/${language}/posts/${data?.slug || doc?.slug}`
+    },
+  },
+  fields: [],
+}
 ```
 
-Use the global `WithPayload` helpers when you need request-aware access control for localized globals.
-
 ## Enable a Global
 
 Add the global slug to the plugin config.
@@ -142,30 +199,12 @@ payloadMultilang({
 })
 ```
 
-Then read one language as flat data:
-
-```ts
-import { findGlobalByLanguage } from '@roxxel/payload-multilang'
-
-const settings = await findGlobalByLanguage({
-  slug: 'site-settings',
-  language: 'uk',
-})
-
-console.log(settings.title)
-```
-
-Update one language without replacing other language values:
+Read one language as flat data:
 
 ```ts
-import { updateGlobalByLanguage } from '@roxxel/payload-multilang'
-
-await updateGlobalByLanguage({
+const settings = await multilang.findGlobalByLanguage({
   slug: 'site-settings',
   language: 'uk',
-  data: {
-    title: 'Ukrainian title',
-  },
 })
 ```
 
@@ -177,88 +216,44 @@ import { findGlobalByLanguageWithPayload } from '@roxxel/payload-multilang'
 const settings = await findGlobalByLanguageWithPayload({
   slug: 'site-settings',
   language: 'uk',
-  overrideAccess: false,
   payload: req.payload,
   req,
+  overrideAccess: false,
 })
 ```
 
-## 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.
+Update one language without replacing other language values:
 
 ```ts
-payloadMultilang({
-  collections: {
-    posts: {
-      synchronizedFields: ['featuredImage', 'author', 'category'],
-    },
+await multilang.updateGlobalByLanguage({
+  slug: 'site-settings',
+  language: 'uk',
+  data: {
+    title: 'Ukrainian title',
   },
-  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:
-
-```ts
-payloadMultilang({
-  collections: {
-    posts: {
-      duplicate: false,
-    },
-  },
-  languages,
-})
-```
+## Keep Shared Fields in Sync
 
-To duplicate most fields but exclude specific ones:
+Set `custom.multilang.synchronize` on top-level fields that should be identical across translations, such as author, featured image, or canonical taxonomy.
 
 ```ts
-payloadMultilang({
-  collections: {
-    posts: {
-      duplicateExcludeFields: ['slug', 'seoTitle', 'seoDescription'],
+{
+  name: 'featuredImage',
+  type: 'upload',
+  relationTo: 'media',
+  custom: {
+    multilang: {
+      synchronize: true,
     },
   },
-  languages,
-})
-```
-
-## Build Language Switchers
-
-Use `getDocumentTranslations()` to render links to available translations.
-
-```tsx
-import { getDocumentTranslations } from '@roxxel/payload-multilang'
-
-export const LanguageSwitcher = async ({ collection, id }: { collection: 'posts'; id: string }) => {
-  type PostLink = {
-    id?: number | string
-    slug?: string
-  }
-
-  const state = await getDocumentTranslations<PostLink>({
-    collection,
-    id,
-  })
-
-  return (
-    <nav>
-      {Object.entries(state.translations).map(([language, doc]) => (
-        <a href={`/${language}/posts/${doc.slug || doc.id}`} key={language}>
-          {language.toUpperCase()}
-        </a>
-      ))}
-    </nav>
-  )
 }
 ```
 
-Adjust the URL shape to match your frontend routing.
+When an editor changes one of those fields on a saved translation, the plugin updates the same field on the other linked translations.
+
+For `array` and `blocks` fields, synchronization keeps the outer shell aligned only. The row IDs, order, block types, and block names sync across translations, but nested field values inside each row or block stay language-specific.
 
 ## Generate Types
 

package/package.json

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

package/dist/payload-config.d.js

@@ -1,2 +0,0 @@
-
-//# sourceMappingURL=payload-config.d.js.map

package/dist/payload-config.d.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/payload-config.d.ts"],"names":[],"mappings":""}