|
1 | | -# next-i18n-tiny |
| 1 | +# next-i18n-tiny |
| 2 | + |
| 3 | +[](https://www.npmjs.com/package/next-i18n-tiny) |
| 4 | +<!-- [](https://www.npmjs.com/package/next-i18n-tiny) --> |
| 5 | +[](https://github.com/unlibra/next-i18n-tiny/actions) |
| 6 | +[](https://github.com/unlibra/next-i18n-tiny/blob/main/LICENSE) |
| 7 | +[](https://www.typescriptlang.org/) |
| 8 | + |
| 9 | +Type-safe, zero-dependency i18n library for Next.js App Router with React Server Components support. |
| 10 | + |
| 11 | +Inspired by next-intl, designed for simplicity and type safety. |
| 12 | + |
| 13 | +## Features |
| 14 | + |
| 15 | +- **Type-safe**: Full TypeScript support with **automatic type inference** - autocomplete for `messages.site.name`, `t('common.title')`, and all nested keys |
| 16 | +- **Zero dependencies**: No external i18n libraries needed |
| 17 | +- **Server Components**: Native RSC support |
| 18 | +- **Simple API**: Single configuration, minimal boilerplate |
| 19 | +- **Small**: Minimal bundle size |
| 20 | +- **No global state**: Pure function factory pattern |
| 21 | + |
| 22 | +## Installation |
| 23 | + |
| 24 | +```bash |
| 25 | +npm install next-i18n-tiny |
| 26 | +# or |
| 27 | +pnpm add next-i18n-tiny |
| 28 | +# or |
| 29 | +yarn add next-i18n-tiny |
| 30 | +``` |
| 31 | + |
| 32 | +## Usage |
| 33 | + |
| 34 | +### Project Structure |
| 35 | + |
| 36 | +``` |
| 37 | +your-app/ |
| 38 | +├── app/ |
| 39 | +│ └── [locale]/ |
| 40 | +│ ├── layout.tsx |
| 41 | +│ └── page.tsx |
| 42 | +├── messages/ |
| 43 | +│ ├── en.ts |
| 44 | +│ └── ja.ts |
| 45 | +├── i18n.ts |
| 46 | +└── proxy.ts |
| 47 | +``` |
| 48 | + |
| 49 | +### Minimal Setup |
| 50 | + |
| 51 | +**1. Create message files** |
| 52 | + |
| 53 | +```typescript |
| 54 | +// messages/en.ts |
| 55 | +export default { |
| 56 | + common: { |
| 57 | + title: "My Site", |
| 58 | + description: "Welcome to my site" |
| 59 | + }, |
| 60 | + nav: { |
| 61 | + home: "Home", |
| 62 | + about: "About" |
| 63 | + } |
| 64 | +} |
| 65 | +``` |
| 66 | + |
| 67 | +```typescript |
| 68 | +// messages/ja.ts |
| 69 | +export default { |
| 70 | + common: { |
| 71 | + title: "マイサイト", |
| 72 | + description: "サイトへようこそ" |
| 73 | + }, |
| 74 | + nav: { |
| 75 | + home: "ホーム", |
| 76 | + about: "概要" |
| 77 | + } |
| 78 | +} |
| 79 | +``` |
| 80 | + |
| 81 | +**2. Define i18n instance** |
| 82 | + |
| 83 | +Place this file anywhere in your project (`i18n.ts`, `lib/i18n.ts`, etc.) |
| 84 | + |
| 85 | +```typescript |
| 86 | +// i18n.ts |
| 87 | +import { define } from 'next-i18n-tiny' |
| 88 | +import enMessages from '@/messages/en' |
| 89 | +import jaMessages from '@/messages/ja' |
| 90 | + |
| 91 | +export type Locale = 'ja' | 'en' |
| 92 | +const locales: Locale[] = ['ja', 'en'] |
| 93 | +const defaultLocale: Locale = 'ja' |
| 94 | + |
| 95 | +const { client, server, Link, Provider } = define({ |
| 96 | + locales, |
| 97 | + defaultLocale, |
| 98 | + messages: { ja: jaMessages, en: enMessages } |
| 99 | +}) |
| 100 | + |
| 101 | +export { Link, Provider } |
| 102 | +export const { useMessages, useTranslations, useLocale } = client |
| 103 | +export const { getMessages, getTranslations } = server |
| 104 | +``` |
| 105 | + |
| 106 | +**3. Setup Proxy** (Next.js 16+) |
| 107 | + |
| 108 | +> For Next.js 15 or earlier, use `middleware.ts` instead. See [official migration guide](https://nextjs.org/docs/messages/middleware-to-proxy). |
| 109 | +
|
| 110 | +```typescript |
| 111 | +// proxy.ts |
| 112 | +import { NextRequest, NextResponse } from 'next/server' |
| 113 | + |
| 114 | +const locales = ['ja', 'en'] |
| 115 | +const defaultLocale = 'ja' |
| 116 | + |
| 117 | +export default function proxy(request: NextRequest) { |
| 118 | + const { pathname } = request.nextUrl |
| 119 | + |
| 120 | + // Check if pathname already has a locale |
| 121 | + const hasLocale = locales.some( |
| 122 | + (locale) => pathname.startsWith(`/${locale}/`) || pathname === `/${locale}` |
| 123 | + ) |
| 124 | + |
| 125 | + if (hasLocale) return |
| 126 | + |
| 127 | + // Redirect to default locale |
| 128 | + request.nextUrl.pathname = `/${defaultLocale}${pathname}` |
| 129 | + return NextResponse.redirect(request.nextUrl) |
| 130 | +} |
| 131 | + |
| 132 | +export const config = { |
| 133 | + matcher: ['/((?!api|_next|.*\\..*).*)'] |
| 134 | +} |
| 135 | +``` |
| 136 | + |
| 137 | +**4. Use in Layout** |
| 138 | + |
| 139 | +```typescript |
| 140 | +// app/[locale]/layout.tsx |
| 141 | +import { Provider, getMessages, type Locale } from '@/i18n' |
| 142 | + |
| 143 | +export default async function Layout({ children, params }) { |
| 144 | + const { locale } = await params |
| 145 | + const messages = await getMessages(locale) |
| 146 | + |
| 147 | + return ( |
| 148 | + <Provider locale={locale} messages={messages}> |
| 149 | + {children} |
| 150 | + </Provider> |
| 151 | + ) |
| 152 | +} |
| 153 | +``` |
| 154 | + |
| 155 | +**5. Use in Components** |
| 156 | + |
| 157 | +```typescript |
| 158 | +// Server Component |
| 159 | +import { getMessages, getTranslations, type Locale } from '@/i18n' |
| 160 | + |
| 161 | +export async function ServerComponent({ locale }: { locale: Locale }) { |
| 162 | + /* Direct object access */ |
| 163 | + const messages = await getMessages(locale) |
| 164 | + /* Function call */ |
| 165 | + const t = await getTranslations(locale) |
| 166 | + |
| 167 | + return ( |
| 168 | + <div> |
| 169 | + <h1>{messages.common.title}</h1> |
| 170 | + {/* ^^^^^ Auto-complete */} |
| 171 | + <p>{t('common.description')}</p> |
| 172 | + {/* ^^^^^^^^^^^^^^^^^^ Auto-complete */} |
| 173 | + </div> |
| 174 | + ) |
| 175 | +} |
| 176 | +``` |
| 177 | + |
| 178 | +```typescript |
| 179 | +// Client Component |
| 180 | +'use client' |
| 181 | +import { Link, useMessages, useTranslations } from '@/i18n' |
| 182 | + |
| 183 | +export function ClientComponent() { |
| 184 | + /* Direct object access */ |
| 185 | + const messages = useMessages() |
| 186 | + /* Function call */ |
| 187 | + const t = useTranslations() |
| 188 | + |
| 189 | + return ( |
| 190 | + <div> |
| 191 | + <h1>{messages.common.title}</h1> |
| 192 | + {/* ^^^^^ Auto-complete */} |
| 193 | + <Link href="/about">{t('nav.about')}</Link> |
| 194 | + {/* ^^^^^^^^^ Auto-complete */} |
| 195 | + </div> |
| 196 | + ) |
| 197 | +} |
| 198 | +``` |
| 199 | + |
| 200 | +That's it! **Types are automatically inferred** - no manual type annotations needed. |
| 201 | + |
| 202 | +**Two ways to access translations:** |
| 203 | + |
| 204 | +- `messages.common.title` - Direct object access (simple and clear) |
| 205 | +- `t('common.title')` - Function call (useful for dynamic keys) |
| 206 | + |
| 207 | +Both are fully typed with autocomplete. Use whichever you prefer! |
| 208 | + |
| 209 | +## API Reference |
| 210 | + |
| 211 | +### `define(config)` |
| 212 | + |
| 213 | +Defines an i18n instance with automatic type inference. |
| 214 | + |
| 215 | +**Parameters:** |
| 216 | + |
| 217 | +- `config.locales` - Array of supported locales |
| 218 | +- `config.defaultLocale` - Default locale |
| 219 | +- `config.messages` - Messages object keyed by locale |
| 220 | + |
| 221 | +**Returns:** |
| 222 | + |
| 223 | +```typescript |
| 224 | +{ |
| 225 | + Provider, // Context provider component |
| 226 | + Link, // Next.js Link with locale handling |
| 227 | + server: { |
| 228 | + getMessages, // Get messages object |
| 229 | + getTranslations // Get translation function |
| 230 | + }, |
| 231 | + client: { |
| 232 | + useMessages, // Get messages object (hook) |
| 233 | + useTranslations, // Get translation function (hook) |
| 234 | + useLocale // Get current locale (hook) |
| 235 | + } |
| 236 | +} |
| 237 | +``` |
| 238 | + |
| 239 | +## Technical Notes |
| 240 | + |
| 241 | +### Message Serialization |
| 242 | + |
| 243 | +This library uses `JSON.parse(JSON.stringify())` to convert ES module namespace objects to plain objects, ensuring React Server Components compatibility. |
| 244 | + |
| 245 | +### Link Component |
| 246 | + |
| 247 | +The `Link` component automatically handles both string paths and Next.js `UrlObject`: |
| 248 | + |
| 249 | +```typescript |
| 250 | +<Link href="/about">About</Link> |
| 251 | +<Link href={{ pathname: '/search', query: { q: 'test' } }}>Search</Link> |
| 252 | +``` |
| 253 | + |
| 254 | +Both will have the locale prefix automatically added based on the current locale. |
| 255 | + |
| 256 | +## License |
| 257 | + |
| 258 | +MIT |
0 commit comments