> ## Documentation Index
> Fetch the complete documentation index at: https://docs.talosjs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Country

> Country metadata with ISO codes, multi-language names, and IANA timezone typing for internationalized applications.

`@talosjs/country` ships curated country datasets — each entry a `{ name, code }` pair keyed by ISO 3166-1 alpha-2 code — localized into English, German, Spanish, and Italian, plus the `ICountry` interface and supporting types for modeling a country as a stored entity with its own timezone and language.

## Installation

Add the package with Bun.

```bash theme={null}
bun add @talosjs/country
```

## Usage

### Browse a dataset

Each locale exports its own constant. Look up a country by code, or list every entry to drive a picker.

```typescript theme={null}
import { COUNTRIES_EN, COUNTRIES_DE, COUNTRIES_ES, COUNTRIES_IT } from "@talosjs/country";

const unitedStates = COUNTRIES_EN.find((c) => c.code === "US");
// { name: "United States", code: "US" }

const allemagne = COUNTRIES_DE.find((c) => c.code === "FR");
// { name: "Frankreich", code: "FR" }
```

### Typed codes and names

`CountryType` and `CountryNameType` are unions derived from the English dataset, so a country code or name can be validated or narrowed at compile time.

```typescript theme={null}
import type { CountryType, CountryNameType } from "@talosjs/country";

const code: CountryType = "US";       // typed against COUNTRIES_EN
const name: CountryNameType = "France"; // typed against COUNTRIES_EN
```

### Modeling a country entity

`ICountry` describes a country as a persisted record — the same lock/block/public/soft-delete metadata shared by other Talos resources — with a `language` (a `LocaleType` from `@talosjs/translation`) and a `code`.

```typescript theme={null}
import type { ICountry } from "@talosjs/country";

const france: ICountry = {
  id: "country_fr",
  name: "France",
  code: "FR",
  language: "fr",
  isPublic: true,
};
```

### Timezones

`TimeZoneType` is the `name` union from `@vvo/tzdb`'s `TimeZone`, giving you a typed IANA timezone identifier (e.g. `"Europe/Paris"`) to pair with a country record.

```typescript theme={null}
import type { TimeZoneType } from "@talosjs/country";

const timezone: TimeZoneType = "Europe/Paris";
```

## Available locales

| Export         | Language |
| -------------- | -------- |
| `COUNTRIES_EN` | English  |
| `COUNTRIES_DE` | German   |
| `COUNTRIES_ES` | Spanish  |
| `COUNTRIES_IT` | Italian  |

Each dataset has the same shape and country ordering, so switching locales is a matter of swapping the imported constant — pair it with the current [translation](/components/translation) locale to render country names in the user's language.

## When it earns its place

Reach for `@talosjs/country` for a typed, localized country list — populating a country selector, validating a stored `code` against a known set, or modeling a country as a first-class record with `ICountry`. It doesn't fetch or cache data at runtime; every dataset is a static, bundled constant.