Nuovo Intlayer v9 - Cosa c'è di nuovo?

Benvenuti a Intlayer v9! Questa major release segna un'enorme pietra miliare nella semplificazione del percorso di migrazione a Intlayer con i Compat Adapter Packages per le principali librerie i18n (react-i18next, next-intl, vue-i18n, ecc.) e aggiunge il supporto per strutture di contenuto ricche: Collections e Variants.

Indice

Compat Adapter Packages

La migrazione a Intlayer dalle popolari librerie i18n è ora più facile che mai. Abbiamo creato cinque compat package che espongono le stesse identiche API pubbliche delle librerie i18n standard, ma delegano tutto il lavoro di traduzione a Intlayer a runtime.

Esporre la stessa API pubblica con tipizzazione stretta

Sostituendo gli import, ottieni tutti i vantaggi di Intlayer (inclusa la type safety in fase di compilazione rispetto ai tuoi dizionari effettivi) con modifiche minime al codice:

• @intlayer/i18next
• @intlayer/react-i18next
• @intlayer/next-intl
• @intlayer/react-intl
• @intlayer/next-i18next
• @intlayer/vue-i18n
• @intlayer/lingui

Ad esempio, è sufficiente cambiare:

import { useTranslation } from "react-i18next";

in:

import { useTranslation } from "@intlayer/react-i18next";

Le tue chiavi saranno ora strettamente tipizzate rispetto ai tuoi dizionari Intlayer, offrendo il completamento automatico completo del dot-path nel tuo IDE!

Bundler Alias Plugins (Vite, Next.js, Turbopack)

Per consentire la migrazione senza riscrivere manualmente tutte le tue istruzioni di import, ogni compat adapter package include un plugin bundler personalizzato (Vite o Next.js) sotto il sottopercorso /plugin.

