Implementing Dynamic Database-Driven Translations in PayloadCMS

[kbarejko]

Background

We needed to implement a flexible internationalization system for our PayloadCMS v3 project that would:

1. Support multiple languages (Polish, English, French)
2. Store translations in the database instead of hardcoding them
3. Allow easy management of translations through the admin panel
4. Support translations for collection labels, field labels, and descriptions

Solution Overview

We created a system consisting of:

1. Translations Collection

   • Stores all translations with language variants
   • Organized by namespaces (collections, fields, blocks, UI)
   • Each translation has a unique key and translations for each language

2. Translation Utility

   • withTranslations HOC to wrap collection configs
   • In-memory caching (5-minute TTL)
   • Hooks to dynamically fetch and apply translations
   • Support for common field translations

3. Seeding System

   • Endpoint to seed/reseed translations
   • Support for initial translation data
   • Handles duplicate prevention

Implementation Details

1. Translations Collection Structure

{
  slug: 'translations',
  fields: [
    {
      name: 'key',
      type: 'text',
      required: true,
      unique: true,
    },
    {
      name: 'namespace',
      type: 'select',
      options: ['collections', 'fields', 'blocks', 'ui'],
    },
    {
      name: 'pl',
      type: 'text',
      required: true,
    },
    {
      name: 'en',
      type: 'text',
      required: true,
    },
    {
      name: 'fr',
      type: 'text',
      required: true,
    }
  ]
}

2. Translation Keys Structure

// Collection labels
'collections.{collectionSlug}.labels.singular'
'collections.{collectionSlug}.labels.plural'

// Field labels
'collections.{collectionSlug}.fields.{fieldName}'

// Common fields
'common.fields.{fieldName}'

3. Using the System

const MyCollection: CollectionConfig = {
  slug: 'myCollection',
  fields: [
    {
      name: 'title',
      type: 'text',
      required: true,
    }
  ]
}

export const MyCollection = withTranslations(MyCollection)

Key Features

1. Dynamic Loading: Translations are loaded from the database on demand
2. Performance Optimized: In-memory caching reduces database queries
3. Flexible: Supports collection-specific and common field translations
4. Maintainable: Centralized translation management through admin panel
5. Type-Safe: Full TypeScript support

Challenges Overcome

1. Hook Timing: Switched from beforeRead to afterRead hook for proper translation application
2. Client Components: Special handling for fields with functions (like filterOptions) to avoid serialization issues
3. Performance: Implemented caching to reduce database load
4. Migration: Support for transitioning from hardcoded to dynamic translations

Usage Example

1. Create translations in the database:

{
  key: 'myCollection.labels.singular',
  namespace: 'collections',
  pl: 'Moja Kolekcja',
  en: 'My Collection',
  fr: 'Ma Collection'
}

2. Apply translations to collection:

const MyCollection = withTranslations(MyCollectionConfig)

3. Seed/reseed translations:

GET /api/seed?reseed=true

Benefits

1. Maintainability: No need to modify code for translation updates
2. Scalability: Easy to add new languages
3. User-Friendly: Non-technical users can manage translations
4. Consistency: Centralized translation management
5. Performance: Optimized with caching

Future Improvements

1. Translation versioning
2. Bulk translation updates
3. Translation export/import
4. Translation status tracking
5. Missing translation detection

Has anyone tried to tackle a similar concept?