# Internationalization packs

Locale packs are optional exact imports. The base, lite, and compatibility
renderers never bundle locale data unless an application imports it.

## Static locale

```ts
import { DataTable } from 'wts-data-table/base';
import { dataTableBaseLocaleOptions } from 'wts-data-table/i18n';
import { frLocale } from 'wts-data-table/locales/fr';
import 'wts-data-table/base.css';

new DataTable({
  ...dataTableBaseLocaleOptions(frLocale),
  columns,
  data,
  element: '#people',
});
```

Use `dataTableLocaleOptions()` for the compatibility renderer or
`dataTableLiteLocaleOptions()` for the lite renderer. These helpers configure
the core collation locale, translated labels, advanced-filter operators, and
writing direction together.

## Official exact entry points

| Locale | Import | Export | Direction |
| --- | --- | --- | --- |
| English | `wts-data-table/locales/en` | `enLocale` | LTR |
| French | `wts-data-table/locales/fr` | `frLocale` | LTR |
| German | `wts-data-table/locales/de` | `deLocale` | LTR |
| Spanish | `wts-data-table/locales/es` | `esLocale` | LTR |
| Arabic | `wts-data-table/locales/ar` | `arLocale` | RTL |
| Hindi | `wts-data-table/locales/hi` | `hiLocale` | LTR |
| Japanese | `wts-data-table/locales/ja` | `jaLocale` | LTR |
| Simplified Chinese | `wts-data-table/locales/zh-CN` | `zhCNLocale` | LTR |
| Brazilian Portuguese | `wts-data-table/locales/pt-BR` | `ptBRLocale` | LTR |

`wts-data-table/locales` is an optional aggregate entry for applications that
genuinely need every pack. Exact imports are recommended for static locales.

## Negotiation and fallback

```ts
import { resolveDataTableLocale } from 'wts-data-table/i18n';
import { enLocale } from 'wts-data-table/locales/en';
import { frLocale } from 'wts-data-table/locales/fr';

const locale = resolveDataTableLocale(
  navigator.languages,
  [enLocale, frLocale],
  { fallback: 'en' },
);
```

The resolver supports canonical BCP 47 tags, pack aliases, progressive
subtag fallback, browser language arrays, and weighted `Accept-Language`
headers. Missing strings in a custom or official pack inherit the complete
English contract, so newly added labels cannot render as `undefined`.

## Lazy locale loading

Keep dynamic imports explicit so bundlers create one chunk per language:

```ts
async function loadLocale(language: string) {
  switch (language.split('-')[0]) {
    case 'ar': return (await import('wts-data-table/locales/ar')).arLocale;
    case 'de': return (await import('wts-data-table/locales/de')).deLocale;
    case 'fr': return (await import('wts-data-table/locales/fr')).frLocale;
    default: return (await import('wts-data-table/locales/en')).enLocale;
  }
}
```

Avoid a variable package subpath such as `import('wts-data-table/locales/' +
language)`, which many bundlers cannot statically analyze.

## Numbers, dates, lists, relative time, and plurals

```ts
import { createDataTableLocaleFormatters } from 'wts-data-table/i18n';

const format = createDataTableLocaleFormatters(frLocale);
format.number(1234.5);                    // 1 234,5
format.dateTime(new Date());
format.list(['Design', 'Platform']);
format.relativeTime(-2, 'day');
format.pluralCategory(2);
```

The helpers use the platform `Intl` implementation and do not ship CLDR data.
Applications targeting runtimes without the required `Intl` constructors must
provide their normal application-level polyfills.

## Custom and product-specific packs

```ts
import { defineDataTableLocalePack } from 'wts-data-table/i18n';

export const productEnglish = defineDataTableLocalePack({
  aliases: ['en-ACME'],
  locale: 'en-US',
  name: 'ACME English',
  labels: {
    globalFilter: 'Find orders',
    nextPage: 'Continue',
  },
});
```

Definitions are validated, canonicalized, completed with English fallbacks,
and frozen. A pack can independently override compatibility, base, lite, and
filter-operator labels.

## Setup assistant

```sh
npx wts-data-table setup --renderer base --locale fr --write
npx wts-data-table setup --renderer complete --locale ar --write
```

The generated module imports exactly one locale and the correct renderer
helper. It does not add every official pack.