git:20260923.e86be10 to git:20260930.7e17553

---

name: intlayer-compat

description: Migrates an existing i18n library (i18next, react-i18next, next-intl, next-i18next, react-intl, vue-i18n, Lingui…) to Intlayer through compat adapters that keep the original API. Use when the user asks to "migrate from i18next / next-intl / vue-i18n", "keep useTranslation working", or adopt Intlayer without rewriting translation calls.

metadata:

author: Intlayer

url: https://intlayer.org

license: Apache-2.0

mcp-server: "@intlayer/mcp"

category: productivity

tags: [i18n, migration, i18next, next-intl, react-intl, vue-i18n, lingui]

documentation: https://intlayer.org/doc

support: contact@intlayer.org

---

# Intlayer Compat Adapters

Compat adapters expose the **exact same public API** as an existing i18n library, but serve translations from Intlayer dictionaries. Application code keeps calling `useTranslation`, `useTranslations`, `useIntl`, `$t`… with keys typed against the Intlayer dictionaries.

## How it works

1. Run `npx intlayer init --interactive`: it creates `intlayer.config.ts`, installs the adapter and can keep existing JSON catalogs as the source of truth via a sync plugin.

2. Register the adapter's bundler plugin (`<adapter>/plugin`). It aliases the original imports to the adapter at build time, so no import is rewritten by hand.

## Adapters

| Existing library | Adapter | Bundler plugin (`<adapter>/plugin`) |

| ------------------------------- | ------------------------- | ----------------------------------- |

| `i18next` | `@intlayer/i18next` | `i18nextVitePlugin` |

| `react-i18next` | `@intlayer/react-i18next` | `reactI18nextVitePlugin` |

| `next-i18next` | `@intlayer/next-i18next` | `createNextI18nPlugin` |

| `next-intl` | `@intlayer/next-intl` | `createNextIntlPlugin` |

| `use-intl` | `@intlayer/use-intl` | `useIntlVitePlugin` |

| `react-intl` | `@intlayer/react-intl` | `reactIntlVitePlugin` |

| `vue-i18n` | `@intlayer/vue-i18n` | `vueI18nVitePlugin` |

| `@lingui/core`, `@lingui/react` | `@intlayer/lingui` | `linguiVitePlugin` |

> Lingui: keep the Lingui macro plugin (`@lingui/babel-plugin-lingui-macro` / `@lingui/swc-plugin`) running before the Intlayer compiler.

> Features outside translation stay with the original library, e.g. `next-intl/navigation` (`Link`, `redirect`, `usePathname`). ICU messages (plural, select, `#`, formatted arguments) and rich formatting (`t.rich`, `<Trans>`) are resolved by Intlayer.

Migration guides also exist for Nuxt I18n, NGX Translate, Transloco, Svelte I18n, Next Translate, Polyglot.js and i18n-js.

## Keep Existing Catalogs: Sync Plugins

To keep the current library **and** its message files, register a sync plugin in the `plugins` of `intlayer.config.ts` instead of (or alongside) an adapter. Intlayer then manages the catalogs (AI fill, CI tests, CMS) without changing the rendering runtime.

| Catalog format | Package | Plugins |

| -------------- | ---------------------------- | ---------------------- |

| JSON | `@intlayer/sync-json-plugin` | `syncJSON`, `loadJSON` |

| Gettext PO | `@intlayer/sync-po-plugin` | `syncPO`, `loadPO` |

- `sync*` reads **and writes back** the files, keeping them in sync with the dictionaries.

- `load*` only loads the files into dictionaries (never writes back), e.g. for catalogs fetched from a remote source.

- Current scope: plain text and translations; insertions, plurals/ICU and the visual editor are not supported yet for synced files.

## After migrating

Once the app runs on Intlayer, components can be moved progressively to the native API (`useIntlayer` + `.content` files) and the adapter removed.

## References

- [Website](https://intlayer.org)

- [Doc](https://intlayer.org/doc)

### Plugins

- [Sync JSON](references/plugin_sync-json.md)

- [Sync PO](references/plugin_sync-po.md)

### Migration Guides

- [Compat Adapters Overview](references/compatibility.md)

- [i18next](references/compatibility_i18next.md)

- [react-i18next](references/compatibility_react-i18next.md)

- [next-i18next](references/compatibility_next-i18next.md)

- [next-intl](references/compatibility_next-intl.md)

- [React Intl](references/compatibility_react-intl.md)

- [Vue I18n](references/compatibility_vue-i18n.md)

- [Lingui](references/compatibility_lingui.md)

- [NuxtJS I18n](references/compatibility_nuxtjs-i18n.md)

- [NGX Translate](references/compatibility_ngx-translate.md)

- [Svelte I18n](references/compatibility_svelte-i18n.md)