Internationalization (i18n)

How to add multi-language support to Docyrus UI components.

Overview

Docyrus UI components have built-in i18n support through a provider-agnostic translation system. Components display English by default and automatically switch to the active language when a translation provider is present.

No dependency on any specific i18n library — works with @docyrus/i18n, react-i18next, next-intl, or any custom solution.

Quick Start

1. Wrap your app with `UiTranslationProvider`

import { UiTranslationProvider } from '@docyrus/ui/hooks/use-ui-translation';

function App() {
  return (
    <UiTranslationProvider t={yourTranslateFunction}>
      {/* All Docyrus UI components will now be translated */}
      <Calendar events={events} />
      <DataGrid table={table} />
    </UiTranslationProvider>
  );
}

The t prop accepts any function with the signature:

(key: string, fallback?: string | Record<string, string | number>) => string

2. Without a provider

Components render in English with no setup required:

// No provider needed — English fallback works automatically
<Calendar events={events} />

Integration Examples

@docyrus/i18n

import { useDocyrusI18n } from '@docyrus/i18n';
import { UiTranslationProvider } from '@docyrus/ui/hooks/use-ui-translation';

function AppShell({ children }: { children: React.ReactNode }) {
  const { t } = useDocyrusI18n();

  return (
    <UiTranslationProvider t={t}>
      {children}
    </UiTranslationProvider>
  );
}

react-i18next

import { useTranslation } from 'react-i18next';
import { UiTranslationProvider } from '@docyrus/ui/hooks/use-ui-translation';

function AppShell({ children }: { children: React.ReactNode }) {
  const { t } = useTranslation();

  return (
    <UiTranslationProvider t={t}>
      {children}
    </UiTranslationProvider>
  );
}

next-intl

import { useTranslations } from 'next-intl';
import { UiTranslationProvider } from '@docyrus/ui/hooks/use-ui-translation';

function AppShell({ children }: { children: React.ReactNode }) {
  const t = useTranslations();

  return (
    <UiTranslationProvider t={t}>
      {children}
    </UiTranslationProvider>
  );
}

Translation Keys

All component translation keys follow the ui.<group>.<camelCaseKey> convention:

Group	Prefix	Example Key	English Default
Common	`ui.common`	`ui.common.search`	Search
Calendar	`ui.calendar`	`ui.calendar.addEvent`	Add Event
Data Grid	`ui.dataGrid`	`ui.dataGrid.filter`	Filter
Form Fields	`ui.formField`	`ui.formField.selectPlaceholder`	Select...
Pricing Engine	`ui.pricing`	`ui.pricing.subtotal`	Subtotal
Mega Select	`ui.megaSelect`	`ui.megaSelect.search`	Search
Team Chat	`ui.teamChat`	`ui.teamChat.writePost`	Write a post...
Contact Activity	`ui.contactActivity`	`ui.contactActivity.all`	All
Log Activity	`ui.logActivity`	`ui.logActivity.taskSubject`	Task subject
Email Composer	`ui.emailComposer`	`ui.emailComposer.send`	Send
Record Sharing	`ui.recordSharing`	`ui.recordSharing.share`	Share
Query Builder	`ui.queryBuilder`	`ui.queryBuilder.columns`	Columns
Data Grid View	`ui.dataGridView`	`ui.dataGridView.selectView`	Select view
Time Slot	`ui.timeSlot`	`ui.timeSlot.available`	Available
Scheduler	`ui.scheduler`	`ui.scheduler.today`	Today
Agent	`ui.agent`	`ui.agent.sendMessage`	Send message
Tree View	`ui.treeView`	`ui.treeView.expandAll`	Expand All
Place Autocomplete	`ui.placeAutocomplete`	`ui.placeAutocomplete.searchPlaces`	Search places...

How It Works

Components use the useUiTranslation hook internally:

import { useUiTranslation } from '@/hooks/use-ui-translation';

function MyComponent() {
  const { t } = useUiTranslation();

  return (
    <button>{t('ui.calendar.addEvent', 'Add Event')}</button>
  );
}

First argument: Translation key
Second argument: English fallback text (shown when key has no translation or no provider)

The hook reads from UiTranslationContext:

If UiTranslationProvider is in the tree → uses the provided t function
If no provider → returns the English fallback string

Customizing Translations

To override a specific component's text, add the corresponding key to your i18n translation dictionary.

For example, to change the Calendar's "Add Event" button to "New Appointment" in Turkish:

{
  "ui.calendar.addEvent": "Yeni Randevu"
}

Any key not present in your dictionary will fall back to the English default embedded in the component.

API Reference

UiTranslationProvider

Prop	Type	Description
`t`	`(key: string, fallback?: string \| Record<string, string \| number>) => string`	Translation function from your i18n library
`children`	`ReactNode`	Child components

useUiTranslation

function useUiTranslation(): { t: TranslateFn }

Returns { t } where t(key, fallback) resolves to:

Translated string from provider (if available)
English fallback string (if no provider or key not found)

Internationalization (i18n)

On this page