# Acknowledgment URL: /docs/acknowledgment Acknowledgment, references, and links for Intl-T *** title: Acknowledgment description: Acknowledgment, references, and links for Intl-T ------------------------------------------------------------- ## References ### Acknowledgment * [dx\_over\_dt's Stack Overflow answer,](https://stackoverflow.com/a/64418639/29393046) demonstrates how to override the `[Symbol.iterator]` method of a `String` object to prevent character-by-character rendering in React. This idea helped shape earlier versions of Intl-T. * [Kent C. Dodds's blog post,](https://kentcdodds.com/blog/rendering-a-function-with-react) explores a clever way to trick React into rendering functions as children. Although, this approach is no longer supported due to `react-reconciler`. It provides historical context that eventually led to the strategy used in Intl-T. ### Mentions * Featured in [Next.js Weekly issue #90](https://nextjsweekly.com/issues/90) as an unique node-based system for organizing translations * [First Reddit Post](https://www.reddit.com/r/nextjs/comments/1l6x8wg/i_develop_a_fullytyped_objectbased_i18n) shared on r/nextjs, introducing `intl-t` and received feedback from the community. *** ## Links *** # Contributing URL: /docs/contributing Ideas and plans for future features and improvements *** title: Contributing description: Ideas and plans for future features and improvements ----------------------------------------------------------------- ## Guidelines Contributions are welcome! If you have ideas, suggestions, or improvements, feel free to open an issue or pull request. ## Roadmap Here are some planned features and improvements for future: * **Translations Merging:** Support for dynamically merging and extending translation namespaces for each independent node in the tree, enabling on-demand loading and updates. * **CLI Tooling:** Command-line utilities for managing, validating, and extracting translations. * **Documentation Web:** A web-based documentation site for Intl-T, providing examples, guides, and API references. * **Documentation Enhancement:** Improve docs such as `AGENTS.md`, `CONTRIBUTING.md` to provide clearer and more practical guidance for contributors. * **Editor Integrations:** VSCode plugin for enhanced translation management. * **Improved ICU Support:** More advanced ICU message format features. * **Performance Optimizations:** Further reduce bundle size and improve runtime efficiency. * **Plugins:** Support for third-party plugins and integrations. * **Testing:** Add robust testing for Intl-T to ensure its reliability. * **More frameworks:** Support for more popular frameworks and libraries, including backend frameworks. * **Implement new features:** For example, localization for pathnames. * **Modular and agnostic:** To ensure agnosticism, Intl-T will be a monorepo with separate modules for different environments and features (e.g., `@intl-t/next`, `@intl-t/utils`, `@intl-t/server`, etc.) * **Intl-T Server:** Easily self-host translations with a simple API that is agnostic and compatible with the intl-t client. * **Intl-T l10n Service:** A simple service for providing translation management to your application through intl-t API. * **Crowdin Integration:** Integration with Crowdin for efficient translation management and dynamic loading. * **TypeScript Augmentation:** Allow augmenting the `intl-t` module so the default `t` object can be imported directly from the package with full type inference. ### Progress Table 🔴 Planned 🟡 In Progress 🔵 Almost there 🟢 Completed | Feature | Status | | --------------------------------- | ------ | | Modular and agnostic | 🔵 | | Translations Merging | 🔴 | | CLI Tooling | 🔴 | | Documentation web | 🟢 | | Documentation enhancement | 🟡 | | Edge Runtime Support | 🔵 | | IDE Integration | 🔴 | | Improved ICU Support | 🔴 | | Performance Optimizations | 🔴 | | Testing | 🟡 | | More frameworks support | 🔴 | | `@intl-t/server` | 🔴 | | Intl-T Service | 🔴 | | Crowdin Integration | 🔴 | | Enhance dynamic import strategies | 🔴 | | TypeScript Augmentation | 🔴 | | Enhance TypeScript type inference | 🔴 | | Debugging | 🔴 | | Plugins | 🔴 | Have a feature request? [Open an issue](https://github.com/nivandres/intl-t/issues) or join the [Discord](https://discord.gg/5EbCXKpdyw). # Dynamic Import URL: /docs/dynamic-import Load locales dynamically *** title: Dynamic Import description: Load locales dynamically ------------------------------------- > Dynamic Import There are several ways to dynamically import locales. Dynamic locale importing consists in loading only the translations you actually need. You may not need to use dynamic importing, but if you do, please read this section carefully for a complete overview. ## Nodes as dynamic functions To dynamically import locales, set node values as functions to be called when needed. ```ts import { Translation } from "intl-t"; export const t = new Translation({ locales: { en: () => import("./en.json"), es: () => import("./es.json"), }, }); await t; // Automatically imports the locale that is needed at client or server ``` ```ts import { createTranslation } from "intl-t"; // use await at createTranslation to preload default locale export const { t } = await createTranslation({ locales: { en: () => import("./en.json"), es: () => import("./es.json"), }, hydration: false, // disable hydration to automatically load the correct client locale }); // This is not recommended for hydration environments ``` Or you can import the locales dynamically and assert the type in this way. ```ts type Locale = typeof import("./en.json"); createTranslation({ locales: locale => import(`./${locale}.json`) as Promise, // default type is inferred allowedLocales: ["en", "es"], // It is important to specify locales }); ``` ## `getLocales` function `getLocales` function is a way to preload locales dynamically depending if it is client or server. If you are invoking from server it preloads with a top-level await, but if you are invoking from client it will dynamically import the locales. If you are using [static rendering](/docs/next#static-rendering) with [React Provider](/docs/react#provider), the right locale will be automatically handled and sent to the client. ```ts import { createTranslation, getLocales } from "intl-t"; // `allowedLocales` as locale list, e.g. ["en", "es"] as const; !important use `as const` import { allowedLocales } from "./locales"; const locales = await getLocales(locale => import(`./messages/${locale}.json`), allowedLocales); // Preload locales at server and dynamically imported at client export const { t } = createTranslation({ locales }); ``` `getLocales(cb, locales, preload?)` If your import function doesn't return the type directly, you can assert it in this way. ```ts type Locale = typeof import("./messages/en.json"); await getLocales(locale => import(`./messages/${locale}.json`) as Promise, allowedLocales); ``` `getLocales` function also supports preloading locales with locales record. `{ en: [AsyncFunction] }` `getLocales(locales record, list?, preload?)` ## Preload Locales Preload option is a way to implement `getLocales` function directly at create translation, instead of using `await getLocales` you will use `await` directly on the translation object. ```ts await createTranslation({ locales: locale => import(`./messages/${locale}.json`) as Promise, preload: true, // e. g. preload all locales depending if is server or whichever condition }); ``` Actually when using locales as callback, it will automatically turn on preload and use !isClient as default condition. ```ts await createTranslation({ locales: { en: () => ({ hello: "Hello World!" }), es: new Promise(r => r({ hello: "¡Hola Mundo!" })) as { hello: "¡Hola Mundo!" }, // intl-t supports promises but it is need to assert the type fr: async () => ({ hello: "Bonjour le monde!" }), ja: { hello: "こんにちは世界！" }, }, preload: true, // preloads all locales when using `await` }); ``` When `preload` is enabled, the first `await` invocation will preload all locales. By default, if `preload` is not specified and you use `await`, only the current locale is preloaded. Additionally, if you provide a callback for `locales`, `preload` is enabled automatically and all locales are preloaded on the server by default. Enabling `preload` turns the top-level translation object into a promise that resolves when all locales are loaded. Therefore, if you enable `preload`, remember to use `await` with `createTranslation`. In this case, you cannot use the `new Translation` syntax, as you cannot use `await` with `new`. However, intl-t is flexible: if you enable `preload` but do not use `await`, it will behave as a normal translation object without preloading. You can simply use `await` on the specific locales you need. (But it is the same as having `preload: false`) ```ts const t = createTranslation({ locales: { en: async () => ({ hello: "Hello World!" }), es: async () => ({ hello: "¡Hola Mundo!" }), fr: () => ({ hello: "Bonjour le monde!" }), ja: async () => ({ hello: "こんにちは世界！" }), }, preload: false, // preloads all locales when using top-level `await` }); t.hello; // undefined (await t.es).hello; // "¡Hola Mundo!" t.fr.hello; // "Bonjour le monde!" // It works because it is just a function without promise (await t.en).hello; // "Hello World!" // `t.en` It is being preloaded without preloading the rest of locales, even when preload is on, because it is being used after accessing the specific locale (await t.es).hello; // "¡Hola Mundo!" // Already resolved, it doesn't do unnecessary reloads ``` You can test and debug the locale loads in the console and you can see the locales being loaded and resolved. Not repeated nodes, not unnecessary reloads, just the same independent nodes, proxies, instances, values and locales. ## Server-Side importing A way to preload all locales at server is to separate the translations into different files and import them at the server. Client or server file: ```ts title="i18n/translation.ts" import { createTranslation } from "intl-t/next"; export const { t } = await createTranslation({ locales: {} as { es: typeof import("./messages/es.json"); en: typeof import("./messages/en.json"); }, allowedLocales: ["en", "es"], // It is important to specify in this case }); ``` Only server file: ```ts title="i18n/server.ts" import en from "./messages/en.json"; import es from "./messages/es.json"; import { t } from "./translation"; t.en.setSource(en); t.es.setSource(es); // or t.settings.getLocale = locale => import(`./messages/${locale}.json`); ``` Then in your server-side code. It could be only the root layout, API endpoints and server actions. ```tsx import { Translation } from "./i18n/server"; export default function RootLayout({ children }) { return ( {/* Automatically send the translations to the client */} {children} ); } ``` This method is not totally recommended due to some errors when building with Next.js. It is a example of how flexible you can handle your translations and dynamic loads and imports. If you're getting started with `intl-t` and dynamic imports, you may want to begin by [setting nodes as dynamic functions](#nodes-as-dynamic-functions). Some of these dynamic locales importing strategies are unstable and may not work as expected. You may find the next error when building with Next.js: > Linting and checking validity of types ..Debug Failure. False expression. > Next.js build worker exited with code: 1 and signal: null > error: script "build" exited with code 1 This occurs when using `import("...")` and `bundle` module resolution in `tsconfig.json`. In this case, you can disable typescript check with Next.js ```ts title="next.config.js" const nextConfig = { typescript: { ignoreBuildErrors: true, }, }; ``` Or use `import en from "./en.json"` instead of `await import("./en.json")`. # Edge URL: /docs/edge Special Edge Runtimes Compatibility Warning *** title: Edge description: Special Edge Runtimes Compatibility Warning -------------------------------------------------------- ### Edge Runtimes Compatibility Warning Edge environments, such as Cloudflare Workers, Vercel Edge Functions, and Cloudflare Pages, are only partially supported and have various limitations and caveats. Since `new Function` cannot be executed in edge environments, Translation Node Proxies created from a new function cannot be functions anymore. This means you won't be able to call them directly. Instead, you'll need to use methods like `.use` or `.get` to perform actions. Also some variable injections may not work as expected. ```ts // From const t = getTranslation(); t("hello"); t.greetings({ name: "John" }); // To const t = getTranslation(); // Also hooks lose their proxy properties t.get("hello"); // or t.hello t.greetings.use({ name: "John" }); // .use and .get are the same ``` The upside is that, since these proxies become string objects rather than function objects, this offers better compatibility in some environments and eliminates the need for workarounds such as React Patch. However, this limitation only applies to edge environments. The current solution is a temporary workaround. In the future, full compatibility will be achieved, as there are ways in JavaScript that can provide the desired behavior and even allow you to choose between string objects or function objects as needed, thus avoiding the need for workarounds like the React Patch. # Examples & Strategies URL: /docs/examples Practical patterns and edge cases *** title: Examples & Strategies description: Practical patterns and edge cases ---------------------------------------------- ## Locales metadata You can include metadata in your translation files to help you with localization and translation management. For example ```jsonc { "meta": { // It is a normal node "code": "en", "name": "English", "dir": "ltr", }, // ... } ``` And then you can access it from your translations. ```tsx import { Translation, t } from "@/i18n/translation"; import { match } from "intl-t/utils"; interface Props { params: Promise<{ locale: string }>; } export default function RootLayout({ children, params }) { let { locale } = await params; locale = match(locale, t.allowedLocales); const { meta } = await t[locale]; // Preload if you are using dynamic import without TranslationProvider that will preload translations return ( {children} ); } ``` ## Fallbacks When a translation node is executed and the translation is not found, it will fall back to the input text with injected variables. This could be useful when you receive a string from an external API or server. You might get either a translation key or the direct text. ```ts t("Please try again"); // falls back to "Please try again" t("messages.try_again"); // outputs the translation t("Please try again, {name}", { name: "John" }); // falls back to "Please try again, John" // these fallbacks are also type safe typeof t("Please try again, {name}"); // `Please try again, ${string}` ``` ## String Methods ```tsx {t.description.split(" ").map((word, index, words) => { return ( {word + " "} ); })} ``` ## Template Strings ```tsx async function Greeting() { "use server"; return t`greeting`({ name: await getName() }); } ``` ## Namespaces Namespaces are a way to simulate isolated translation contexts in your application. While intl-t does not natively support namespaces as a built-in feature, you can achieve similar separation by organizing your translation files and configuration per feature or section. For example, you might have: `app/protected/i18n/translation.ts` `i18n/translation.ts` `app/docs/i18n/translation.ts` Each of these files can export its own translation instance: ```ts title="protected/i18n/translation.ts" import { createTranslation } from "intl-t"; import en from "./locales/en.json"; export const { t: protectedT } = createTranslation({ locales: { en } }); ``` ```ts title="docs/i18n/translation.ts" import { createTranslation } from "intl-t"; import en from "./locales/en.json"; export const { t: docsT } = createTranslation({ locales: { en } }); ``` You can then import and use the appropriate translation object in each part of your app: ```ts import { docsT } from "../../docs/i18n/translation"; import { protectedT } from "../i18n/translation"; protectedT("dashboard.title"); docsT("guide.intro"); ``` Renaming is not required; this is just for demonstration purposes. Simply import from the appropriate folders. If you are sending translations dynamically to the client via React, you must use a [`TranslationProvider`](/docs/react#provider) for each isolated translation instance. You can also implement different strategies for each isolated translation, such as using only [dynamic](/docs/next/dynamic-rendering) translation loading or preloading at server-side and dynamically importing at client-side. **This approach keeps translations isolated. In the future, intl-t may support merging or extending translations dynamically, but for now, this pattern allows you to simulate namespaces effectively.** # Overview URL: /docs Introduction for Intl-T *** title: Overview description: Introduction for Intl-T ------------------------------------ ## Intl-T `intl-t` is a fully-typed, object-based internationalization (i18n) library for TypeScript, React, and Next.js. It offers a type-safe and amazing developer experience for managing translations in modern applications. ![Banner](https://raw.githubusercontent.com/nivandres/intl-t/main/assets/banner.webp) > A Fully-Typed Object-Based i18n Translation Library for TypeScript, React, and Next.js. ### Features * 🎯 Fully-Typed for TypeScript with autocomplete for translation variables * 🌲 Node-based translations for easy organization and management * ✨ Type-safe translation keys, values and all sub-nodes * 🚚 Supports JSON files and dynamic remote imports * 🪄 Flexible syntax integrating all the best parts of other i18n libraries * 🧩 ICU message format support and extended for complex and nested pluralization and formatting * ⚛️ React components injections out of the box with translation variables * 🚀 Supports server-side rendering and static rendering with Next.js and React * 🔄 Dynamic importing of locales for optimized bundle size and on-demand language loading * ⚙️ Modular and agnostic to any framework or library * 📦 Lightweight bundle with no dependencies and Tree-Shakable ## Demo

