API

Connect your project with your translations instantly

Tutorials

Quick Start

On the Export page of your i18nexus project, you will find i18next code snippets ready for you to copy and paste into your app. But if you would like to learn more about the different ways i18nexus can integrate with i18next, read on!

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

Connecting your application to the i18nexus API is an awesome way to develop. Every time you add a string to i18nexus, it will immediately appear in your application with all its Google translations! Now you can see how your project looks in other languages before your translators have even gotten started!

In the code snippet below, we are making use of three awesome i18next libraries:

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

Below, we are making use of two more awesome i18next libraries:

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.

When you create a new version in your project’s Export section, that version is automatically served as JSON through our blazing-fast CDN (Content Delivery Network).

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 i18nexus CLI allows you to download your translations to bundle with your app.

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.

GET https://api.i18nexus.com/project_resources/translations/:language_code/:namespace.json?api_key=:project_api_key

{
    "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.

API

Integrate with i18next