# Internationalization (i18n)
URL: /docs/web/guide/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`

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

function App() {
  return (
    
  );
}
```

The `t` prop accepts any function with the signature:

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

### 2. Without a provider

Components render in **English** with no setup required:

```tsx
// No provider needed — English fallback works automatically

```

## Integration Examples

### @docyrus/i18n

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

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

  return (
    
  );
}
```

### react-i18next

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

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

  return (
    
  );
}
```

### next-intl

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

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

  return (
    
  );
}
```

## 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:

```tsx
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:

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

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

## Date Formatting

Docyrus UI components **do not format dates** — they display raw values by default. To show formatted dates (e.g. `DD/MM/YYYY` or `MM/DD/YYYY`), wrap your app with `DateFormatProvider`.

### Setup

```tsx
import { DateFormatProvider } from '@docyrus/ui/hooks/use-date-format';
import { format } from 'date-fns';

function App() {
  return (
    
  );
}
```

Works with any date library — `date-fns`, `dayjs`, `Intl.DateTimeFormat`, or plain functions.

### Per-component override

Some components accept `formatDate` / `formatDateTime` props directly for per-instance customization:

```tsx
<DataGrid
  table={table}
  formatDate={(v) => dayjs(v).format('MM/DD/YYYY')}
  formatDateTime={(v) => dayjs(v).format('MM/DD/YYYY h:mm A')}
/>
```

Per-component props take precedence over the provider.

### Without a provider

Components display **raw values** (e.g. `2026-04-13` or `2026-04-13T10:30:00.000Z`) with no formatting applied.

### useDateFormat hook

```ts
import { useDateFormat } from '@docyrus/ui/hooks/use-date-format';

function MyComponent() {
  const { formatDate, formatDateTime, formatTime } = useDateFormat();

  return <span>{formatDate(someDate)}</span>;
}
```

## 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

```ts
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)

### DateFormatProvider

| Prop | Type | Description |
|------|------|-------------|
| `formatDate` | `(value: unknown) => string` | Format a date value for display |
| `formatDateTime` | `(value: unknown) => string` | Format a datetime value for display |
| `formatTime` | `(value: unknown) => string` | Format a time value for display |
| `children` | `ReactNode` | Child components |

### useDateFormat

```ts
function useDateFormat(): {
  formatDate: (value: unknown) => string;
  formatDateTime: (value: unknown) => string;
  formatTime: (value: unknown) => string;
}
```

Returns formatters from `DateFormatProvider`. Without a provider, all formatters return the raw value as a string.