@roxxel/payload-multilang 0.0.4 → 0.0.6

package/dist/translations.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/translations.ts"],"sourcesContent":["export const payloadMultilangTranslations = {\n  en: {\n    payloadMultilang: {\n      allLanguages: 'All languages',\n      chooseLanguage: 'Choose language',\n      chooseTargetLanguage: 'Choose a target language.',\n      connectExisting: 'Connect existing',\n      createOrConnectDocuments: 'Create or connect separate localized documents.',\n      createTranslation: 'Create translation',\n      createTranslationFor: 'Create {{language}} translation',\n      current: 'Current',\n      disconnectDocument: 'Disconnect this document',\n      documentID: 'Document ID',\n      editTranslationFor: 'Edit {{language}} translation',\n      existingDocumentID: 'Existing document ID',\n      language: 'Language',\n      linkedDocuments: 'Linked documents',\n      localized: 'Localized',\n      localizedContent: 'Localized content',\n      missing: 'Missing',\n      saveBeforeAddingTranslations: 'Save before adding translations.',\n      saveBeforeCreatingTranslations: 'Save the document before creating translations.',\n      saveBeforeManagingTranslations: 'Save the document before managing translations.',\n      targetIDAndLanguageRequired: 'Target ID and language are required.',\n      translationActions: 'Translation actions',\n      translationConnected: 'Translation connected.',\n      translationCouldNotBeConnected: 'Translation could not be connected.',\n      translationCouldNotBeCreated: 'Translation could not be created.',\n      translationCouldNotBeDisconnected: 'Translation could not be disconnected.',\n      translationDisconnected: 'Translation disconnected.',\n      translations: 'Translations',\n      unassigned: 'Unassigned',\n      unassignedStoredLanguageNotConfigured:\n        'Unassigned; stored language \"{{language}}\" is not configured',\n    },\n  },\n  uk: {\n    payloadMultilang: {\n      allLanguages: 'Усі мови',\n      chooseLanguage: 'Оберіть мову',\n      chooseTargetLanguage: 'Оберіть цільову мову.',\n      connectExisting: 'Підключити наявний',\n      createOrConnectDocuments: 'Створюйте або підключайте окремі локалізовані документи.',\n      createTranslation: 'Створити переклад',\n      createTranslationFor: 'Створити переклад: {{language}}',\n      current: 'Поточний',\n      disconnectDocument: 'Від’єднати цей документ',\n      documentID: 'ID документа',\n      editTranslationFor: 'Редагувати переклад: {{language}}',\n      existingDocumentID: 'ID наявного документа',\n      language: 'Мова',\n      linkedDocuments: 'Пов’язані документи',\n      localized: 'Локалізовано',\n      localizedContent: 'Локалізований вміст',\n      missing: 'Відсутній',\n      saveBeforeAddingTranslations: 'Збережіть перед додаванням перекладів.',\n      saveBeforeCreatingTranslations: 'Збережіть документ перед створенням перекладів.',\n      saveBeforeManagingTranslations: 'Збережіть документ перед керуванням перекладами.',\n      targetIDAndLanguageRequired: 'Потрібні ID цільового документа та мова.',\n      translationActions: 'Дії з перекладами',\n      translationConnected: 'Переклад підключено.',\n      translationCouldNotBeConnected: 'Не вдалося підключити переклад.',\n      translationCouldNotBeCreated: 'Не вдалося створити переклад.',\n      translationCouldNotBeDisconnected: 'Не вдалося від’єднати переклад.',\n      translationDisconnected: 'Переклад від’єднано.',\n      translations: 'Переклади',\n      unassigned: 'Не призначено',\n      unassignedStoredLanguageNotConfigured:\n        'Не призначено; збережена мова \"{{language}}\" не налаштована',\n    },\n  },\n} as const\n\nexport type PayloadMultilangTranslations =\n  (typeof payloadMultilangTranslations)['en']\n\nexport type PayloadMultilangTranslationKey =\n  `payloadMultilang:${keyof PayloadMultilangTranslations['payloadMultilang']}`\n"],"names":["payloadMultilangTranslations","en","payloadMultilang","allLanguages","chooseLanguage","chooseTargetLanguage","connectExisting","createOrConnectDocuments","createTranslation","createTranslationFor","current","disconnectDocument","documentID","editTranslationFor","existingDocumentID","language","linkedDocuments","localized","localizedContent","missing","saveBeforeAddingTranslations","saveBeforeCreatingTranslations","saveBeforeManagingTranslations","targetIDAndLanguageRequired","translationActions","translationConnected","translationCouldNotBeConnected","translationCouldNotBeCreated","translationCouldNotBeDisconnected","translationDisconnected","translations","unassigned","unassignedStoredLanguageNotConfigured","uk"],"mappings":"AAAA,OAAO,MAAMA,+BAA+B;IAC1CC,IAAI;QACFC,kBAAkB;YAChBC,cAAc;YACdC,gBAAgB;YAChBC,sBAAsB;YACtBC,iBAAiB;YACjBC,0BAA0B;YAC1BC,mBAAmB;YACnBC,sBAAsB;YACtBC,SAAS;YACTC,oBAAoB;YACpBC,YAAY;YACZC,oBAAoB;YACpBC,oBAAoB;YACpBC,UAAU;YACVC,iBAAiB;YACjBC,WAAW;YACXC,kBAAkB;YAClBC,SAAS;YACTC,8BAA8B;YAC9BC,gCAAgC;YAChCC,gCAAgC;YAChCC,6BAA6B;YAC7BC,oBAAoB;YACpBC,sBAAsB;YACtBC,gCAAgC;YAChCC,8BAA8B;YAC9BC,mCAAmC;YACnCC,yBAAyB;YACzBC,cAAc;YACdC,YAAY;YACZC,uCACE;QACJ;IACF;IACAC,IAAI;QACF/B,kBAAkB;YAChBC,cAAc;YACdC,gBAAgB;YAChBC,sBAAsB;YACtBC,iBAAiB;YACjBC,0BAA0B;YAC1BC,mBAAmB;YACnBC,sBAAsB;YACtBC,SAAS;YACTC,oBAAoB;YACpBC,YAAY;YACZC,oBAAoB;YACpBC,oBAAoB;YACpBC,UAAU;YACVC,iBAAiB;YACjBC,WAAW;YACXC,kBAAkB;YAClBC,SAAS;YACTC,8BAA8B;YAC9BC,gCAAgC;YAChCC,gCAAgC;YAChCC,6BAA6B;YAC7BC,oBAAoB;YACpBC,sBAAsB;YACtBC,gCAAgC;YAChCC,8BAA8B;YAC9BC,mCAAmC;YACnCC,yBAAyB;YACzBC,cAAc;YACdC,YAAY;YACZC,uCACE;QACJ;IACF;AACF,EAAU"}

