aymericzip/intlayer-skills/intlayer-compat

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

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.

• 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.
• syncJSON accepts format: 'intlayer' | 'icu' | 'i18next' | 'vue-i18n' to match the message syntax of the existing library.
• 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
• Doc

Plugins

• Sync JSON
• Sync PO

Migration Guides

• Compat Adapters Overview
• i18next
• react-i18next
• next-i18next
• next-intl
• React Intl
• Vue I18n
• Lingui
• NuxtJS I18n
• NGX Translate
• Svelte I18n