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, Variants e Dynamic Records.

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/next-i18next
• @intlayer/vue-i18n

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 & Dynamic Records

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",  content: [    {      question: t({        it: "Cos'è Intlayer?",        en: "What is Intlayer?",        fr: "Qu'est-ce qu'Intlayer ?",      }),      answer: t({        it: "Un toolkit i18n.",        en: "An i18n toolkit.",        fr: "Une boîte à outils i18n.",      }),    },  ],} satisfies Dictionary;

Utilizzo:

// Recupera tutti gli elementiconst allFaqs = useIntlayer("faq"); // -> { question: string, answer: string }[]// Recupera un singolo elemento per indiceconst faq = useIntlayer("faq", { item: 1 }); // -> { question: string, answer: string }

2. Variants

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

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" });

3. Dynamic Records

Definisci dizionari le cui voci vengono caricate dinamicamente a runtime tramite ID di query:

import { t, type Dictionary } from "intlayer";export default {  key: "product-copy",  meta: {    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", {  id: "prod_123",  category: "books",});

Caricamento Dinamico e Ottimizzazioni delle Dimensioni del Bundle

Per mantenere i bundle estremamente piccoli, Intlayer v9 supporta il caricamento dinamico lazy loading.

Nella tua configurazione, imposta importMode su 'dynamic' o 'fetch':

export default {  dictionary: {    importMode: "dynamic", // "static" | "dynamic" | "fetch"  },};

In fase di build, @intlayer/swc e @intlayer/babel scansionano i tuoi file e sostituiscono le chiamate useIntlayer / getIntlayer con wrapper tree-shakeable (useDictionary / useDictionaryDynamic). Viene caricato solo il contenuto richiesto per l'elemento della collection, la variante o la locale selezionati, impedendo al tuo bundle di produzione di contenere traduzioni inutilizzate.

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:

• 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, id }. Se in precedenza passavi direttamente una stringa locale, puoi ancora farlo, ma l'utilizzo dell'oggetto di opzioni è consigliato per selezioni avanzate.

Link utili

• Guida ai Compat Adapter Packages
• Dizionari Dinamici - Collections, Variants & Dynamic Records
• Riferimento alla Configurazione