How to automate your next-intl JSON translations using Intlayer

Table of Contents

What is Intlayer?

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

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

Why Combine Intlayer with next-intl?

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

Intlayer offers a rich set of advanced features that go beyond traditional i18n tools. It helps you.

• Automatically detect and fill missing translations to streamline localization.
• Test and validate your translations directly in your development or CI/CD workflows.
• Manage content per component, enabling a clean, scalable, and maintainable structure across your app.
• Externalize your content, making it easily editable by your whole team (developers, translators, and content managers).

However, next-intl remains an excellent and widely adopted i18n solution thanks to its mature ecosystem, broad community support, and extensive plugin compatibility.

By combining Intlayer with next-intl, you get the best of both worlds, next-intl’s stability and ecosystem maturity, with Intlayer’s modern content management, automation, and developer experience improvements.

This guide explains how to leverage Intlayer as an adapter for next-intl, allowing you to:

• Gradually migrate from next-intl to Intlayer.
• Keep existing next-intl plugins and workflows.
• Automate your JSON translations in CLI or CI/CD pipelines.
• Test, sync, and manage translations more effectively.

Table of Contents

Step-by-Step Guide to Set Up Intlayer with next-intl

1. 1

   Install Dependencies

   Install the necessary packages:

   bash

   Copy content

   Copy code

   Copy the code to the clipboard

   npx intlayer-cli init --interactive

   the --interactive flag is optional. Use intlayer-cli init if you're an AI agent.

   This command will detect your environment and install the required packages. For example:

   bash

   Copy content

   Copy code

   Copy the code to the clipboard

   npm install intlayer @intlayer/sync-json-plugin --save-dev

   Package descriptions:

   • intlayer: Core library for internationalisation management, content declaration, and building
   • @intlayer/sync-json-plugin: Plugin to export Intlayer content declarations to next-intl compatible JSON format
2. 2

   Implement the Intlayer plugin to wrap the JSON

   Create an Intlayer configuration file to define your supported locales:

   If you also want to export JSON dictionaries for next-intl, add the syncJSON plugin:

   intlayer.config.ts

   Copy content

   Copy code

   Copy the code to the clipboard

   import { Locales, type IntlayerConfig } from "intlayer";import { syncJSON } from "@intlayer/sync-json-plugin";const config: IntlayerConfig = {  internationalisation: {    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],    defaultLocale: Locales.ENGLISH,  },  plugins: [    syncJSON({      format: "icu",      source: ({ key, locale }) => `./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 that JSON coexist with intlayer content declaration files (.content files), Intlayer will proceed as follows:

   plaintext

   Copy content

   Copy code

   Copy the code to the clipboard

   1. load both JSON and content declaration files and transform them into an intlayer dictionary.2. if there are conflicts between the JSON and the content declaration files, Intlayer will proceed to merge all those dictionaries. This depends on the priority of the plugins, and that 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.

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

Git Configuration

It is recommended to ignore auto-generated Intlayer files:

# Ignore files generated by Intlayer.intlayer

These files can be regenerated during your build process and do not need to be committed to version control.

VS Code Extension

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

Install from the VS Code Marketplace