# PACKAGE: @nofinite/locale

Lightweight localization, country lookups, dialing codes, and flag utilities.

You are using @nofinite/locale for localization, currencies, and country lookups.

---



### Document: locale/installation/page.mdx

# Installation & Setup

Complete guide to installing and using **Nofinite Locale** in Node.js, modern web runtimes, and frontend frameworks.

---

## 1. Package Installation

Install `@nofinite/locale` using your preferred package manager:

```bash
# pnpm
pnpm add @nofinite/locale

# npm
npm install @nofinite/locale

# yarn
yarn add @nofinite/locale

# bun
bun add @nofinite/locale
```

> [!NOTE]
> **Zero Runtime Dependencies:** `@nofinite/locale` has **0 external runtime dependencies**. It executes natively on any JavaScript engine (Node.js `>= 18`, Cloudflare Workers, Deno, Bun, and all modern browsers).

---

## 2. Flag Stylesheet (Optional)

If your application renders SVG country flags, import the lightweight flag stylesheet:

```ts
import '@nofinite/locale/style';
```

Or in your HTML via CDN:

```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@nofinite/locale/dist/style.css" />
```

---

## 3. Verify Installation

### In Node.js / TypeScript / Vanilla DOM

```ts
import { getCountryByCode, getCountryByDialCode, countries } from '@nofinite/locale';

// Lookup metadata for a country by ISO-2 code
const country = getCountryByCode('US');
console.log(country);
// { name: 'United States', iso2: 'US', dialCode: '+1' }

// Total countries in catalog
console.log(`Loaded ${countries.length} countries.`);
```

### In Plain HTML via CDN

```html
<script type="module">
  import { getCountryByCode } from 'https://esm.sh/@nofinite/locale';

  const de = getCountryByCode('DE');
  console.log(de.name); // 'Germany'
</script>
```

---

## Next Steps

- Explore the [Country Lookup API](/locale/usage/country-lookup) for searching and filtering country data.
- Learn how to render [SVG Flags](/locale/usage/flags) using optimized CSS classes.

---


### Document: locale/llms/page.mdx

# LLMs.txt Documentation

How to get tools like Cursor, Windsurf, GitHub Copilot, ChatGPT, and Claude to understand `@nofinite/locale`.

> [!TIP]
> Looking for unified ecosystem presets or multi-package rules? Visit our central [AI Agents Hub](/ai).

We support **LLMs.txt** files for making `@nofinite/locale` country and localization utilities directly available to large language models.

---

## Directory Overview

The following machine-readable context files are available:

- [`/locale/llms.txt`](/locale/llms.txt): The main LLMs index for `@nofinite/locale`.
- [`/locale/llms-full.txt`](/locale/llms-full.txt): Complete context bundle containing ISO country lookups, dialing codes, and SVG flags.
- [`/llms.txt`](/llms.txt): Ecosystem index covering all 8 `@nofinite` libraries.
- [`/llms-full.txt`](/llms-full.txt): The unified ecosystem bundle.

---

## Usage with Cursor & Windsurf

```markdown
# Locale Rules for AI Assistants
1. Package Imports: Import country utilities and metadata from `@nofinite/locale` (zero dependencies, framework-agnostic).
2. Flag Stylesheet: Import `@nofinite/locale/style` and use `.nf-flag` and `.nf-flag-{iso}` classes (pure CSS/SVG).
3. Use ISO-3166-1 alpha-2 codes (e.g. `US`, `GB`, `IN`, `DE`) for standardized country lookups and flags.
```

---


### Document: locale/page.mdx

<PackageHero packageId="locale" />

---

## Overview

**Nofinite Locale** is a high-performance, tree-shakeable, 100% framework-agnostic utility library providing standardized international country metadata, phone dialing codes, and lightweight CSS-driven SVG flags for web applications.

It is designed to power international phone inputs, registration forms, billing address selectors, and localization layers with strict TypeScript typings and zero external runtime dependencies.

---

## Core Capabilities

- **Normalized Country Metadata**: 240+ international countries and territories with official common names, ISO-2 alpha codes, and international dialing codes.
- **Fast In-Memory Lookup APIs**: Instant case-insensitive resolution by ISO-2 code or telephone dial code (`getCountryByCode`, `getCountryByDialCode`).
- **Optimized CSS Flag Icons**: Pure CSS SVG flags (`@nofinite/locale/style`) avoiding hundreds of heavy raster images or separate HTTP requests.
- **Strict TypeScript Types**: Fully typed `Country` interface with zero `any` leakage.
- **100% Framework Agnostic**: Runs everywhere — Node.js, Edge workers, Deno, Bun, Next.js, Vite, Vue, Svelte, or vanilla HTML/JS.

---

## 1. Usage in Vanilla TypeScript & HTML (Core First)

### In-Memory Metadata Lookups

```ts
import { getCountryByCode, getCountryByDialCode, countries } from '@nofinite/locale';

// 1. Lookup country by ISO-2 code (case-insensitive)
const usa = getCountryByCode('US');
console.log(usa);
// { name: 'United States', iso2: 'US', dialCode: '+1' }

// 2. Lookup country by telephone dial code
const india = getCountryByDialCode('+91');
console.log(india);
// { name: 'India', iso2: 'IN', dialCode: '+91' }

// 3. Iterate over the complete country catalog for a select dropdown
const options = countries.map(c => ({
  value: c.iso2,
  label: `${c.name} (${c.dialCode})`
}));
```

### Pure HTML & CSS Flag Rendering

Import the stylesheet in your CSS or JavaScript entry:

```ts
import '@nofinite/locale/style';
```

Or in plain HTML via CDN:

```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@nofinite/locale/dist/style.css" />
```

