Migrating from @nuxtjs/i18n to Intlayer

Why migrate from @nuxtjs/i18n to Intlayer?

Migration strategies

Since @nuxtjs/i18n is powered by vue-i18n under the hood, there are two complementary strategies for migrating to Intlayer:

1. Compat adapter (recommended for existing apps) — Install @intlayer/vue-i18n and nuxt-intlayer. This exposes the exact same API as vue-i18n but delegates all translation work to Intlayer under the hood. You keep your existing $t, useI18n(), and Nuxt routing unchanged — the only change is the initialization.

2. Full migration — Gradually replace @nuxtjs/i18n APIs with native Intlayer hooks (useIntlayer) and co-locate content in .content.ts files alongside your components.

This guide covers Strategy 1 first (drop-in compat adapter), then walks through the optional full migration.

Table of Contents

Quick migration

The following steps are the minimum required to get your existing Nuxt app running on Intlayer with zero code changes in your components.

1. 1

   Install Dependencies

   Install the Intlayer core packages and the compat adapter:

   bash

   نسخ المحتوى

   نسخ الكود

   نسخ الكود إلى الحافظة

   npm install intlayer vue-intlayer nuxt-intlayer @intlayer/vue-i18n @intlayer/sync-json-pluginnpx intlayer init

   You can safely keep @nuxtjs/i18n installed during migration, though you will remove it from your Nuxt config shortly.

2. 2

   Configure Intlayer

   The intlayer init command creates a starter intlayer.config.ts. Update it to match your existing locales and point the syncJSON plugin at your message files:

   intlayer.config.ts

   نسخ المحتوى

   نسخ الكود

   نسخ الكود إلى الحافظة

   import { Locales, type IntlayerConfig } from "intlayer";
   import { syncJSON } from "@intlayer/sync-json-plugin";
   
   const config: IntlayerConfig = {
     internationalization: {
       locales: [
         Locales.ENGLISH,
         Locales.FRENCH,
         Locales.SPANISH,
         // Add all your existing locales here
       ],
       defaultLocale: Locales.ENGLISH,
     },
     plugins: [
       syncJSON({
         // matches vue-i18n placeholder syntax: {name}
         format: "icu",
         source: ({ locale }) => `./locales/${locale}.json`,
         location: "locales",
       }),
     ],
   };
   
   export default config;

   source maps a locale to its JSON file path. location tells the Intlayer watcher which folder to monitor for changes. The format: 'icu' option ensures that placeholders are parsed correctly for vue-i18n.

3. 3

   Update Nuxt Configuration

   Replace the @nuxtjs/i18n module with nuxt-intlayer in your nuxt.config.ts. The Intlayer plugin automatically injects module aliases, meaning your existing import { useI18n } from 'vue-i18n' calls are transparently redirected to @intlayer/vue-i18n.

   nuxt.config.ts

   نسخ المحتوى

   نسخ الكود

   نسخ الكود إلى الحافظة

   export default defineNuxtConfig({
     // Remove '@nuxtjs/i18n'
     modules: ["nuxt-intlayer"],
   });

   You no longer need to define Nuxt i18n config objects. Intlayer compiles all dictionaries at build time, handling locale detection, routing, and dictionary loading seamlessly.

That's it for the quick migration. Your Nuxt app now runs on Intlayer while keeping every $t and useI18n() intact.

Complete migration

The steps below are optional and can be done incrementally. They unlock the full Intlayer feature set: visual editor, CMS, typed content files, AI-powered translation, and more.

1. 4

   Explicit import renaming (optional)

   اختياري

   The Intlayer plugins already handle aliasing at the bundler level. If you prefer to make the dependency explicit in your source files, you can rename imports manually:

   اظهار جميع محتويات الجدول

   اظهار جميع محتويات الجدول

   افتح الجدول في نافذة منبثقة لعرض جميع محتويات البيانات بوضوح

   Before	After
   import { useI18n } from 'vue-i18n'	import { useI18n } from '@intlayer/vue-i18n'

   These are drop-in replacements — no changes to call signatures, arguments, or return types are required.

2. 5

   Enable AI-Powered Translation Automation

   اختياري

   Once Intlayer is wired up, use its CLI to fill missing translations automatically:

   bash

   نسخ المحتوى

   نسخ الكود

   نسخ الكود إلى الحافظة

   # Test for missing translations (add to CI)npx intlayer test# Fill missing translations with AInpx intlayer fill

   Add the AI configuration to intlayer.config.ts:

   intlayer.config.ts

   نسخ المحتوى

   نسخ الكود

   نسخ الكود إلى الحافظة

   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({
         format: "icu",
         source: ({ locale }) => `./locales/${locale}.json`,
         location: "locales",
       }),
     ],
     ai: {
       apiKey: process.env.OPENAI_API_KEY,
       // provider: "openai",     // default
       // model: "gpt-4o-mini",   // default
     },
   };
   
   export default config;

   See Intlayer CLI documentation for all available options.

What you can delete after migration

Once the compat adapter is in place, the following boilerplate can be removed:

When you are ready to go further, Intlayer automatically discovers all .content.ts and .content.json files anywhere in your codebase (by default, anywhere inside ./src). You can place a my-component.content.ts file right next to your MyComponent.vue and Intlayer will pick it up at build time with no additional configuration — no imports, no registration, no centralized index file needed. This makes co-locating translations with pages and components completely frictionless.

Configure TypeScript

Intlayer uses module augmentation to provide full TypeScript intellisense for your translation keys. Make sure your tsconfig.json includes the auto-generated types:

{  // ... Your existing TypeScript configurations  "include": [    // ... Your existing TypeScript configurations    ".intlayer/**/*.ts", // Include the auto-generated types  ],}

Git Configuration

Add Intlayer's generated directory to your .gitignore:

# Ignore the files generated by Intlayer.intlayer

Go Further

• Visual Editor — Manage translations visually in your browser: Intlayer Visual Editor
• CMS — Externalize and manage content remotely: Intlayer CMS
• VS Code Extension — Get autocompletion and real-time translation error detection: Intlayer VS Code Extension
• CLI Reference — Full list of CLI commands: Intlayer CLI
• Intlayer with Nuxt — Full setup guide for Nuxt: intlayerwithnuxt.md
• Intlayer with Vue — Full setup guide for Vue: intlayerwithvite+vue.md