Traduci il tuo backend AdonisJS usando Intlayer | Internazionalizzazione (i18n)

adonis-intlayer è un potente pacchetto di internazionalizzazione (i18n) per applicazioni AdonisJS, progettato per rendere i tuoi servizi backend accessibili a livello globale fornendo risposte localizzate basate sulle preferenze del cliente.

Casi d'Uso Pratici

• Visualizzazione degli Errori Backend nella Lingua dell'Utente: Quando si verifica un errore, mostrare i messaggi nella lingua madre dell'utente migliora la comprensione e riduce la frustrazione. Questo è particolarmente utile per messaggi di errore dinamici che potrebbero essere visualizzati in componenti front-end come toast o modali.

• Recupero di Contenuti Multilingue: Per le applicazioni che estraggono contenuti da un database, l'internazionalizzazione garantisce che sia possibile servire tali contenuti in più lingue. Questo è fondamentale per piattaforme come siti di e-commerce o sistemi di gestione dei contenuti che devono visualizzare descrizioni di prodotti, articoli e altri contenuti nella lingua preferita dall'utente.

• Invio di Email Multilingue: Che si tratti di email transazionali, campagne di marketing o notifiche, l'invio di email nella lingua del destinatario può aumentare significativamente il coinvolgimento e l'efficacia.

• Notifiche Push Multilingue: Per le applicazioni mobili, l'invio di notifiche push nella lingua preferita di un utente può migliorare l'interazione e la fidelizzazione. Questo tocco personale può rendere le notifiche più pertinenti e stimolanti.

• Altre Comunicazioni: Qualsiasi forma di comunicazione dal backend, come messaggi SMS, avvisi di sistema o aggiornamenti dell'interfaccia utente, trae vantaggio dall'essere nella lingua dell'utente, garantendo chiarezza e migliorando l'esperienza utente complessiva.

Internazionalizzando il backend, la tua applicazione non solo rispetta le differenze culturali, ma si allinea anche meglio alle esigenze del mercato globale, rendendolo un passo fondamentale per scalare i tuoi servizi in tutto il mondo.

Iniziare

See Application Template on GitHub.

Installazione

Per iniziare a usare adonis-intlayer, installa il pacchetto usando npm:

npm install intlayer adonis-intlayernpx intlayer init

Configurazione

Configura le impostazioni di internazionalizzazione creando un file intlayer.config.ts nella root del tuo progetto:

import { Locales, type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  internationalization: {
    locales: [
      Locales.ENGLISH,
      Locales.RUSSIAN,
      Locales.JAPANESE,
      Locales.FRENCH,
      Locales.KOREAN,
      Locales.CHINESE,
      Locales.SPANISH,
      Locales.GERMAN,
      Locales.ARABIC,
      Locales.ITALIAN,
      Locales.ENGLISH_UNITED_KINGDOM,
      Locales.PORTUGUESE,
      Locales.HINDI,
      Locales.TURKISH,
      Locales.POLISH,
      Locales.INDONESIAN,
      Locales.VIETNAMESE,
      Locales.UKRAINIAN,
    ],
    defaultLocale: Locales.ENGLISH,
  },
};

export default config;

Dichiarazione del Contenuto

Crea e gestisci le tue dichiarazioni di contenuto per memorizzare le traduzioni:

import { t, type Dictionary } from "intlayer";

const indexContent = {
  key: "index",
  content: {
    exampleOfContent: t({
      en: "Example of returned content in English",
      fr: "Exemple de contenu renvoyé en français",
      it: "Esempio di contenuto restituito in italiano",
      "es-ES": "Ejemplo de contenido devuelto en español (España)",
      "es-MX": "Ejemplo de contenido devuelto en español (México)",
    }),
  },
} satisfies Dictionary;

export default indexContent;

Le tue dichiarazioni di contenuto possono essere definite ovunque nella tua applicazione, purché siano incluse nella directory contentDir (per impostazione predefinita, ./src o ./app) e corrispondano all'estensione del file di dichiarazione del contenuto (per impostazione predefinita, .content.{json,ts,tsx,js,jsx,mjs,cjs}).

Per maggiori dettagli, consulta la documentazione sulla dichiarazione del contenuto.

