https://github.com/jon1vk/nextglobegen
Internationalization (i18n) library for Next.js App Router
https://github.com/jon1vk/nextglobegen
i18n internationalization localization nextjs react
Last synced: about 1 month ago
JSON representation
Internationalization (i18n) library for Next.js App Router
- Host: GitHub
- URL: https://github.com/jon1vk/nextglobegen
- Owner: Jon1VK
- License: mit
- Created: 2024-12-04T14:10:09.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-05-02T14:37:56.000Z (11 months ago)
- Last Synced: 2025-07-05T06:54:07.482Z (9 months ago)
- Topics: i18n, internationalization, localization, nextjs, react
- Language: TypeScript
- Homepage: https://next-globe-gen.dev/
- Size: 1.23 MB
- Stars: 22
- Watchers: 1
- Forks: 4
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
NextGlobeGen
NextGlobeGen makes it effortless to deliver your content in multiple languages with SEO-optimized, localized URLs.
NextGlobeGen is a powerful TypeScript-first internationalization (i18n) library for Next.js App Router applications. Unlike traditional i18n solutions, NextGlobeGen uses **generative programming** to automatically create localized routes and type-safe APIs, giving you a seamless development experience with full TypeScript support.
## Why NextGlobeGen?
### 🎯 Developer Experience First
- **Zero Runtime Overhead** - Routes are generated at build time, not runtime
- **Type-Safe Everything** - Full TypeScript inference for routes, locales, and messages
- **Universal API** - Same hooks and components work in both server and client components
- **Hot Reloading** - Changes to routes and messages regenerate automatically
### 🚀 Production Ready
- **SEO Optimized** - Automatic language alternate links and localized pathnames
- **Performance** - Code splitting support with filtered message delivery
- **Flexible Routing** - Support for prefix-based and domain-based locale routing
- **Next.js Native** - Built specifically for Next.js App Router with full feature support
### 💪 Powerful Features
- **Automatic Key Extraction** - Automatically discover translation keys from your source code
- **ICU Message Format** - Rich text formatting with plurals, dates, numbers, and embedded React components
- **Localized Pathnames** - Translate URL segments for better SEO (e.g., `/en/about` → `/fi/tietoja`)
- **Smart Locale Detection** - Automatic user locale negotiation with cookie persistence
- **Dynamic Routes** - Full support for dynamic segments, catch-all routes, and parallel routes
## Quick Example
```tsx
import { useTranslations, Link } from "next-globe-gen";
export default function HomePage() {
const t = useTranslations();
return (
{t("welcome")}
{t("description", { name: "NextGlobeGen" })}
{t("dashboard.title")}
);
}
```
```json
{
"welcome": "Welcome!",
"description": "{name} makes i18n effortless",
"dashboard": {
"title": "Dashboard"
}
}
```
This automatically works for all configured locales with zero additional code!
## Key Features
### Generative Locale Routes
The plugin watches your `src/_app` directory and automatically generates localized versions of your routes in real-time:
```
src/_app/about/page.tsx → src/app/(i18n)/en/about/page.tsx
→ src/app/(i18n)/fi/tietoja/page.tsx
```
No manual route duplication. No runtime route matching. Just write your routes once, and NextGlobeGen handles the rest.
### Type-Safe API
Get full TypeScript support across your entire i18n implementation:
```tsx
// Routes are type-checked
Post
;
// Message keys are autocompleted
const t = useTranslations("dashboard");
t("title"); // ✓ Type-safe
t("typo"); // ✗ TypeScript error
// Locale switching with preserved params
const route = useRoute(); // Type: "/blog/[slug]"
const params = useParams>();
Suomeksi
;
```
### ICU Message Format
Support for rich text formatting with plurals, select, dates, and React components:
```json
{
"welcome": "Welcome {name}!",
"posts": "{count, plural, =0 {No posts} one {One post} other {# posts}}",
"updated": "Last updated: {date, date, long}",
"richText": "Read our guide for more info"
}
```
```tsx
t("welcome", { name: "Jon" });
t("posts", { count: 5 });
t("updated", { date: new Date() });
t("richText", { link: (children) => {children} });
```
### Automatic Key Extraction
NextGlobeGen automatically scans your source files and extracts translation keys, keeping your message files in sync with your code:
```tsx
// Keys are automatically extracted from your source files
const t = useTranslations("home");
t("title"); // Extracted as "home.title"
t("welcome", { _defaultMessage: "Welcome!" }); // Extracted with default message
```
Configure extraction behavior in your config:
```ts
const config = {
messages: {
keyExtractionDirs: ["./src"], // Directories to scan
pruneUnusedKeys: true, // Remove keys no longer in code
whitelistedKeys: [/^dynamic\./], // Protect dynamic keys from pruning
},
};
```
### Flexible Routing Options
Choose the routing strategy that fits your needs:
**Prefix-Based Routing** (e.g., `example.com/en`, `example.com/fi`)
```ts
const config = {
locales: ["en", "fi"],
defaultLocale: "en",
prefixDefaultLocale: true, // or false for root default locale
};
```
**Domain-Based Routing** (e.g., `example.com`, `example.fi`)
```ts
const config = {
domains: [
{ domain: "example.com", locales: ["en"], defaultLocale: "en" },
{ domain: "example.fi", locales: ["fi"], defaultLocale: "fi" },
],
};
```
### Smart Middleware
The included proxy/middleware handles:
- **Locale Negotiation** - Detects user's preferred language from Accept-Language header
- **Cookie Persistence** - Remembers user's language choice
- **Alternate Links** - Adds SEO-friendly language alternate links to response headers
- **Domain Routing** - Redirects users to the correct domain based on locale
### Server & Client Components
The same API works everywhere:
```tsx
// "use client"; just add this directive for Client Components
import { useLocale, useTranslations } from "next-globe-gen";
export default function ServerComponent() {
const locale = useLocale();
const t = useTranslations();
return
{t("title")}
;
}
```
Need async functions? Use the `get*` aliases:
```tsx
export async function generateMetadata() {
const t = getTranslations();
return { title: t("pageTitle") };
}
```
## Getting Started
Ready to internationalize your Next.js app? Follow our [Getting Started Guide](https://next-globe-gen.dev/docs/getting-started) to set up NextGlobeGen in minutes.
### Coming from next-intl?
If you're familiar with next-intl or considering alternatives, check out our [detailed comparison](https://next-globe-gen.dev/docs/comparison-with-next-intl) to understand the differences and see which approach fits your project best.