```ts twoslash include demo import { Translation } from "intl-t"; // ---cut-start--- const en = { title: "Homepage", welcome: "Welcome, {user}!", summary: "{count, plural, =0 {no items} one {# item} other {# items}}", main: "It is {now, date, sm}", features: [ "Hi {name}. This is Feature 1", "Hi {name}. This is Feature 2", "Hi {name}. This is Feature 3", { base: "Hi {name}. This is Feature 4 with html title", title: "Feature 4", }, ], page1: { section1: { article1: { title: "Article 1", }, }, }, account: { options: { change: "Change your account settings. Your account id is {accountId}", }, values: { accountId: 0, }, }, copyright: "Copyright © 2025", values: { user: "World", name: "{user}", now: "{(Date.now())}", }, } as const; // ---cut-end--- export const { useTranslation } = new Translation({ locales: { en } }); // - config // ---cut--- // - usage ```

```tsx twoslash title="page.tsx" import React from "react"; interface Props { data: {}; } // @include: demo-usage export default function HomePage({ data }: Props) { const { t } = useTranslation(); return ( <>

{t("title")}

{/* Get translations as an object or function */}

{t.title}

{/* Use variables in your translations */} {t("welcome", { user: "Ivan" })} {t.summary(data)} {/* Flexible syntax */}

{t("main", { now: Date.now() })}

{t.features[0]}
{t("features.1", { name: "Ivan V" })}
{t("features")[2]({ name: "Ivan V" })}
{t({ name: "Ivan V" }).features("3")}

{/* Node-based translations */}

{t.page1.section1.article1.title}

{t("page1.section1").article1("title")}

{/* Full typesafe with completion for variables */}

{t({ day: "Monday" }).account(data).options.change}

); } ``` ```jsonc title="en.json" { "title": "Homepage", "welcome": "Welcome, {user}!", // support ICU message format "summary": "{count, plural, =0 {no items} one {# item} other {# items}}", // ICU Format Extended "main": "It is {now, date, sm}", "features": [ "Hi {name}. This is Feature 1", "Hi {name}. This is Feature 2", "Hi {name}. This is Feature 3", { "base": "Hi {name}. This is Feature 4 with html title", // base is default text for objects "title": "Feature 4", }, ], "page1": { "section1": { "article1": { "title": "Article 1", }, }, }, "account": { "options": { "change": "Change your account settings. Your account id is {accountId}", }, "values": { // default values for this node "accountId": 0, }, }, "copyright": "Copyright © 2025", "values": { // default values "user": "World", "name": "{user}", // inject code "now": "{(Date.now())}", }, } ``` ```ts twoslash title="translation.ts" // @include: demo-config ``` ## Why Intl-T? > Why Intl-T instead of Other i18n Libraries Intl-T was created out of frustration with the limitations and poor DX of existing i18n solutions. Although they offer different features, none of them deliver the optimal developer experience. Many require excessive boilerplate code, lack robust type safety, or lack key conveniences. Intl-T combines the best features of all of them to provide a super robust, solid, fully-typed, and streamlined solution that focuses on providing the best possible developer experience that we all want. Intl-T is designed to be: * **Fully type-safe**: Enjoy 100% TypeScript autocompletion everywhere for translations, keys, variables and more. * **Minimal and dependency-free**: No extra dependencies or complex setup. Just import and use. * **Node-based and flexible**: Organize translations in a powerful, deeply nested object structure. * **Seamless with React and Next.js**: Integrates out of the box with modern frameworks. Such as React with super powerful [Component Injection](/docs/react#react-component-injection) and Next.js with [Navigation](/docs/next#navigation). * **Lightweight**: Small bundle size, optimized for performance. * **Rich API**: Access translations as functions, objects, or strings, with dynamic variable injection and ICU support. * **Easy migration and adaptation**: Supports most popular i18n formats, key aliases, and usage patterns, making it simple to migrate from other libraries or integrate with existing translation files. If you want a simple, robust, and modern i18n library that puts developer experience first, give Intl-T a try. Feedback is welcome! ```tsx // Flexible Syntax t("welcome"); t.welcome ``` *** *** # Migration Guide URL: /docs/migration Migrate from other i18n libraries to Intl‑T *** title: Migration Guide description: Migrate from other i18n libraries to Intl‑T -------------------------------------------------------- Before migrating, make sure you understand the core concepts of intl-t. See the [Basic Usage](/docs/node) section for details. ## 1. **Prepare your translations** `intl-t` supports flexible JSON files with deeply nested nodes. However, you should review the [Reserved Keywords](/docs/node#reserved-keywords) before using them in your translations. All locale translation files must have the same structure, keys, and nodes. `intl-t` will warn you if there are any discrepancies. ```jsonc // en.json { "homepage": { "welcome": "Welcome, {user}!", } } // es.json { "homepage": { "welcome": "Bienvenido, {user}!", } } ``` It's recommended to have a central translation meta file for general data, such as `allowedLocales` and `defaultLocale`. This is useful for navigation and middleware. ```ts title="i18n/locales.ts" export const allowedLocales = ["en", "es"]; ``` ## 2. **Set up your translation configuration** Use async createTranslation with the `locales` option as a function to preload locales on the server and dynamically import them on the client. ```ts title="i18n/translation.ts" import { createTranslation, getLocales } from "intl-t/next"; import { allowedLocales } from "./locales"; type Locale = typeof import("./messages/en.json"); export const { Translation, useTranslation, getTranslation } = await createTranslation({ allowedLocales, locales: locale => import(`./messages/${locale}.json`) as Promise, }); ``` If you want to use type declarations for each locale, you should set up the configuration as follows: ```ts title="i18n/translation.ts" import { createTranslation, getLocales } from "intl-t/next"; import { allowedLocales } from "./locales"; export const t = createTranslation({ locales: { en: () => import("./messages/en.json"), es: () => import("./messages/es.json"), // ... }, }); ``` You can generate literal string declarations for your JSON files using [`generateDeclarations`](/docs/typescript#declarations) function. ```ts title="next.config.js" import { generateDeclarations } from "intl-t/declarations"; generateDeclarations("messages"); ``` If you're using Next.js in production, you may need to patch React to support translation objects: ```ts title="i18n/patch.ts" import patch from "intl-t/patch"; import React from "react"; import jsx from "react/jsx-runtime"; process.env.NODE_ENV !== "development" && patch(React, jsx); ``` Then import this patch at the top of your translation file: ```ts title="i18n/translation.ts" import "./patch"; // ... ``` ## 3. **Configure navigation** ```ts title="i18n/navigation.ts" import { createNavigation } from "intl-t/navigation"; import { allowedLocales } from "./locales"; export const { middleware, generateStaticParams, Link, redirect, useRouter } = createNavigation({ allowedLocales }); ``` ```ts title="middleware.ts" export { middleware as default } from "@/i18n/navigation"; export const config = { matcher: ["/((?!api|static|.*\\..*|_next).*)"], }; ``` > To customize the `intl-t` middleware, you can extract `withMiddleware` function to wrap the function in a chain or as needed. `middleware(request, event, response)` [See the complete navigation documentation in the Navigation section.](/docs/next#navigation) ## 4. **Set up your root layout** By default, the locale is managed using the `[locale]` route parameter. However, you can fully customize this behavior. For example, you can get the locale dynamically from headers, detect the domain, geolocation, or custom HTTP Request. See the [Navigation](/docs/next#navigation) section for more details. There is also a mini example in the [dynamic rendering with Next.js](/docs/next#dynamic-rendering) section that shows how to avoid using the `[locale]` param by detecting the locale from headers. `/app/[locale]/...` ```tsx title="app/[locale]/layout.tsx" import { Translation } from "@/i18n/translation"; import { setRequestLocale } from "intl-t/next"; export { generateStaticParams } from "@/i18n/navigation"; interface Props { params: Promise<{ locale: typeof Translation.locale }>; children: React.ReactNode; } export default async function RootLayout({ children, params }: Props) { const { locale } = await params; if (!Translation.locales.includes(locale)) return; setRequestLocale(locale); return ( {children} ); } ``` ## 5. **Use translations in your code** **With React Server Components (Static):** ```tsx import { getTranslation } from "@/i18n/translation"; export default function Component() { const t = getTranslation(); return