i18n-tiny

The simplest i18n library for modern frameworks. Type-safe, zero-dependency, minimal setup.

One function for fully-typed translations. define() gives you complete autocomplete for every translation key.

Optional routing support with create() for Next.js and Astro.

Currently supports: Next.js | Astro

Documentation

Quick Start

Next.js

npm install @i18n-tiny/next

// i18n.ts - define() gives you everything
import { define } from '@i18n-tiny/next'

const { client, server, Provider } = define({
  locales: ['en', 'ja'] as const,
  defaultLocale: 'en',
  messages: { en: enMessages, ja: jaMessages }
})

export { Provider }
export const { useMessages, useTranslations } = client
export const { getMessages, getTranslations } = server

// Server Component
const messages = await getMessages(locale)
const t = await getTranslations(locale)
return <h1>{messages.common.title}</h1>  // ← Typed! Full autocomplete
return <p>{t('greeting', { name })}</p>  // ← Interpolation

// Client Component
const messages = useMessages()
const t = useTranslations()
return <p>{messages.common.welcome}</p>  // ← Typed! Full autocomplete
return <p>{t('greeting', { name })}</p>  // ← Interpolation

Full documentation →

Astro

npm install @i18n-tiny/astro

// i18n.ts - define() gives you everything
import { define } from '@i18n-tiny/astro'

export const { getMessages, getTranslations } = define({
  locales: ['en', 'ja'] as const,
  defaultLocale: 'en',
  messages: { en: enMessages, ja: jaMessages }
})

---
const messages = getMessages(locale)
const t = getTranslations(locale)
---
<h1>{messages.common.title}</h1>  <!-- ← Typed! Full autocomplete -->
<p>{t('greeting', { name })}</p>  <!-- ← Interpolation -->

Full documentation →

Features

• One function: Just define() - get Provider, hooks, and utilities
• Type-safe: Full TypeScript support with automatic type inference
• Zero dependencies: No external i18n libraries needed
• Framework support: Next.js, Astro
• Minimal bundle: No bloat, just what you need

Security

Variable interpolation ({name}) inserts values as-is without HTML escaping.

Safe usage (React/Astro auto-escape):

// ✅ Safe - framework escapes output
<p>{t('greeting', { name: userInput })}</p>

Unsafe usage:

// ❌ Unsafe - bypasses escaping
<p dangerouslySetInnerHTML={{ __html: t('greeting', { name: userInput }) }} />
// Astro: <p set:html={t('greeting', { name: userInput })} />

When using dangerouslySetInnerHTML or set:html, sanitize user input first.

Examples

See the examples directory for complete working examples.

Development

This is a pnpm workspace monorepo.

pnpm install   # Install dependencies
pnpm build     # Build all packages
pnpm test      # Run tests
pnpm lint      # Lint

License

MIT