Allow passing a custom t() factory function via I18nOptions to support external translation libraries

[MurzNN]

Summary

Currently, Payload's translation function t() is hardcoded throughout the core. There is no way to replace it with a function from an external i18n library (e.g. Lingui, i18next, FormatJS). This feature request proposes adding a createT escape hatch to I18nOptions that would allow users to inject a custom translation function at the config level.

Why it is needed

Many teams already have an established i18n stack in their project. When they adopt Payload, they are forced to maintain two parallel translation systems — one for their application and one for Payload's admin UI. This creates friction in several areas:

• Duplicate translation infrastructure — separate message catalogs, separate tooling, separate CI pipelines for extraction and compilation.
• Inconsistent pluralization and formatting — Payload uses a simple namespace:key string lookup with basic variable interpolation, while libraries like Lingui and FormatJS support full ICU message format, gender, and ordinal plurals.
• No compile-time extraction — tools like @lingui/cli or formatjs extract cannot extract strings from Payload's internal components because they use a different API.
• Custom components are already free — users can call useLingui() or useTranslation() inside their own custom Payload components today. The only blocker is that Payload's own internal components cannot be driven by the same system.

Why it is not hard to implement

The change is additive and backward-compatible. No existing behavior changes unless the user explicitly provides a createT factory. The required modifications touch five files:

1. packages/translations/src/types.ts — add createT to I18nOptions

export type I18nOptions<TTranslations = DefaultTranslationsObject> = {
  fallbackLanguage?: AcceptedLanguages
  supportedLanguages?: SupportedLanguages
  translations?: Partial<{
    [key in AcceptedLanguages]?: Language<TTranslations>['translations']
  }>
  // NEW: optional factory called with the merged translations and active language
  createT?: (
    translations: Language<TTranslations>['translations'],
    language: string,
  ) => TFunction
}

2. packages/translations/src/utilities/init.ts — use createT in initI18n when provided

// inside initI18n, after mergedTranslations is computed:
const t = config.createT
  ? config.createT(mergedTranslations as any, language)
  : initTFunction({ config: config as any, language, translations: translations as any }).t

The existing initTFunction path is unchanged. The memoization cache key (currently ['language', 'context']) should be extended or bypassed when createT is present, since the factory itself is not part of the cache key.

3. packages/ui/src/providers/Translation/index.tsx — accept an optional tFunction prop

type Props = {
  // ... existing props
  tFunction?: TFunction  // NEW
}

const nextT: ContextType['t'] = React.useCallback(
  (key, vars): string =>
    tFunction
      ? tFunction(key, vars)
      : t({ key, translations, vars }),
  [translations, tFunction],
)

4. packages/ui/src/providers/Root/index.tsx — forward tFunction to TranslationProvider

Add tFunction?: TFunction to RootProvider's Props and pass it through to <TranslationProvider>.

5. Next.js / TanStack adapter root layouts — thread the factory from config to RootProvider

The server component that calls getNextRequestI18n and renders RootProvider would need to read config.i18n.createT and pass the resulting t (or the factory itself) down as a prop.

Scope

• All server-side call sites (createPayloadRequest, getLocalI18n, getNextRequestI18n) automatically benefit from the initI18n change since they all call it with config.i18n.
• The client-side path requires the additional TranslationProvider / RootProvider changes.
• No breaking changes — createT is optional and the default behavior is identical to today.

Example usage (Lingui adapter)

import { i18n } from '@lingui/core'

export default buildConfig({
  i18n: {
    supportedLanguages: { en: enTranslations, cs: csTranslations },
    fallbackLanguage: 'en',
    createT: (_translations, language) => {
      i18n.activate(language)
      // wrap Lingui's i18n into Payload's TFunction signature
      return (key, vars) => i18n._(key, vars ?? {})
    },
  },
})

Alternatives considered

• Forking @payloadcms/ui — possible today but requires maintaining a fork across every Payload release.
• Overriding via module aliasing — fragile and not officially supported.
• Using Lingui only in custom components — already possible, but leaves Payload's own UI strings outside the unified i18n pipeline.

---

Feel free to adjust the tone or trim sections before posting. The most important technical detail to keep is the five-file breakdown, since it demonstrates the change is genuinely small and non-breaking.