Panoramica

In gt-next 6.3.0 ci avviciniamo a una libreria adatta sia agli sviluppatori umani sia agli sviluppatori AI. Il nostro principio guida per questa release è stato ridurre al minimo le modifiche al codice esistente, introducendo al contempo le funzionalità essenziali necessarie per l'i18n.

Per ottenere questo risultato, introduciamo una nuova funzione msg() per tradurre stringhe ovunque nel tuo codebase. In precedenza, gli sviluppatori dovevano passare la funzione t() da useGT() o getGT() lungo lo stack delle chiamate per poter tradurre una stringa. Con msg(), ti basta racchiudere la stringa una sola volta e poi passarla a m() al momento del rendering.

Un confronto

Storicamente, le stringhe dovevano essere avvolte passando la funzione t() attraverso più livelli:

export const greeting1 = 'Ciao, mondo!'
export const getGreeting2 = (t: any) => t('Ciao, mondo!')

import { greeting1, getGreeting2 } from './constants'

export default function Page() {
  const t = useGT()
  return (
    <div>
      {greeting1}
      {getGreeting2(t)}
    </div>
  )
}

Ora, con msg(), le stringhe possono essere dichiarate direttamente come costanti. L'unico requisito è passarle a m() (da useMessages() o getMessages()) al momento della visualizzazione.

export const greeting1 = 'Ciao, mondo!'
export const greeting2 = msg('Ciao, mondo!')

import { greeting1, greeting2 } from './constants'

export default function Page() {
  const m = useMessages()
  return (
    <div>
      {greeting1}
      {m(greeting2)}
    </div>
  )
}

Codifica e decodifica

Per supportare l'interpolazione, la funzione msg() restituisce un messaggio codificato invece di una semplice stringa. Il formato è il seguente:

<contenuto interpolato>:<stringa codificata base64>

La parte codificata in base64 contiene un oggetto JSON con:

• $_hash: Hash della stringa originale
• $_source: Parametri interpolati nel messaggio
• $id: Identificatore univoco personalizzato (se fornito)
• $context: Contesto del messaggio (se specificato)
• Tutte le variabili incluse nell'interpolazione

Questo design modifica leggermente il modo in cui le stringhe vengono confrontate direttamente, ma garantisce un impatto minimo sul typing e sulla struttura del codice. Per accedere al contenuto interpolato, usa decodeMsg().

Perché una stringa codificata?

L'alternativa all'uso di una stringa codificata implicherebbe che msg() debba restituire un tipo di oggetto personalizzato contenente i metadati aggiuntivi. Sebbene questo funzioni per il paradigma di codifica/decodifica, introduce problemi quando si lavora con il typing rigoroso.

Abbiamo concluso che il modo migliore per ridurre al minimo l'impatto dell'i18n in questo scenario è semplicemente restituire una stringa che contiene i metadati.

Esempio

Codice originale senza i18n:

const name = 'John'
const message = `Hello, ${name}!`

if (message.length > 10) {
  console.log('Il messaggio è troppo lungo')
} else {
  console.log('Il messaggio ha la lunghezza corretta')
}

Con msg() e decodeMsg():

import { msg, decodeMsg } from 'gt-next'

const name = 'John'
const message = msg('Ciao, {name}!', { name })

if (decodeMsg(message).length > 10) {
  console.log('Il messaggio è troppo lungo')
} else {
  console.log('Il messaggio ha la lunghezza corretta')
}

Altro

Puoi anche sostituire i parametri all'interno della funzione t(), anche se sono già stati interpolati quando hai chiamato msg().

import { msg, useMessages } from 'gt-next'

const message = msg('Ciao, {name}!', { name: 'John' })

export default function Page() {
  const m = useMessages()
  return <div>{m(message, { name: 'Jane' })}</div> // Restituirà "Ciao, Jane!"
}

Riepilogo

Questa release si concentra sul rendere gt-next più intuitivo per gli sviluppatori, riducendo al minimo l’overhead dell’i18n. Eliminando la necessità di passare la funzione t() attraverso lo stack delle chiamate, la nuova funzione msg() offre un modo più pulito e naturale per tradurre le stringhe e semplifica notevolmente il processo di i18n.