# Getting started
## Installation
i18next can be added to your project using **npm** or **yarn**:
```bash
# 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](https://deno.land/)
i18next can be imported like this:
```javascript
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'
```
{% hint style="success" %}
In [this tutorial blog post](https://locize.com/blog/i18n-for-deno-with-i18next/) you can check out how this works.[
](https://locize.com/blog/i18n-for-deno-with-i18next/)[](https://locize.com/blog/i18n-for-deno-with-i18next/)
{% endhint %}
## 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 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](https://www.i18next.com/translation-function/essentials) 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](https://www.i18next.com/principles/fallback#key-fallback).
## 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](https://www.i18next.com/overview/supported-frameworks) to get better and simpler integrations (Setting innerHTML is just done to show how it works).
{% tabs %}
{% tab title="JavaScript" %}
```javascript
import i18next from 'i18next';
i18next.init({
lng: 'en', // if you're using a language detector, do not define the lng option
debug: true,
resources: {
en: {
translation: {
"key": "hello world"
}
}
}
});
// initialized and ready to go!
// i18next is already initialized, because the translation resources where passed via init function
document.getElementById('output').innerHTML = i18next.t('key');
```
{% endtab %}
{% tab title="TypeScript" %}
```typescript
import i18next from 'i18next';
i18next.init({
lng: 'en', // if you're using a language detector, do not define the lng option
debug: true,
resources: {
en: {
translation: {
"key": "hello world"
}
}
}
});
// initialized and ready to go!
// i18next is already initialized, because the translation resources where passed via init function
document.getElementById('output').innerHTML = i18next.t($ => $.key);
```
{% endtab %}
{% endtabs %}
Or using callback init signature:
{% tabs %}
{% tab title="JavaScript" %}
```javascript
import i18next from 'i18next';
i18next.init({
lng: 'en', // if you're using a language detector, do not define the lng option
debug: true,
resources: {
en: {
translation: {
"key": "hello world"
}
}
}
}, function(err, t) {
// initialized and ready to go!
document.getElementById('output').innerHTML = i18next.t('key');
});
```
{% endtab %}
{% tab title="TypeScript" %}
```typescript
import i18next from 'i18next';
i18next.init({
lng: 'en', // if you're using a language detector, do not define the lng option
debug: true,
resources: {
en: {
translation: {
"key": "hello world"
}
}
}
}, function(err, t) {
// initialized and ready to go!
document.getElementById('output').innerHTML = i18next.t($ => $.key);
});
```
{% endtab %}
{% endtabs %}
Or using Promises:
{% tabs %}
{% tab title="JavaScript" %}
```javascript
i18next.init({
lng: 'en', // if you're using a language detector, do not define the lng option
debug: true,
resources: {
en: {
translation: {
"key": "hello world"
}
}
}
}).then(function(t) {
// initialized and ready to go!
document.getElementById('output').innerHTML = i18next.t('key');
});
```
{% endtab %}
{% tab title="TypeScript" %}
```typescript
i18next.init({
lng: 'en', // if you're using a language detector, do not define the lng option
debug: true,
resources: {
en: {
translation: {
"key": "hello world"
}
}
}
}).then(function(t) {
// initialized and ready to go!
document.getElementById('output').innerHTML = i18next.t($ => $.key);
});
```
{% endtab %}
{% endtabs %}
Or using async/await:
{% tabs %}
{% tab title="JavaScript" %}
```javascript
await i18next.init({
lng: 'en', // if you're using a language detector, do not define the lng option
debug: true,
resources: {
en: {
translation: {
"key": "hello world"
}
}
}
});
// initialized and ready to go!
document.getElementById('output').innerHTML = i18next.t('key');
```
{% endtab %}
{% tab title="TypeScript" %}
```typescript
await i18next.init({
lng: 'en', // if you're using a language detector, do not define the lng option
debug: true,
resources: {
en: {
translation: {
"key": "hello world"
}
}
}
});
// initialized and ready to go!
document.getElementById('output').innerHTML = i18next.t($ => $.key);
```
{% endtab %}
{% endtabs %}
{% hint style="info" %}
if you are [lazy loading the translation resources](https://www.i18next.com/how-to/add-or-load-translations), you may need to wait for i18next to have finished to initialize.
{% endhint %}
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](https://jsfiddle.net/jamuhl/dvk0e8a9/#tabs=js,result,html)
{% hint style="info" %}
Do you quickly want to translate your resources to other languages?\
Try: [https://translate.i18next.com](https://translate.i18next.com/)
{% endhint %}
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](https://github.com/i18next/i18next-gitbook/tree/master/locales).
[source code](https://jsfiddle.net/jamuhl/ferfywyf/525/)
You should now have an idea about how to achieve the basic setup. It's time to learn more about:
* The translation functions like [interpolation](https://www.i18next.com/translation-function/interpolation), [formatting](https://www.i18next.com/translation-function/formatting) and [plurals](https://www.i18next.com/translation-function/plurals).
* Find an [extension for your project](https://www.i18next.com/overview/supported-frameworks), eg. **react-i18next**, **jquery-i18next** and **others**. Using those wrappers around i18next makes using i18next a lot simpler in your project. Most of such modules come with extended examples.
* Find out more about the [configuration options](https://www.i18next.com/overview/configuration-options).
* Set up [type-safe translations with TypeScript](https://www.i18next.com/overview/typescript).
* Add a [language detector](https://www.i18next.com/overview/plugins-and-utils) to detect the preferred language of your user
* Add a [backend plugin](https://www.i18next.com/overview/plugins-and-utils) to load the translations from the server or filesystem
* Connect i18next with a smart [Translation Management System](https://locize.com), like in [this React.js example](https://github.com/locize/react-tutorial)
{% hint style="success" %}
Don't have a [Locize](https://www.locize.com/) account yet?\
You can now sign up for a **Free plan** to test the integration in your development environment indefinitely.
{% endhint %}
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://www.i18next.com/overview/getting-started.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.