@roxxel/payload-multilang 0.0.1

package/docs/helpers.md

@@ -0,0 +1,231 @@
+# Helper API
+
+Import helpers from `@roxxel/payload-multilang`.
+
+```ts
+import {
+  findGlobalByLanguage,
+  findGlobalByLanguageWithPayload,
+  getDocumentTranslation,
+  getDocumentTranslations,
+  getLanguages,
+  updateGlobalByLanguage,
+  updateGlobalByLanguageWithPayload,
+  withLanguage,
+} from '@roxxel/payload-multilang'
+```
+
+## `getLanguages`
+
+Returns the languages configured for the plugin.
+
+```ts
+const languages = await getLanguages()
+```
+
+You can also pass known languages or a Payload config-like object.
+
+```ts
+const languages = await getLanguages({
+  config: payload.config,
+})
+```
+
+## `withLanguage`
+
+Adds a language constraint to a Payload `where` query.
+
+```ts
+const where = withLanguage({
+  language: 'uk',
+  where: {
+    title: {
+      like: 'Hello',
+    },
+  },
+})
+```
+
+Result:
+
+```ts
+{
+  and: [
+    {
+      title: {
+        like: 'Hello',
+      },
+    },
+    {
+      _multilangLanguage: {
+        equals: 'uk',
+      },
+    },
+  ],
+}
+```
+
+Signature:
+
+```ts
+withLanguage(args: {
+  fieldName?: string
+  language: string
+  where?: Where
+}): Where
+```
+
+Use `fieldName` if you configured a custom collection language field.
+
+## `getDocumentTranslations`
+
+Returns the source document and all linked translations for a localized collection document.
+
+```ts
+const state = await getDocumentTranslations<Post>({
+  collection: 'posts',
+  id: post.id,
+})
+```
+
+Signature:
+
+```ts
+getDocumentTranslations<TDoc>(args: {
+  collection: CollectionSlug
+  fieldNames?: MultilangFieldNames
+  id: number | string
+}): Promise<TranslationState<TDoc>>
+```
+
+Return shape:
+
+```ts
+type TranslationState<TDoc = Record<string, unknown>> = {
+  group?: string
+  language?: string
+  source?: TDoc
+  translations: Record<string, TDoc>
+}
+```
+
+## `getDocumentTranslation`
+
+Returns one target-language document from the source document's translation group.
+
+```ts
+const ukrainianPost = await getDocumentTranslation<Post>({
+  collection: 'posts',
+  id: post.id,
+  language: 'uk',
+})
+```
+
+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>({
+  slug: 'site-settings',
+  language: 'uk',
+})
+```
+
+Signature:
+
+```ts
+findGlobalByLanguage<TDoc>(args: {
+  depth?: number
+  language: string
+  slug: GlobalSlug
+}): Promise<TDoc>
+```
+
+## `updateGlobalByLanguage`
+
+Updates one language in a localized global.
+
+```ts
+const settings = await updateGlobalByLanguage<SiteSettings>({
+  slug: 'site-settings',
+  language: 'uk',
+  data: {
+    title: 'Ukrainian title',
+  },
+})
+```
+
+Signature:
+
+```ts
+updateGlobalByLanguage<TDoc>(args: {
+  data: Record<string, unknown>
+  depth?: number
+  language: string
+  slug: GlobalSlug
+}): Promise<TDoc>
+```
+
+The helper merges `data` into the selected language and preserves existing values in other languages.
+
+## Global Helpers With Payload
+
+Use these variants when you already have a Payload instance or need request-aware access control.
+
+```ts
+const settings = await findGlobalByLanguageWithPayload<SiteSettings>({
+  slug: 'site-settings',
+  language: 'uk',
+  overrideAccess: false,
+  payload: req.payload,
+  req,
+})
+
+await updateGlobalByLanguageWithPayload<SiteSettings>({
+  slug: 'site-settings',
+  language: 'uk',
+  data: {
+    title: 'Updated title',
+  },
+  overrideAccess: false,
+  payload: req.payload,
+  req,
+})
+```
+
+Signatures:
+
+```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>
+```
+
+`overrideAccess` defaults to `true`. Set it to `false` when operating on behalf of a user.

package/docs/usage.md

@@ -0,0 +1,269 @@
+# Developer Usage
+
+This guide covers the typical code you write in an app that uses `@roxxel/payload-multilang`.
+
+## Enable a Collection
+
+Add the collection slug to the plugin config.
+
+```ts
+payloadMultilang({
+  collections: {
+    posts: true,
+  },
+  languages: [
+    {
+      code: 'en',
+      isDefault: true,
+      name: 'English',
+    },
+    {
+      code: 'uk',
+      name: 'Ukrainian',
+    },
+  ],
+})
+```
+
+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.
+
+## Query Documents for One Language
+
+Use `withLanguage()` with the Local API.
+
+```ts
+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 })
+
+  return payload.find({
+    collection: 'posts',
+    where: withLanguage({
+      language,
+      where: {
+        _status: {
+          equals: 'published',
+        },
+      },
+    }),
+  })
+}
+```
+
+Without an existing `where` query:
+
+```ts
+const { docs } = await payload.find({
+  collection: 'posts',
+  where: withLanguage({
+    language: 'en',
+  }),
+})
+```
+
+With custom language field names:
+
+```ts
+const where = withLanguage({
+  fieldName: 'postLanguage',
+  language: 'uk',
+})
+```
+
+## Get Translations for a Document
+
+Use `getDocumentTranslations()` when you have a document ID and need every linked translation.
+
+```ts
+import { getDocumentTranslations } from '@roxxel/payload-multilang'
+
+const state = await getDocumentTranslations({
+  collection: 'posts',
+  id: post.id,
+})
+
+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.
+
+```ts
+import { getDocumentTranslation } from '@roxxel/payload-multilang'
+
+const ukrainianPost = await getDocumentTranslation({
+  collection: 'posts',
+  id: post.id,
+  language: 'uk',
+})
+```
+
+## Access Control in Server Code
+
+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`.
+
+```ts
+const { docs } = await req.payload.find({
+  collection: 'posts',
+  overrideAccess: false,
+  req,
+  where: withLanguage({
+    language: 'uk',
+  }),
+})
+```
+
+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.
+
+```ts
+payloadMultilang({
+  globals: {
+    'site-settings': true,
+  },
+  languages,
+})
+```
+
+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:
+
+```ts
+import { updateGlobalByLanguage } from '@roxxel/payload-multilang'
+
+await updateGlobalByLanguage({
+  slug: 'site-settings',
+  language: 'uk',
+  data: {
+    title: 'Ukrainian title',
+  },
+})
+```
+
+In request-scoped code:
+
+```ts
+import { findGlobalByLanguageWithPayload } from '@roxxel/payload-multilang'
+
+const settings = await findGlobalByLanguageWithPayload({
+  slug: 'site-settings',
+  language: 'uk',
+  overrideAccess: false,
+  payload: req.payload,
+  req,
+})
+```
+
+## 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:
+
+```ts
+payloadMultilang({
+  collections: {
+    posts: {
+      duplicate: false,
+    },
+  },
+  languages,
+})
+```
+
+To duplicate most fields but exclude specific ones:
+
+```ts
+payloadMultilang({
+  collections: {
+    posts: {
+      duplicateExcludeFields: ['slug', 'seoTitle', 'seoDescription'],
+    },
+  },
+  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.
+
+## Generate Types
+
+After enabling collections, globals, or changing field names, regenerate Payload types.
+
+```bash
+pnpm run generate:types
+```

package/package.json

@@ -0,0 +1,95 @@
+{
+  "name": "@roxxel/payload-multilang",
+  "version": "0.0.1",
+  "description": "Polylang-style document localization for Payload CMS",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./client": {
+      "import": "./dist/exports/client.js",
+      "types": "./dist/exports/client.d.ts",
+      "default": "./dist/exports/client.js"
+    },
+    "./rsc": {
+      "import": "./dist/exports/rsc.js",
+      "types": "./dist/exports/rsc.d.ts",
+      "default": "./dist/exports/rsc.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "docs"
+  ],
+  "scripts": {
+    "build": "pnpm copyfiles && pnpm build:types && pnpm build:swc",
+    "build:swc": "swc ./src -d ./dist --config-file .swcrc --strip-leading-paths",
+    "build:types": "tsc --outDir dist --rootDir ./src",
+    "clean": "rimraf {dist,*.tsbuildinfo}",
+    "copyfiles": "copyfiles -u 1 \"src/**/*.{html,css,scss,ttf,woff,woff2,eot,svg,jpg,png,json}\" dist/",
+    "dev": "next dev dev --turbo",
+    "dev:generate-importmap": "pnpm dev:payload generate:importmap",
+    "dev:generate-types": "pnpm dev:payload generate:types",
+    "dev:payload": "cross-env PAYLOAD_CONFIG_PATH=./dev/payload.config.ts payload",
+    "generate:importmap": "pnpm dev:generate-importmap",
+    "generate:types": "pnpm dev:generate-types",
+    "lint": "eslint",
+    "lint:fix": "eslint ./src --fix",
+    "test": "pnpm test:int && pnpm test:e2e",
+    "test:e2e": "playwright test",
+    "test:int": "vitest"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@eslint/eslintrc": "^3.2.0",
+    "@payloadcms/db-mongodb": "3.84.1",
+    "@payloadcms/db-postgres": "3.84.1",
+    "@payloadcms/db-sqlite": "3.84.1",
+    "@payloadcms/eslint-config": "3.28.0",
+    "@payloadcms/next": "3.84.1",
+    "@payloadcms/richtext-lexical": "3.84.1",
+    "@payloadcms/ui": "3.84.1",
+    "@playwright/test": "1.58.2",
+    "@swc-node/register": "1.10.9",
+    "@swc/cli": "0.6.0",
+    "@types/node": "22.19.9",
+    "@types/react": "19.2.14",
+    "@types/react-dom": "19.2.3",
+    "copyfiles": "2.4.1",
+    "cross-env": "^7.0.3",
+    "eslint": "^9.23.0",
+    "eslint-config-next": "16.2.6",
+    "graphql": "^16.8.1",
+    "mongodb-memory-server": "10.1.4",
+    "next": "16.2.6",
+    "open": "^10.1.0",
+    "payload": "3.84.1",
+    "prettier": "^3.4.2",
+    "qs-esm": "8.0.1",
+    "react": "19.2.6",
+    "react-dom": "19.2.6",
+    "rimraf": "3.0.2",
+    "sharp": "0.34.2",
+    "sort-package-json": "^2.10.0",
+    "typescript": "5.7.3",
+    "vite-tsconfig-paths": "6.0.5",
+    "vitest": "4.0.18"
+  },
+  "peerDependencies": {
+    "payload": "^3.84.1"
+  },
+  "engines": {
+    "node": "^18.20.2 || >=20.9.0",
+    "pnpm": "^9 || ^10 || ^11"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}