# Internationalization (i18n)

Widgets built from the canonical template use `i18next` and `react-i18next`, set up through `configureI18n` from `@dynamic-framework/ui-react`. Both packages are in the template's `package.json`.

---

## Files

```
src/
├── config/
│   └── i18nConfig.ts   # configureI18n with both locales
└── locales/
    ├── en.json
    └── es.json
```

- One JSON file per language in `src/locales/`, with the same keys in both.
- The validator requires both files and checks that each is a JSON object with at least one key (*Core Files*, *Translation Content*).

---

## Configuration: `src/config/i18nConfig.ts`

```ts
import { configureI18n } from '@dynamic-framework/ui-react';

import en from '@/locales/en.json';
import es from '@/locales/es.json';

import { DEFAULT_LANGUAGE, SITE_LANG } from './widgetConfig';

const resources = {
  es: { translation: es },
  en: { translation: en },
};

configureI18n(resources, { lng: SITE_LANG, fallbackLng: DEFAULT_LANGUAGE });

export const changeLanguage = (lang: keyof typeof resources) => (
  configureI18n(resources, { lng: lang, fallbackLng: DEFAULT_LANGUAGE })
);
```

- The initial language is `SITE_LANG`, read from the Liquid tag `{{site.language}}` in `src/config/widgetConfig.ts`, so the widget starts in the site's language.
- `DEFAULT_LANGUAGE` (in `widgetConfig.ts`) is used when `{{site.language}}` arrives empty or unresolved, and as `fallbackLng`. The template sets it to `'es'`.
- `changeLanguage(lang)` switches the language at runtime.
- `src/app/main.tsx` imports `@/config/i18nConfig` before rendering `App`.

---

## Visible text comes from `t('...')`

ESLint rejects literal text in JSX in `src/`: every visible text comes from `t('...')`, with its key in `src/locales/*.json`.

```tsx
import { useTranslation } from 'react-i18next';

import { SITE_LANG } from '@/config/widgetConfig';

export default function SiteLang() {
  const { t } = useTranslation();

  return (
    <small className="fw-normal text-center text-muted">
      {t('siteLang', { lang: SITE_LANG })}
    </small>
  );
}
```

```json
// src/locales/en.json
"siteLang": "This site is in: {lang}",
```

```json
// src/locales/es.json
"siteLang": "Este sitio está en: {lang}",
```

Props that hold visible text also take `t('...')`, for example `text={t('common.save')}` on a `DButton` or `placeholder={t('common.searchPlaceholder')}` on a `DInput`.

---

## Single-brace interpolation

`configureI18n` sets i18next's interpolation delimiters to single braces (`prefix: '{'`, `suffix: '}'`) and turns off escaping (`escapeValue: false`).

- Locale values interpolate with single braces: `"This site is in: {lang}"`.
- The call uses the usual i18next signature: `t('siteLang', { lang: SITE_LANG })`.
- `{{lang}}` is **not** interpolated, and it must not appear in texts anyway: Modyo processes the widget as a Liquid template and would interpret `{{ }}` on the site.

---

## Keys of a feature

Each feature keeps its keys under its own block. The reference feature uses `entities`:

```tsx
<DListGroup ariaLabel={t('entities.list.title')}>
```

When copying the feature, copy the `entities` block of both locale files under the new domain name. Shared texts (`common.save`, `common.cancel`, `common.searchPlaceholder`, …) and the states of `src/shared/ui` (`states.*`) live at the top level of the locale files.

---

## Using another i18n library

Some Dynamic UI components depend on `i18next`/`react-i18next` through `configureI18n`, so those dependencies cannot be removed. Another library can run in parallel in the widget's own code; keep its initial language in sync with `SITE_LANG`.

---

## See also

- `modyo://docs/widgets/patterns-liquid-environment` — `SITE_LANG` and other site variables
- `modyo://docs/widgets/patterns-features` — locale keys when adding a feature
