feat(plugin-nested-docs): support for translations

MrFlathill · MrFlathill · commit bc0b3a510ca1 · 2026-05-30T12:11:26.000+02:00
Introduces translation keys and default translations for the nested docs plugin fields (breadcrumbs, parent). This enables the plugin to display its UI labels in multiple languages within the Payload admin, improving user experience for internationalized installations.

The plugin now registers its own translation namespace, allowing its field labels to be localized and overridden through the main Payload i18n configuration.
diff --git a/packages/plugin-nested-docs/package.json b/packages/plugin-nested-docs/package.json
@@ -47,6 +47,7 @@
     "lint:fix": "eslint . --fix"
   },
   "devDependencies": {
+    "@payloadcms/translations": "workspace:*",
     "@payloadcms/eslint-config": "workspace:*",
     "payload": "workspace:*"
   },
diff --git a/packages/plugin-nested-docs/src/fields/breadcrumbs.ts b/packages/plugin-nested-docs/src/fields/breadcrumbs.ts
@@ -6,6 +6,12 @@ export const createBreadcrumbsField = (
 ): Field => ({
   name: 'breadcrumbs',
   type: 'array',
+  labels: {
+    // @ts-expect-error - translations are not typed in plugins yet
+    plural: ({ t }) => t('plugin-nested-docs:breadcrumbsPlural'),
+    // @ts-expect-error - translations are not typed in plugins yet
+    singular: ({ t }) => t('plugin-nested-docs:breadcrumbsSingular'),
+  },
   localized: true,
   ...(overrides || {}),
   admin: {
@@ -19,6 +25,8 @@ export const createBreadcrumbsField = (
       admin: {
         disabled: true,
       },
+      // @ts-expect-error - translations are not typed in plugins yet
+      label: ({ t }) => t('plugin-nested-docs:doc'),
       maxDepth: 0,
       relationTo,
     },
@@ -31,14 +39,17 @@ export const createBreadcrumbsField = (
           admin: {
             width: '50%',
           },
-          label: 'URL',
+          // @ts-expect-error - translations are not typed in plugins yet
+          label: ({ t }) => t('plugin-nested-docs:url'),
         },
         {
           name: 'label',
           type: 'text',
           admin: {
             width: '50%',
           },
+          // @ts-expect-error - translations are not typed in plugins yet
+          label: ({ t }) => t('plugin-nested-docs:label'),
         },
       ],
     },
diff --git a/packages/plugin-nested-docs/src/fields/parent.ts b/packages/plugin-nested-docs/src/fields/parent.ts
@@ -13,6 +13,8 @@ export const createParentField = (
     position: 'sidebar',
     ...(overrides?.admin || {}),
   },
+  // @ts-expect-error - translations are not typed in plugins yet
+  label: ({ t }) => t('plugin-nested-docs:parent'),
   // filterOptions are assigned dynamically based on the pluginConfig
   // filterOptions: parentFilterOptions(),
   type: 'relationship',
diff --git a/packages/plugin-nested-docs/src/index.ts b/packages/plugin-nested-docs/src/index.ts
@@ -1,5 +1,7 @@
 import type { Plugin, SingleRelationshipField } from 'payload'
 
+import { deepMergeSimple } from 'payload/shared'
+
 import type { NestedDocsPluginConfig } from './types.js'
 
 import { createBreadcrumbsField } from './fields/breadcrumbs.js'
@@ -8,7 +10,9 @@ import { parentFilterOptions } from './fields/parentFilterOptions.js'
 import { populateBreadcrumbsBeforeChange } from './hooks/populateBreadcrumbsBeforeChange.js'
 import { resaveChildren } from './hooks/resaveChildren.js'
 import { resaveSelfAfterCreate } from './hooks/resaveSelfAfterCreate.js'
+import { translations } from './translations/index.js'
 import { getParents } from './utilities/getParents.js'
+export { translations as nestedDocsTranslations } from './translations/index.js'
 
 export { createBreadcrumbsField, createParentField, getParents }
 
@@ -67,4 +71,8 @@ export const nestedDocsPlugin =
 
       return collection
     }),
+    i18n: {
+      ...config.i18n,
+      translations: deepMergeSimple(translations, config.i18n?.translations ?? {}),
+    },
   })