Use semantic `.nf-flag` and `.nf-flag-{iso}` classes:

```html
<!-- Standard 4:3 Flag -->
<span class="nf-flag nf-flag-us"></span>

<!-- Square 1:1 Flag -->
<span class="nf-flag nf-flag-jp square"></span>

<!-- Flag inside a button -->
<button class="btn btn-outline flex items-center gap-2">
  <span class="nf-flag nf-flag-fr square"></span>
  <span>Français</span>
</button>
```

---

## 2. Usage in React

```tsx
'use client';

import React, { useState } from 'react';
import { countries, getCountryByCode } from '@nofinite/locale';
import '@nofinite/locale/style';
import '@nofinite/nuicss/styles.css';

export function CountryPicker() {
  const [selectedIso, setSelectedIso] = useState('US');
  const activeCountry = getCountryByCode(selectedIso);

  return (
    

      {activeCountry && (
        <p className="text-xs text-muted">
          Dial Code: <span className="font-mono text-primary">{activeCountry.dialCode}</span>
        </p>
      )}
    </div>
  );
}
```

---

## API Summary

| Export | Type | Description |
| :--- | :--- | :--- |
| [`countries`](/locale/usage/country-lookup) | `Country[]` | Array of all countries with name, ISO2, and dialCode |
| [`getCountryByCode(iso)`](/locale/usage/country-lookup) | `(iso: string) => Country \| undefined` | Resolves country metadata by ISO-2 code |
| [`getCountryByDialCode(code)`](/locale/usage/country-lookup) | `(dialCode: string) => Country \| undefined` | Resolves country metadata by phone dial code |
| [`@nofinite/locale/style`](/locale/usage/flags) | Stylesheet | Optimized SVG flag sprites and utility classes |

---

## Next Steps

- Follow the [Installation Guide](/locale/installation) to install and configure the package.
- Explore [Country Lookup](/locale/usage/country-lookup) for country filtering and search recipes.
- Explore [SVG Flags](/locale/usage/flags) for flag sizing, styling, and form integration.

---


### Document: locale/releases/page.mdx

# Locale Releases
 
**Latest version:** `v1.0.0` (25 December 2025)

---

## Summary

Initial stable release of **Locale**.

**Locale** is a lightweight TypeScript library providing standardized country metadata, flags, and international dialing codes for web applications.

---

## Included

- Country metadata (name, ISO code, dial code)
- Type-safe country lookup utilities
- CSS-based SVG flag assets and utility classes
- Support for modern frameworks and plain HTML usage
- Dual distribution (ESM & CJS) with optional CDN inclusion

---

## Notes

- Establishes the public API surface for locale data usage.
- Designed for integration in both library and application contexts.
- No breaking changes prior to this release.

---


### Document: locale/usage/country-lookup/page.mdx

# Country Lookup

Nofinite Locale provides simple helper functions to retrieve country information.

## Lookup by ISO Code or Dial Code

### JavaScript / TypeScript

```ts
import { getCountryByCode, getCountryByDialCode } from '@nofinite/locale';

// Lookup by ISO-2 code (case-insensitive)
const india = getCountryByCode('IN');

// Lookup by dial code
const indiaAlt = getCountryByDialCode('+91');
// or
const indiaAlt2 = getCountryByDialCode('91');

console.log(india);
```

**Returned object structure:**

```ts
{
  name: "India",
  iso2: "IN",
  dialCode: "+91"
}
```

### HTML (CDN)

```html
<script>
  const country = NofiniteLocale.getCountryByCode('IN');
  console.log(country.name);
  console.log(country.dialCode);
</script>
```

---


### Document: locale/usage/flags/page.mdx

# SVG Flag Icons

**Nofinite Locale** provides lightweight, CSS-driven SVG flag icons for 240+ international countries and territories.

The stylesheet bundles vectorized country flag sprites that scale cleanly, eliminating the need to serve hundreds of loose PNGs or make external network requests.

---

## 1. Import Styles

### In JavaScript / TypeScript Entry

```ts
import '@nofinite/locale/style';
```

### In Plain HTML / CDN

```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@nofinite/locale/dist/style.css" />
```

---

## 2. CSS Flag Classes

| Class | Description |
| :--- | :--- |
| `.nf-flag` | Base flag container (required) |
| `.nf-flag-{iso}` | Target country by lowercase ISO-2 code (e.g. `nf-flag-us`, `nf-flag-in`, `nf-flag-de`) |
| `.square` | Optional modifier for square (1:1) aspect ratio |

---

## 3. Usage in Vanilla HTML (Core First)

### Standard 4:3 Flag

```html
<span class="nf-flag nf-flag-us"></span>
<span class="nf-flag nf-flag-gb"></span>
<span class="nf-flag nf-flag-in"></span>
```

### Square 1:1 Flag

```html
<span class="nf-flag nf-flag-jp square"></span>
<span class="nf-flag nf-flag-br square"></span>
```

### Embedded in Buttons & Form Controls

```html
<button class="btn btn-outline flex items-center gap-2">
  <span class="nf-flag nf-flag-fr square"></span>
  <span>Français (FR)</span>
</button>
```

---

## 4. Usage in React

```tsx
'use client';

import React from 'react';
import '@nofinite/locale/style';

interface FlagProps {
  iso: string;
  square?: boolean;
  className?: string;
}

export function Flag({ iso, square = false, className = '' }: FlagProps) {
  const normalized = iso.toLowerCase();
  const squareClass = square ? 'square' : '';

  return (
    <span
      className={`nf-flag nf-flag-${normalized} ${squareClass} ${className}`.trim()}
      role="img"
      aria-label={`${iso.toUpperCase()} flag`}
    />
  );
}

// Example usage
export function LanguageSelector() {
  return (
    
  );
}
```

---