How to automate your i18next JSON translations using Intlayer

What is Intlayer?

Intlayer is an innovative, open-source internationalization library designed to address the shortcomings of traditional i18n solutions. It offers a modern approach to content management in JavaScript applications.

See a concrete comparison with i18next in our next-i18next vs. next-intl vs. Intlayer blog post.

Why Combine Intlayer with i18next?

While Intlayer provides an excellent standalone i18n solution (see our Next.js integration guide), you might want to combine it with i18next for several reasons:

1. Existing codebase: You have an established i18next implementation and want to gradually migrate to Intlayer's improved developer experience.
2. Legacy requirements: Your project requires compatibility with existing i18next plugins or workflows.
3. Team familiarity: Your team is comfortable with i18next but wants better content management.

For that, Intlayer can be implemented as an adapter for i18next to help automating your JSON translations in CLI or CI/CD pipelines, testing your translations, and more.

This guide shows you how to leverage Intlayer's superior content declaration system while maintaining compatibility with i18next.

Table of Contents

Step-by-Step Guide to Set Up Intlayer with i18next

Step 1: Install Dependencies

Install the necessary packages:

npm install intlayer @intlayer/sync-json-plugin

Package descriptions:

• intlayer: Core library for internationalization management, content declaration, and building
• @intlayer/sync-json-plugin: Plugin to export Intlayer content declarations to i18next compatible JSON format

Step 2: Implement the Intlayer plugin to wrap the JSON

Create an Intlayer configuration file to define your supported locales:

If you want to also export JSON dictionaries for i18next, add the syncJSON plugin:

import { Locales, type IntlayerConfig } from "intlayer";import { syncJSON } from "@intlayer/sync-json-plugin";const config: IntlayerConfig = {  internationalization: {    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],    defaultLocale: Locales.ENGLISH,  },  plugins: [    syncJSON({      source: ({ key, locale }) => `./intl/messages/${locale}/${key}.json`,    }),  ],};export default config;

The syncJSON plugin will automatically wrap the JSON. It will read and write the JSON files without changing the content architecture.

If you want to make coexist that JSON with intlayer content declaration files (.content files), Intlayer will proceed this way:

1. load both JSON and content declaration files and transform them into a intlayer dictionary.2. if there is conflicts between the JSON and the content declaration files, Intlayer will process to the merge of that all dictionaries. Depending of the priority of the plugins, and the one of the content declaration file (all are configurable).

If changes are made using the CLI to translate the JSON, or using the CMS, Intlayer will update the JSON file with the new translations.

To see more details about the syncJSON plugin, please refer to the syncJSON plugin documentation.

Git Configuration

It's recommended to ignore auto-generated Intlayer files:

# Ignore files generated by Intlayer.intlayer

These files can be regenerated during your build process and don't need to be committed to version control.

VS Code Extension

For improved developer experience, install the official Intlayer VS Code Extension:

Install from the VS Code Marketplace