package/dist/types.d.ts

@@ -17,22 +17,10 @@ export type MultilangLanguage = {
     order?: number;
 };
 export type MultilangCollectionOptions = {
-    /**
-     * Set to false to create empty translation documents by default.
-     */
-    duplicate?: boolean;
-    /**
-     * Additional top-level document field names that should not be copied when creating a translation.
-     */
-    duplicateExcludeFields?: string[];
     /**
      * Override hidden metadata field names for this collection.
      */
     fields?: Partial<MultilangFieldNames>;
-    /**
-     * Top-level document field names that should share one value across every language in a translation group.
-     */
-    synchronizedFields?: string[];
 };
 export type MultilangGlobalOptions = {
     /**
@@ -49,10 +37,6 @@ export type PayloadMultilangConfig = {
      * Disable runtime UI/endpoints/hooks while keeping schema fields in place.
      */
     disabled?: boolean;
-    /**
-     * Global duplicate exclusions applied to all enabled collections.
-     */
-    duplicateExcludeFields?: string[];
     /**
      * Global hidden metadata field name overrides.
      */
@@ -69,12 +53,9 @@ export type PayloadMultilangConfig = {
 };
 export type ResolvedMultilangCollection = {
     defaultLanguage: MultilangLanguage;
-    duplicate: boolean;
-    duplicateExcludeFields: string[];
     fieldNames: MultilangFieldNames;
     languages: MultilangLanguage[];
     slug: string;
-    synchronizedFields: string[];
 };
 export type ResolvedMultilangGlobal = {
     defaultLanguage: MultilangLanguage;

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/types.ts"],"sourcesContent":["import type { CollectionSlug, GlobalSlug, Where } from 'payload'\n\nexport type MultilangDirection = 'ltr' | 'rtl'\n\nexport type MultilangFieldNames = {\n  group: string\n  language: string\n  meta: string\n}\n\nexport type MultilangLanguage = {\n  active?: boolean\n  code: string\n  direction?: MultilangDirection\n  flagLabel?: string\n  id?: number | string\n  isDefault?: boolean\n  locale?: string\n  name: string\n  order?: number\n}\n\nexport type MultilangCollectionOptions = {\n  /**\n   * Set to false to create empty translation documents by default.\n   */\n  duplicate?: boolean\n  /**\n   * Additional top-level document field names that should not be copied when creating a translation.\n   */\n  duplicateExcludeFields?: string[]\n  /**\n   * Override hidden metadata field names for this collection.\n   */\n  fields?: Partial<MultilangFieldNames>\n  /**\n   * Top-level document field names that should share one value across every language in a translation group.\n   */\n  synchronizedFields?: string[]\n}\n\nexport type MultilangGlobalOptions = {\n  /**\n   * Override the top-level tabs field label used to group localized global fields.\n   */\n  label?: string\n}\n\nexport type PayloadMultilangConfig = {\n  /**\n   * Payload collections that should use Polylang-style document translations.\n   */\n  collections?: Partial<Record<CollectionSlug, MultilangCollectionOptions | true>>\n  /**\n   * Disable runtime UI/endpoints/hooks while keeping schema fields in place.\n   */\n  disabled?: boolean\n  /**\n   * Global duplicate exclusions applied to all enabled collections.\n   */\n  duplicateExcludeFields?: string[]\n  /**\n   * Global hidden metadata field name overrides.\n   */\n  fieldNames?: Partial<MultilangFieldNames>\n  /**\n   * Payload globals that should store language-specific values in one singleton document.\n   */\n  globals?: Partial<Record<GlobalSlug, MultilangGlobalOptions | true>>\n  /**\n   * Languages available to translated collections. Codes are normalized to\n   * lowercase during plugin setup.\n   */\n  languages: MultilangLanguage[]\n}\n\nexport type ResolvedMultilangCollection = {\n  defaultLanguage: MultilangLanguage\n  duplicate: boolean\n  duplicateExcludeFields: string[]\n  fieldNames: MultilangFieldNames\n  languages: MultilangLanguage[]\n  slug: string\n  synchronizedFields: string[]\n}\n\nexport type ResolvedMultilangGlobal = {\n  defaultLanguage: MultilangLanguage\n  label: string\n  languages: MultilangLanguage[]\n  slug: string\n}\n\nexport type TranslationMap<TDoc = Record<string, unknown>> = Record<string, TDoc>\n\nexport type TranslationState<TDoc = Record<string, unknown>> = {\n  group?: string\n  language?: string\n  source?: TDoc\n  translations: TranslationMap<TDoc>\n}\n\nexport type WithLanguageArgs = {\n  fieldName?: string\n  language: string\n  where?: Where\n}\n"],"names":[],"mappings":"AAsGA,WAIC"}
+{"version":3,"sources":["../src/types.ts"],"sourcesContent":["import type { CollectionSlug, GlobalSlug, Where } from 'payload'\n\nexport type MultilangDirection = 'ltr' | 'rtl'\n\nexport type MultilangFieldNames = {\n  group: string\n  language: string\n  meta: string\n}\n\nexport type MultilangLanguage = {\n  active?: boolean\n  code: string\n  direction?: MultilangDirection\n  flagLabel?: string\n  id?: number | string\n  isDefault?: boolean\n  locale?: string\n  name: string\n  order?: number\n}\n\nexport type MultilangCollectionOptions = {\n  /**\n   * Override hidden metadata field names for this collection.\n   */\n  fields?: Partial<MultilangFieldNames>\n}\n\nexport type MultilangGlobalOptions = {\n  /**\n   * Override the top-level tabs field label used to group localized global fields.\n   */\n  label?: string\n}\n\nexport type PayloadMultilangConfig = {\n  /**\n   * Payload collections that should use Polylang-style document translations.\n   */\n  collections?: Partial<Record<CollectionSlug, MultilangCollectionOptions | true>>\n  /**\n   * Disable runtime UI/endpoints/hooks while keeping schema fields in place.\n   */\n  disabled?: boolean\n  /**\n   * Global hidden metadata field name overrides.\n   */\n  fieldNames?: Partial<MultilangFieldNames>\n  /**\n   * Payload globals that should store language-specific values in one singleton document.\n   */\n  globals?: Partial<Record<GlobalSlug, MultilangGlobalOptions | true>>\n  /**\n   * Languages available to translated collections. Codes are normalized to\n   * lowercase during plugin setup.\n   */\n  languages: MultilangLanguage[]\n}\n\nexport type ResolvedMultilangCollection = {\n  defaultLanguage: MultilangLanguage\n  fieldNames: MultilangFieldNames\n  languages: MultilangLanguage[]\n  slug: string\n}\n\nexport type ResolvedMultilangGlobal = {\n  defaultLanguage: MultilangLanguage\n  label: string\n  languages: MultilangLanguage[]\n  slug: string\n}\n\nexport type TranslationMap<TDoc = Record<string, unknown>> = Record<string, TDoc>\n\nexport type TranslationState<TDoc = Record<string, unknown>> = {\n  group?: string\n  language?: string\n  source?: TDoc\n  translations: TranslationMap<TDoc>\n}\n\nexport type WithLanguageArgs = {\n  fieldName?: string\n  language: string\n  where?: Where\n}\n"],"names":[],"mappings":"AAmFA,WAIC"}

package/docs/configuration.md

@@ -32,6 +32,8 @@ export default buildConfig({
 })
 ```
 
+Payload built-in localization must stay disabled. This plugin models translations as separate documents linked by metadata fields, so `localized: true` fields are not the intended model. If `config.localization` is enabled, `payloadMultilang()` throws during config setup.
+
 ## Plugin Options
 
 | Option                   | Type                                                 | Description                                                                                                            |
@@ -40,9 +42,47 @@ export default buildConfig({
 | `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
+
+Translated collection entries are independent Payload documents. The plugin adds hidden metadata fields:
+
+```ts
+{
+  language: '_multilangLanguage',
+  group: '_multilangGroup',
+  meta: '_multilangMeta',
+}
+```
+
+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
@@ -101,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,
 })
