Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Getting started

Install i18next with npm or a CDN script, initialize it with resources, and call t() in Node.js, the browser or any framework.

🤖 Using a coding agent? Paste this prompt into Claude Code, Cursor, Codex, GitHub Copilot, Gemini CLI or any agent that can run terminal commands:

Localize this app with i18next.
Run `npx i18next-cli localize --print-agent-prompt` and follow
the steps it prints, in order, checking each one before the next.

You review the diff, and the translation files stay in your repository unless you choose otherwise. ⇒ What the prompt tells your agent

Installation

i18next can be added to your project using npm or yarn:

# npm
$ npm install i18next --save

# yarn
$ yarn add i18next

The default export is UMD compatible (commonjs, requirejs, global).

In the /dist folder you may find additional builds for commonjs, es6 modules. Optimized to load i18next in webpack, rollup, ... or node.js. The correct entry points are already configured in the package.json so there should be no extra setup to get the best build option.

Load in Deno

i18next can be imported like this:

import i18next from '@i18next/i18next' // when installed via JSR: deno add jsr:@i18next/i18next
// or import i18next from 'https://raw.githubusercontent.com/i18next/i18next/master/src/index.js'
// or import i18next from 'https://cdn.jsdelivr.net/gh/i18next/i18next/src/index.js'

Load from CDN

You can also directly add a script tag loading i18next from one of the CDNs providing it:

unpkg.com

esm or cjs:

Make sure to use a fixed version in production like https://unpkg.com/[email protected]/dist/umd/i18next.js as passing no version will redirect to latest version which might contain breaking changes in future.

cdnjs.com

jsdelivr.com

Important Caveat

Before we dive into the first sample, please note the following: By default, i18next uses a key-based notation to look up translations, which comes with the benefit of additional structure for your translation files.

The downside of this is that your keys must not be in natural language — the names of the keys are not used as fallback content and the key names must not include reserved characters : and . since those are used by i18next.

If you prefer using natural language in keys, please read the fallback guide.

Basic sample

Please be aware these samples are just showing basic usage of the core functionality. For production usage please consider using one of our framework integrations to get better and simpler integrations (Setting innerHTML is just done to show how it works).

Or using callback init signature:

Or using Promises:

Or using async/await:

if you are lazy loading the translation resources, you may need to wait for i18next to have finished to initialize.

As you might see, this basic sample provides only one language directly added on init… let's extend this to have buttons to change language from English to German:

source code

Do you quickly want to translate your resources to other languages? Try: https://translate.i18next.com

Want to check your files for missing translations or interpolation errors? Try the free i18n health check.

Starting from an app full of hardcoded strings? Run the free i18n readiness check on your GitHub repository.

This is a working sample showing translated text. To learn more, have a look at the following extended sample:

Extended sample

The extended sample adds the language detector for our browser and the http-backend to load translation files from this documentation's i18next-gitbook repo.

source code

Choose your message syntax

The samples above use the i18next JSON format. Two plugins let you write your messages in another syntax instead. Pick one before your translation files grow: switching later means converting every message, and one i18next instance uses one syntax.

i18next JSON (the default) uses {{name}} for values and key suffixes for plurals and context:

Pick it unless you have a reason not to. Every i18next feature, plugin and tool supports it, including nesting, formatting, context and i18next-cli.

ICU MessageFormat via i18next-icu puts plurals and selects into the message:

Pick it if your translations are already in ICU, if your translators or translation management system expect ICU, or if you share messages with other ICU based libraries like FormatJS.

MessageFormat 2 (MF2) via i18next-mf2 is the Unicode successor of ICU MessageFormat:

Pick it if you start fresh and want the newer Unicode standard. Check first that your translation tools can handle MF2 messages.

With all three, i18next.t('photos', { count: 3 }) returns "You have 3 photos.". ICU and MF2 replace i18next's own message handling, so plural and context suffix keys, $t() nesting, i18next formatters and returnObjects stop working. Read Using ICU or MF2 before you switch.

You should now have an idea about how to achieve the basic setup. It's time to learn more about:

Last updated