API
Integrate with i18next
Connect your project with your translations instantly
Tutorials
Quick Start
There are 3 primary ways to integrate your i18nexus translations with your app:
- Connecting your app to your latest live translations through the i18nexus API
- Connecting your app to a static cached version of your translations stored on the i18nexus CDN. (Allows for localStorage caching)
- Downloading your translations with the i18nexus CLI to bundle with your app. (Recommended for SSR/SSG apps)
Option 1: Connecting i18next to your latest translations
- i18next – the main i18next library
- i18next-http-backend – for making AJAX requests to load translations
- i18next-browser-languagedetector – for detecting a user’s browser language
In this method, we are simply telling i18next to make an AJAX request to your i18nexus project to retrieve translations for a specific language.
In production environments, it is recommended to optimize with versioning and caching. Scroll down to Option 2 to see how to do this.
import i18next from "i18next";
import HttpBackend from "i18next-http-backend";
import LanguageDetector from "i18next-browser-languagedetector";
const loadPath = `https://api.i18nexus.com/project_resources/translations/{{lng}}/{{ns}}.json?api_key=YOUR_PROJECT_API_KEY`;
i18next
.use(HttpBackend)
.use(LanguageDetector)
.init({
fallbackLng: "en", // set to your project's base language
ns: ["example-namespace", "example-namespace-2"], // namespaces you want to load
defaultNS: "example-namespace", // namespace that is your default
supportedLngs: ["en", "fr", "es-mx"], // languages in your project
backend: {
loadPath: loadPath
}
})
*To learn more about using i18next, see their documentation.
Option 2: Connecting i18next to a specific version of your translations
- i18next-localstorage-backend – improves the loading speed of your translations by caching them in the browser.
- i18next-chained-backend – helps us manage how our translations are retrieved.
In the code snippet below, we are retrieving our translations from the i18nexus CDN and then caching the translations in the user’s browser. This ensures much faster load times and a better user experience:
import i18next from "i18next";
import LanguageDetector from "i18next-browser-languagedetector";
import HttpBackend from "i18next-http-backend";
import ChainedBackend from "i18next-chained-backend";
import LocalStorageBackend from "i18next-localstorage-backend";
const version = 1; // change this to the version you want to use
const loadPath = `https://cdn.i18nexus.com/versions/${version}/translations/{{lng}}/{{ns}}.json?api_key=YOUR_PROJECT_API_KEY`;
i18next
.use(ChainedBackend)
.use(LanguageDetector)
.init({
fallbackLng: "en", // set to your project's base language
ns: ["example-namespace"], // namespaces you want to load
defaultNS: "example-namespace", // namespace that is your default
supportedLngs: ["en", "fr", "es-mx"], // languages available on this version
backend: {
backends: [
LocalStorageBackend,
HttpBackend
],
backendOptions: [{
defaultVersion: version
}, {
loadPath: loadPath
}]
}
})
*To learn more about using i18next, see their documentation.
Option 3: Downloading translations with the i18nexus CLI
The primary motivation for this CLI is to ease i18nexus integration with SSR/SSG frameworks such as NextJS. It is the best way to integrate i18nexus with next-i18next.
$ npm install -g i18nexus-cli
$ i18nexus pull -k <YOUR_PROJECT_API_KEY>
Your project API key can also be set using an an environment variable I18NEXUS_API_KEY
All options can be viewed here.
Project Resources API
Translations
Returns a JSON object of a project’s translations for a specified language and namespace.
{
"welcome": "Welcome to my app!",
"goodbye": "Thanks for using my app!"
}
All Translations
Returns a nested JSON object of all project translations for all languages and namespaces.
GET https://api.i18nexus.com/project_resources/translations.json?api_key=:project_api_key
{
"en": {
"my-first-namespace": {
"welcome": "Welcome to my app!",
"goodbye": "Thanks for using my app!"
},
"my-second-namespace": {
"greeting": "How are you?"
}
},
"es-MX": {
"my-first-namespace": {
"welcome": "¡Bienvenido a mi aplicación!",
"goodbye": "¡Gracias por usar mi aplicación!"
},
"my-second-namespace": {
"greeting": "¿Cómo estás?"
}
}
}
Versions
Returns a collection of a project’s exported versions ordered from newest to oldest.
By default the latest 10 versions will be returned, but this can be adjusted using the optional limit query parameter.
GET https://api.i18nexus.com/project_resources/versions.json?api_key=:project_api_key&limit=10
{
"collection": [
{
"created_at": 1631402817503,
"description": "My version description",
"download_url": "https://cdn.i18nexus.com/versions/1/translations.zip",
"id": "c3ee93c5-66c8-487d-8cbb-0e6109550f35",
"key_separation": true,
"languages": ["en","es-MX"],
"namespaces": ["my-first-namespace", "my-second-namespace"],
"version_number": 1
}
]
}
Need help?
We are always available for any questions you have.
Click the chat bubble in the bottom right of this page, or email us at support@i18nexus.com.