Configurazione dell'Applicazione AdonisJS

Configura la tua applicazione AdonisJS per usare adonis-intlayer.

Registrare il middleware

Innanzitutto, devi registrare il middleware intlayer nella tua applicazione.

router.use([() => import("adonis-intlayer/middleware")]);

Definire le tue rotte

import router from "@adonisjs/core/services/router";import { t, getIntlayer, getDictionary } from "adonis-intlayer";import indexContent from "../app/index.content";router.get("/t_example", async () => {  return t({    en: "Example of returned content in English",    fr: "Exemple de contenu renvoyé en français",    it: "Esempio di contenuto restituito in italiano",    "es-ES": "Ejemplo de contenuto devuelto en español (España)",    "es-MX": "Ejemplo de contenuto devuelto en español (México)",  });});router.get("/getIntlayer_example", async () => {  return getIntlayer("index").exampleOfContent;});router.get("/getDictionary_example", async () => {  return getDictionary(indexContent).exampleOfContent;});

Funzioni

adonis-intlayer esporta diverse funzioni per gestire l'internazionalizzazione nella tua applicazione:

• t(content, locale?): Funzione di traduzione di base.
• getIntlayer(key, locale?): Recupera il contenuto tramite chiave dai tuoi dizionari.
• getDictionary(dictionary, locale?): Recupera il contenuto da uno specifico oggetto dizionario.
• getLocale(): Recupera la locale corrente dal contesto della richiesta.

Uso nei Controller

import type { HttpContext } from "@adonisjs/core/http";import { t } from "adonis-intlayer";export default class ExampleController {  async index({ response }: HttpContext) {    return response.send(      t({        en: "Hello from controller",        fr: "Bonjour depuis le contrôleur",        it: "Ciao dal controller",      })    );  }}

Compatibilità

adonis-intlayer è completamente compatibile con:

• react-intlayer per applicazioni React
• next-intlayer per applicazioni Next.js
• vite-intlayer per applicazioni Vite

Funziona anche perfettamente con qualsiasi soluzione di internazionalizzazione in vari ambienti, inclusi browser e richieste API. Puoi personalizzare il middleware per rilevare la locale tramite header o cookie:

import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  // ... Altre opzioni di configurazione  middleware: {    headerName: "my-locale-header",    cookieName: "my-locale-cookie",  },};export default config;

Per impostazione predefinita, adonis-intlayer interpreterà l'header Accept-Language per determinare la lingua preferita del cliente.

Per ulteriori informazioni sulla configurazione e argomenti avanzati, visita la nostra documentazione.

Configura TypeScript

adonis-intlayer sfrutta le robuste capacità di TypeScript per migliorare il processo di internazionalizzazione. La tipizzazione statica di TypeScript garantisce che ogni chiave di traduzione sia considerata, riducendo il rischio di traduzioni mancanti e migliorando la manutenibilità.

Assicurati che i tipi autogenerati (per impostazione predefinita in ./types/intlayer.d.ts) siano inclusi nel tuo file tsconfig.json.

{  // ... Le tue configurazioni TypeScript esistenti  "include": [    // ... Le tue configurazioni TypeScript esistenti    ".intlayer/**/*.ts", // Includi i tipi auto-generati  ],}

Estensione VS Code

Per migliorare la tua esperienza di sviluppo con Intlayer, puoi installare l'estensione ufficiale Intlayer per VS Code.

Installa dal VS Code Marketplace

Questa estensione fornisce:

• Autocompletamento per le chiavi di traduzione.
• Rilevamento degli errori in tempo reale per le traduzioni mancanti.
• Anteprime in linea del contenuto tradotto.
• Azioni rapide per creare e aggiornare facilmente le traduzioni.

Per maggiori dettagli su come utilizzare l'estensione, consulta la documentazione dell'estensione Intlayer per VS Code.

Configurazione Git

Si raccomanda di ignorare i file generati da Intlayer. Questo ti permette di evitare di commetterli nel tuo repository Git.

Per farlo, puoi aggiungere le seguenti istruzioni al tuo file .gitignore:

# Ignora i file generati da Intlayer.intlayer