@@ -113,10 +149,24 @@ 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,
+    },
+  },
+}
+```
+
+For repeatable fields with child fields, such as `array` and `blocks`, synchronization only applies to the outer shell. Item IDs, order, block types, and block names follow the source document, while each translation keeps its own nested field values.
 
 ## Globals
 
@@ -144,7 +194,7 @@ payloadMultilang({
 })
 ```
 
-Read and update localized global values with `findGlobalByLanguage` and `updateGlobalByLanguage`.
+Read and update localized global values with `findGlobalByLanguageWithPayload`, `updateGlobalByLanguageWithPayload`, or helpers from `createMultilangHelpers()`.
 
 ## Custom Field Names
 
@@ -190,3 +240,18 @@ payloadMultilang({
 ```
 
 When using custom field names, pass the same names to helpers that accept `fieldNames` or `fieldName`.
+
+## Slug Uniqueness
+
+Because translations are separate documents, decide whether slugs are unique globally or per language.
+
+If every translated document has a different slug, a normal `unique: true` slug field works. If translations may share the same slug across languages, do not use global `unique: true`; enforce uniqueness with a compound database index or a custom validation rule scoped to:
+
+```ts
+{
+  _multilangLanguage: language,
+  slug,
+}
+```
+
+Use `localizedSlugQuery()` for common language + slug lookups in frontend routes.

package/docs/helpers.md

@@ -2,33 +2,52 @@
 
 Import helpers from `@roxxel/payload-multilang`.
 
+## Request-Scoped Helpers
+
+Use `WithPayload` helpers in endpoints, hooks, route handlers, and code running on behalf of a user.
+
 ```ts
 import {
-  findGlobalByLanguage,
   findGlobalByLanguageWithPayload,
-  getDocumentTranslation,
-  getDocumentTranslations,
-  getLanguages,
-  updateGlobalByLanguage,
+  getDocumentTranslationWithPayload,
+  getDocumentTranslationsWithPayload,
+  getGroupTranslationsWithPayload,
   updateGlobalByLanguageWithPayload,
-  withLanguage,
 } from '@roxxel/payload-multilang'
+
+const state = await getDocumentTranslationsWithPayload({
+  collection: 'posts',
+  id: post.id,
+  payload: req.payload,
+  req,
+  overrideAccess: false,
+})
 ```
 
-## `getLanguages`
+`overrideAccess` defaults to `true`, matching Payload Local API defaults. Set it to `false` and pass `req` when enforcing request user access.
+
+## `createMultilangHelpers`
 
-Returns the languages configured for the plugin.
+Use a tiny app-owned module for convenience helpers.
 
 ```ts
-const languages = await getLanguages()
+import { createMultilangHelpers } from '@roxxel/payload-multilang'
+import { getPayload } from 'payload'
+import config from '@payload-config'
+
+export const multilang = createMultilangHelpers({
+  getPayload: () => getPayload({ config }),
+})
 ```
 
-You can also pass known languages or a Payload config-like object.
+The factory returns:
 
 ```ts
-const languages = await getLanguages({
-  config: payload.config,
-})
+multilang.getLanguages()
+multilang.getDocumentTranslations(args)
+multilang.getDocumentTranslation(args)
+multilang.findGlobalByLanguage(args)
+multilang.updateGlobalByLanguage(args)
 ```
 
 ## `withLanguage`
@@ -36,6 +55,8 @@ const languages = await getLanguages({
 Adds a language constraint to a Payload `where` query.
 
 ```ts
+import { withLanguage } from '@roxxel/payload-multilang'
+
 const where = withLanguage({
   language: 'uk',
   where: {
@@ -65,37 +86,31 @@ Result:
 }
 ```
 
-Signature:
-
-```ts
-withLanguage(args: {
-  fieldName?: string
-  language: string
-  where?: Where
-}): Where
-```
-
 Use `fieldName` if you configured a custom collection language field.
 
-## `getDocumentTranslations`
+## Document Helpers
 
-Returns the source document and all linked translations for a localized collection document.
+`getDocumentTranslationsWithPayload` returns the source document and all linked translations for a localized collection document.
 
 ```ts
-const state = await getDocumentTranslations<Post>({
+const state = await getDocumentTranslationsWithPayload<Post>({
   collection: 'posts',
   id: post.id,
+  payload: req.payload,
+  req,
+  overrideAccess: false,
 })
 ```
 
-Signature:
+`getDocumentTranslationWithPayload` returns one target-language document.
 
 ```ts
-getDocumentTranslations<TDoc>(args: {
-  collection: CollectionSlug
-  fieldNames?: MultilangFieldNames
-  id: number | string
-}): Promise<TranslationState<TDoc>>
+const ukrainianPost = await getDocumentTranslationWithPayload<Post>({
+  collection: 'posts',
+  id: post.id,
+  language: 'uk',
+  payload: req.payload,
+})
 ```
 
 Return shape:
@@ -109,123 +124,82 @@ type TranslationState<TDoc = Record<string, unknown>> = {
 }
 ```
 
-## `getDocumentTranslation`
+## Global Helpers
 
-Returns one target-language document from the source document's translation group.
+Localized globals store one singleton document with one top-level tab per language. These helpers read or update one tab and return flat data for that language.
 
 ```ts
-const ukrainianPost = await getDocumentTranslation<Post>({
-  collection: 'posts',
-  id: post.id,
+const settings = await findGlobalByLanguageWithPayload<SiteSettings>({
+  slug: 'site-settings',
   language: 'uk',
+  payload: req.payload,
+  req,
+  overrideAccess: false,
 })
-```
-
-Signature:
-
-```ts
-getDocumentTranslation<TDoc>(args: {
-  collection: CollectionSlug
-  fieldNames?: MultilangFieldNames
-  id: number | string
-  language: string
-}): Promise<TDoc | undefined>
-```
-
-## `findGlobalByLanguage`
-
-Reads one language from a localized global and returns flat data for that language.
 
-```ts
-const settings = await findGlobalByLanguage<SiteSettings>({
+await updateGlobalByLanguageWithPayload<SiteSettings>({
   slug: 'site-settings',
   language: 'uk',
+  payload: req.payload,
+  data: {
+    title: 'Updated title',
+  },
 })
 ```
 
-Signature:
-
-```ts
-findGlobalByLanguage<TDoc>(args: {
-  depth?: number
-  language: string
-  slug: GlobalSlug
-}): Promise<TDoc>
-```
-
-## `updateGlobalByLanguage`
+## Constants
 
-Updates one language in a localized global.
+Default metadata field names are exported so apps do not need to hardcode them.
 
 ```ts
-const settings = await updateGlobalByLanguage<SiteSettings>({
-  slug: 'site-settings',
-  language: 'uk',
-  data: {
-    title: 'Ukrainian title',
-  },
-})
+import {
+  DEFAULT_FIELD_NAMES,
+  MULTILANG_GROUP_FIELD,
+  MULTILANG_LANGUAGE_FIELD,
+  MULTILANG_META_FIELD,
+} from '@roxxel/payload-multilang'
 ```
 
-Signature:
+Values:
 
 ```ts
-updateGlobalByLanguage<TDoc>(args: {
-  data: Record<string, unknown>
-  depth?: number
-  language: string
-  slug: GlobalSlug
-}): Promise<TDoc>
+{
+  language: '_multilangLanguage',
+  group: '_multilangGroup',
+  meta: '_multilangMeta',
+}
 ```
 
-The helper merges `data` into the selected language and preserves existing values in other languages.
-
-## Global Helpers With Payload
+## Preview Language Helper
 
-Use these variants when you already have a Payload instance or need request-aware access control.
+Use `getMultilangDocumentLanguage` in admin preview or livePreview URL builders. It checks unsaved form data first, then the persisted document.
 
 ```ts
-const settings = await findGlobalByLanguageWithPayload<SiteSettings>({
-  slug: 'site-settings',
-  language: 'uk',
-  overrideAccess: false,
-  payload: req.payload,
-  req,
-})
+import { getMultilangDocumentLanguage } from '@roxxel/payload-multilang'
 
-await updateGlobalByLanguageWithPayload<SiteSettings>({
-  slug: 'site-settings',
-  language: 'uk',
-  data: {
-    title: 'Updated title',
-  },
-  overrideAccess: false,
-  payload: req.payload,
-  req,
+const language = getMultilangDocumentLanguage({
+  data,
+  doc,
+  fallback: 'en',
 })
 ```
 
-Signatures:
+## Localized Slug Query
+
+`localizedSlugQuery` builds the common Local API query for language + slug + status.
 
 ```ts
-findGlobalByLanguageWithPayload<TDoc>(args: {
-  depth?: number
-  language: string
-  overrideAccess?: boolean
-  payload: Payload
-  req?: PayloadRequest
-  slug: GlobalSlug
-}): Promise<TDoc>
-
-updateGlobalByLanguageWithPayload<TDoc>(args: {
-  data: Record<string, unknown>
-  depth?: number
-  language: string
-  overrideAccess?: boolean
-  payload: Payload
-  req?: PayloadRequest
-  slug: GlobalSlug
-}): Promise<TDoc>
+import { localizedSlugQuery } from '@roxxel/payload-multilang'
+
+const { docs } = await payload.find({
+  collection: 'posts',
+  limit: 1,
+  ...localizedSlugQuery({
+    slug,
+    language: 'uk',
+    status: 'published',
+  }),
+})
 ```
 
-`overrideAccess` defaults to `true`. Set it to `false` when operating on behalf of a user.
+Use `status: 'draft'` to include `draft: true` and `_status = draft`, or `status: 'any'` to omit `_status`.