Questi plugin riscrivono automaticamente gli import esistenti (ad esempio react-i18next o next-intl) nei loro equivalenti @intlayer/* in fase di build.

Esempio Next.js (Webpack / Turbopack)

Invece di withIntlayer, avvolgi la tua configurazione Next.js con il compat plugin:

import { createNextI18nPlugin } from "@intlayer/next-i18next/plugin";import type { NextConfig } from "next";const withIntlayer = createNextI18nPlugin();const nextConfig: NextConfig = {};export default withIntlayer(nextConfig);

Esempio Vite (React, Vue, Solid, Svelte)

import vueI18nVitePlugin from "@intlayer/vue-i18n/plugin";export default defineConfig({  plugins: [vueI18nVitePlugin()],});

Risolutore Runtime Mutualizzato

Tutti i compat adapter ora instradano la risoluzione delle traduzioni attraverso un singolo parser runtime altamente ottimizzato: @intlayer/core/messageFormat.

• Interpolate Message: Risolve {{var}} standard (spazi bianchi e dot-paths), argomenti formattati ICU ({v, number, percent} ecc.) e template {var} semplici.
• Message Node Resolver: Risolve nodi annidati: insert(), plural() (regole plurali CLDR), enu() (enumerazione), gender(), tag HTML, array e nodi di funzione richiamabili.
• Tokenized Tag Parser: Supporta tag XML/HTML inline e tag numerati (ad esempio, <1>children</1>) per abilitare il rendering di testo ricco out of the box.

Specifica delle Funzionalità: Collections & Variants

Intlayer v9 si espande oltre gli oggetti chiave-valore statici, consentendo ai dizionari di dichiarare strutture di layout dinamiche che sono completamente tipizzate end-to-end.

1. Collections

Definisci un elenco di elementi ordinati gestito da CMS (ad esempio FAQ, prodotti o elenchi di blog):

import { t, type Dictionary } from "intlayer";export default {  key: "faq",  item: 1,  content: {    question: t({ en: "What is Intlayer?", fr: "Qu'est-ce qu'Intlayer ?" }),    answer: t({ en: "An i18n toolkit.", fr: "Une boîte à outils i18n." }),  },} satisfies Dictionary;

import { t, type Dictionary } from "intlayer";export default {  key: "faq",  item: 2,  content: {    question: t({ en: "Is it free?", fr: "Est-ce gratuit ?" }),    answer: t({ en: "Yes, open-source.", fr: "Oui, open-source." }),  },} satisfies Dictionary;

Utilizzo:

// Fetch all items as an arrayconst allFaqs = useIntlayer("faq"); // -> { question: string, answer: string }[]// Fetch a single item by indexconst faq = useIntlayer("faq", { item: 2 }); // -> { question: string, answer: string }

2. Variants

Fornisci A/B test, header stagionali, feature flag o landing page personalizzate:

Varianti stringa (es. test A/B)

import { t, type Dictionary } from "intlayer";export default {  key: "hero-banner",  variant: "default",  content: {    control: t({ it: "Benvenuto", en: "Welcome", fr: "Bienvenue" }),    black_friday: t({      it: "Acquista ora",      en: "Shop now",      fr: "Acheter maintenant",    }),  },} satisfies Dictionary;

Utilizzo:

const banner = useIntlayer("hero-banner", { variant: "black_friday" });

Varianti oggetto (es. Dynamic Records)

import { t, type Dictionary } from "intlayer";export default {  key: "product-copy",  variant: {    id: "prod_123",    category: "books",  },  content: {    title: t({ it: "Clean Code", en: "Clean Code", fr: "Code Propre" }),  },} satisfies Dictionary;

Utilizzo:

// Recupera solo l'elemento richiesto dinamicamente (richiede Suspense)const product = useIntlayer("product-copy", {  variant: { id: "prod_123", category: "books" },});

Vite Plugin: Compiler e Proxy in Bundle

Il plugin Vite intlayer() ora raggruppa il compiler e il proxy di locale-routing direttamente, quindi la maggior parte dei progetti ha bisogno solo di un singolo plugin in vite.config.ts:

import { defineConfig } from "vite";import { intlayer } from "vite-intlayer";export default defineConfig({  plugins: [intlayer()],});

• Compiler: Si attiva automaticamente quando compiler.enabled è impostato su true e un percorso compiler.output è configurato. Non è più necessario registrare intlayerCompiler() separatamente.
• Proxy: Si attiva automaticamente in base alla nuova opzione routing.enableProxy (true per impostazione predefinita). Collega il middleware di rilevamento locale / reindirizzamento / riscrittura in sviluppo, anteprima e SSR in produzione. Non è più necessario registrare intlayerProxy() separatamente.

Opzione routing.enableProxy

Una nuova opzione routing.enableProxy controlla se il proxy di routing per le locale è attivo. Il valore predefinito è true. Disabilitalo quando desideri gestire il routing delle locale autonomamente:

import type { IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  routing: {    enableProxy: false, // Default: true  },};export default config;

I plugin standalone intlayerCompiler() e intlayerProxy() rimangono esportati per configurazioni avanzate. Registrarli insieme a intlayer() è sicuro — ogni plugin si deduplica e viene eseguito una sola volta.

Compilatore disabilitato per impostazione predefinita

A partire da Intlayer v9, il compilatore è disabilitato per impostazione predefinita (compiler.enabled ora ha come valore predefinito false). Per abilitare l'estrazione dei tuoi file .content.ts in fase di build, imposta compiler.enabled: true nella tua configurazione:

import type { IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  compiler: {    enabled: true, // Predefinito: false — richiesto per abilitare il compilatore dalla v9    output: ({ fileName }) => `./${fileName}.content.ts`,  },};export default config;

Quando il compilatore è disabilitato, Intlayer salta il passaggio di estrazione in fase di build e si basa sui dizionari che hai già dichiarato. Abilitalo solo quando vuoi che il plugin del bundler (@intlayer/swc, @intlayer/babel o il plugin Vite intlayer()) estragga il contenuto automaticamente.

React Native: importazioni da un unico pacchetto

In un'app React Native o Expo, non è più necessario destreggiarsi tra react-intlayer e react-native-intlayer. Il pacchetto react-native-intlayer ora riesporta l'intera API react-intlayer (hook, utility e i sottopercorsi /format, /html e /markdown), e il suo IntlayerProvider applica automaticamente i polyfill di React Native.

Importa tutto dal pacchetto singolo react-native-intlayer:

import {  IntlayerProvider,  useIntlayer,  useLocale,} from "react-native-intlayer";

npm install intlayer react-native-intlayer

L'importazione da react-intlayer continua a funzionare, ma react-native-intlayer è ora il punto di ingresso singolo consigliato per React Native: il suo provider include i polyfill che il provider orientato al web react-intlayer non ha.

SDK CMS: usa Intlayer come database di contenuti headless

Intlayer v9 include un SDK pulito e con autenticazione automatica in @intlayer/api per interagire con il CMS in modo programmatico — recuperare progetti, recuperare dizionari e inviarli o aggiornarli dal tuo server, script o CI. L'autenticazione (OAuth2 client_credentials) è gestita e rinnovata automaticamente.

L'SDK è suddiviso in due import separati, così il tuo bundle include solo i domini che usi davvero:

1. createIntlayerCMS — un autenticatore leggero che custodisce le credenziali e il token gestito (nessun client di dominio incluso).
2. dictionaryEndpoint, projectEndpoint, … — binder di endpoint per dominio, ciascuno importato dal proprio sottopercorso.

import { createIntlayerCMS } from "@intlayer/api";import { dictionaryEndpoint } from "@intlayer/api/dictionary";// La configurazione è opzionale: le credenziali ricadono su INTLAYER_CLIENT_ID /// INTLAYER_CLIENT_SECRET risolti da `@intlayer/config/built`.const cms = createIntlayerCMS();// Letturaconst { data: dictionaries } = await dictionaryEndpoint(cms).getDictionaries();// Scrittura — usa il CMS come un databaseawait dictionaryEndpoint(cms).pushDictionaries([myDictionary]);

Sicurezza: le credenziali del CMS concedono l'accesso in scrittura ai tuoi contenuti. Crea l'autenticatore sempre lato server — non inviare mai clientId / clientSecret al browser.

Self-Hosting

Intlayer v9 offre supporto di prima classe per eseguire la propria istanza di Intlayer con un singolo comando — nessun account Intlayer Cloud richiesto.

curl -fsSL https://intlayer.org/install.sh | sh

Il programma di installazione scarica un docker-compose.yml e un .env, genera automaticamente i secret necessari ed esegue docker compose up -d. Tutto — il dashboard, l'API, il database, l'archiviazione di oggetti e le email transazionali — viene eseguito localmente nei container.

Servizi inclusi

Chromium (utilizzato per la generazione di screenshot con Puppeteer) è incluso nell'immagine del backend — nessun container aggiuntivo necessario.

Note di migrazione da v8

Se stai eseguendo l'aggiornamento da v8, nota che la v9 non include breaking changes. Ma ecco le modifiche chiave:

• Compilatore disabilitato per impostazione predefinita: compiler.enabled ora ha come valore predefinito false. Se dipendi dall'estrazione dei tuoi file .content.ts in fase di build, imposta compiler.enabled: true nel tuo intlayer.config.ts.
• Plugin Vite: Il compilatore e il proxy di routing locale sono ora integrati in intlayer(). Se in precedenza hai registrato intlayerCompiler() o intlayerProxy() manualmente, puoi rimuoverli — vengono deduplicati automaticamente, quindi mantenerli è innocuo. Usa routing.enableProxy: false per disattivare il proxy.
• Locales & Dialects: Se utilizzi dipendenze i18n esterne, aggiungi i rispettivi compat adapter plugin nella tua configurazione o setup del bundler per riscrivere automaticamente gli import.
• Custom Selectors: Quando chiami useIntlayer, il secondo parametro è ora riservato a un oggetto di opzioni contenente { locale, item, variant }. Se in precedenza passavi direttamente una stringa locale, puoi ancora farlo, ma l'utilizzo dell'oggetto di opzioni è consigliato per selezioni avanzate.
• React Native: react-native-intlayer ora riesporta l'intera API di react-intlayer. In un'app React Native, importa tutto da react-native-intlayer e rimuovi la dipendenza diretta da react-intlayer. Gli import esistenti di react-intlayer continuano a funzionare.

Link utili

• Guida ai Compat Adapter Packages
• Dizionari Dinamici - Collections & Variants
• Riferimento alla Configurazione
• SDK CMS - Accesso programmatico con @intlayer/api
• Guida al Self-Hosting