diff --git a/packages/plugin-nested-docs/src/translations/index.ts b/packages/plugin-nested-docs/src/translations/index.ts
@@ -0,0 +1,15 @@
+import type { GenericTranslationsObject, NestedKeysStripped } from '@payloadcms/translations'
+
+import { de } from './languages/de.js'
+import { en } from './languages/en.js'
+import { it } from './languages/it.js'
+
+export const translations = {
+  de,
+  en,
+  it,
+}
+
+export type PluginNestedDocsTranslations = GenericTranslationsObject
+
+export type PluginNestedDocsTranslationKeys = NestedKeysStripped<PluginNestedDocsTranslations>
diff --git a/packages/plugin-nested-docs/src/translations/languages/de.ts b/packages/plugin-nested-docs/src/translations/languages/de.ts
@@ -0,0 +1,13 @@
+import type { GenericTranslationsObject } from '@payloadcms/translations'
+
+export const de: GenericTranslationsObject = {
+  $schema: './translation-schema.json',
+  'plugin-nested-docs': {
+    breadcrumbsPlural: 'Navigationspfade',
+    breadcrumbsSingular: 'Navigationspfad',
+    doc: 'Dokument',
+    label: 'Bezeichnung',
+    parent: 'Übergeordnetes Dokument',
+    url: 'URL',
+  },
+}
diff --git a/packages/plugin-nested-docs/src/translations/languages/en.ts b/packages/plugin-nested-docs/src/translations/languages/en.ts
@@ -0,0 +1,13 @@
+import type { GenericTranslationsObject } from '@payloadcms/translations'
+
+export const en: GenericTranslationsObject = {
+  $schema: './translation-schema.json',
+  'plugin-nested-docs': {
+    breadcrumbsPlural: 'Breadcrumbs',
+    breadcrumbsSingular: 'Breadcrumb',
+    doc: 'Document',
+    label: 'Label',
+    parent: 'Parent Document',
+    url: 'URL',
+  },
+}
diff --git a/packages/plugin-nested-docs/src/translations/languages/it.ts b/packages/plugin-nested-docs/src/translations/languages/it.ts
@@ -0,0 +1,13 @@
+import type { GenericTranslationsObject } from '@payloadcms/translations'
+
+export const it: GenericTranslationsObject = {
+  $schema: './translation-schema.json',
+  'plugin-nested-docs': {
+    breadcrumbsPlural: 'Percorsi di navigazione',
+    breadcrumbsSingular: 'Percorso di navigazione',
+    doc: 'Documento',
+    label: 'Etichetta',
+    parent: 'Documento genitore',
+    url: 'URL',
+  },
+}
diff --git a/packages/plugin-nested-docs/src/translations/translation-schema.json b/packages/plugin-nested-docs/src/translations/translation-schema.json
@@ -0,0 +1,36 @@
+{
+  "type": "object",
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "plugin-nested-docs": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "breadcrumbsPlural": {
+          "type": "string"
+        },
+        "breadcrumbsSingular": {
+          "type": "string"
+        },
+        "doc": {
+          "type": "string"
+        },
+        "label": {
+          "type": "string"
+        },
+        "parent": {
+          "type": "string"
+        },
+        "url": {
+          "type": "string"
+        }
+      },
+      "required": ["breadcrumbsPlural", "breadcrumbsSingular", "doc", "label", "parent", "url"]
+    }
+  },
+  "required": ["plugin-nested-docs"]
+}
diff --git a/packages/plugin-nested-docs/src/translations/types.ts b/packages/plugin-nested-docs/src/translations/types.ts
@@ -0,0 +1,3 @@
+import type { en } from './languages/en.js'
+
+export type PluginDefaultTranslationsObject = typeof en
diff --git a/test/plugin-nested-docs/collections/Pages.ts b/test/plugin-nested-docs/collections/Pages.ts
@@ -39,7 +39,7 @@ export const Pages: CollectionConfig = {
       },
       admin: {
         components: {
-          Field: null,
+          Field: undefined,
         },
       },
     },
diff --git a/test/plugin-nested-docs/payload-types.ts b/test/plugin-nested-docs/payload-types.ts
@@ -92,6 +92,9 @@ export interface Config {
   globals: {};
   globalsSelect: {};
   locale: 'en' | 'es' | 'de';
+  widgets: {
+    collections: CollectionsWidget;
+  };
   user: User;
   jobs: {
     tasks: unknown;
@@ -125,6 +128,13 @@ export interface Page {
   title: string;
   slug: string;
   fullTitle?: string | null;
+  testArray?:
+    | {
+        testField?: string | null;
+        testField2?: string | null;
+        id?: string | null;
+      }[]
+    | null;
   parent?: (string | null) | Page;
   breadcrumbs?:
     | {
@@ -275,6 +285,13 @@ export interface PagesSelect<T extends boolean = true> {
   title?: T;
   slug?: T;
   fullTitle?: T;
+  testArray?:
+    | T
+    | {
+        testField?: T;
+        testField2?: T;
+        id?: T;
+      };
   parent?: T;
   breadcrumbs?:
     | T
@@ -369,6 +386,16 @@ export interface PayloadMigrationsSelect<T extends boolean = true> {
   updatedAt?: T;
   createdAt?: T;
 }
+/**
+ * This interface was referenced by `Config`'s JSON-Schema
+ * via the `definition` "collections_widget".
+ */
+export interface CollectionsWidget {
+  data?: {
+    [k: string]: unknown;
+  };
+  width: 'full';
+}
 /**
  * This interface was referenced by `Config`'s JSON-Schema
  * via the `definition` "auth".

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+import type { en } from './languages/en.js'`
	`2`	`+`
	`3`	`+export type PluginDefaultTranslationsObject = typeof en`