Strategia di localizzazione per l’App

1. Perché pensare alla localizzazione proprio in ChatGPT App

Se avete realizzato normali applicazioni web, è probabile che la localizzazione vi abbia fatto pensare al classico i18n: stringhe dell’interfaccia, un paio di formati di date e numeri, dizionari — e traducete tutto con cura. In ChatGPT App è più divertente: c’è un terzo partecipante — il modello LLM stesso. Legge le vostre descrizioni degli strumenti, i prompt, i risultati, trae conclusioni e prende decisioni.

Cioè la lingua non è solo «come mostrare un testo in modo gradevole all’utente», ma anche «come il modello capirà cosa fa il vostro strumento, quando chiamarlo e quali argomenti passarci». Il pulsante «Acquista» può essere tradotto alla buona, l’utente capirà. Ma se descrivete in modo vago un tool che effettua un pagamento, in una miscela di russo e inglese, il modello potrebbe non chiamarlo mai, oppure chiamarlo in un modo completamente diverso da quello che vi aspettavate.

Un altro aspetto: ChatGPT già invia al vostro server MCP indizi su locale e posizione dell’utente — _meta["openai/locale"] e _meta["openai/userLocation"]. Ciò avviene a livello delle richieste MCP verso gli strumenti, così potete adattare testi e dati alla lingua e alla regione dell’utente. Quindi la piattaforma vi «fornisce» già il contesto, e il compito dello sviluppatore è sfruttarlo in modo ponderato.

Per questo, in questo modulo consideriamo la localizzazione come un aspetto architetturale di ChatGPT App, non come «abbiamo tradotto l’UI e ce ne siamo dimenticati».

2. Layer da localizzare

Guardiamo all’App come a una torta a strati. Ogni strato può (e spesso deve) essere localizzato. Per non perdersi, iniziamo dalla mappa.

Panoramica dei layer

Prima — una tabella generale, poi analizziamo i pezzi.

Di fatto questo è il primo layer della nostra mappa di localizzazione: poi aggiungeremo profondità (cosmetica/semantica), lingue ed elementi concreti.

Ora passiamo ai layer uno per uno.

Widget UI

Il layer più evidente è l’interfaccia del widget. In GiftGenius questo è:

• titoli dei blocchi;
• etichette dei campi («Destinatario», «Budget», «Interessi»);
• pulsanti («Trova un regalo», «Reimposta filtri»);
• suggerimenti nei campi di input («ad esempio, collega, mamma…»);
• messaggi di errore e stati vuoti («Nessun regalo trovato»).

In una classica app React questi sono i primi candidati da estrarre nei dizionari. Qui è lo stesso, con la precisazione che l’UI non è tutta l’App, ma solo una delle sue facce.

Più avanti nel modulo costruiremo un’architettura i18n corretta per il widget, ma già ora è importante fissare: non ci devono essere stringhe in JSX. Anche se al momento supportate una sola lingua, conviene strutturare subito i testi dell’UI.

Mini‑esempio con il nostro GiftGenius (per ora senza una vera libreria i18n):

type Locale = "en" | "ru";

const uiText = {
  en: {
    title: "GiftGenius: find a perfect present",
    recipientLabel: "Recipient",
  },
  ru: {
    title: "GiftGenius: trova il regalo perfetto",
    recipientLabel: "Destinatario",
  },
};

function GiftForm({ locale }: { locale: Locale }) {
  const t = uiText[locale];

  return (
    <div>
      <h2>{t.title}</h2>
      <label>{t.recipientLabel}</label>
      {/* altri campi */}
    </div>
  );
}

Qui non stiamo ancora facendo una «vera» localizzazione, ma stiamo già separando esplicitamente il layer dei testi UI.

Testi GPT e prompt

Il layer successivo — testi di sistema e di supporto, non visibili direttamente all’utente, che però influenzano molto il comportamento del modello:

• system‑prompt della vostra App («Sei un assistente per la scelta dei regali…»);
• template di spiegazioni che date al modello («Genera un breve riepilogo della scelta»);
• follow‑up predefiniti e suggerimenti per il modello («suggerisci all’utente di precisare il budget, se…»).

Anche questi testi possono (e spesso devono) essere localizzati. Un esempio semplice: se l’utente scrive in russo ma il vostro system‑prompt è interamente in inglese, il modello se la caverà, certo, ma vi private di un controllo preciso su stile e formulazioni per quella lingua.

Più avanti, nelle lezioni sugli strumenti per localizzare prompt e descrizioni (prompts/descriptions), vedremo come gestire con attenzione system‑prompt multilingue. Qui è importante sottolineare: i prompt sono un layer localizzabile al pari dell’UI.

Dati e contenuti

Poi vengono i vostri dati. Per GiftGenius è il catalogo dei regali: nomi, descrizioni, categorie, talvolta suggerimenti su come usare il regalo. Per un’App commerciale ci sono anche prezzi, valute, unità di misura, formati di date, ecc. Nelle specifiche del product feed per ChatGPT (il formato con cui descrivete i vostri prodotti e servizi per la piattaforma) questi campi testuali (title, description) e i prezzi sono messi in evidenza, affinché possano essere mostrati correttamente agli utenti all’interno di ChatGPT.

Se volete un’App globale, per il catalogo dei regali sorgono almeno queste domande:

• conserviamo nomi/descrizioni in più lingue;
• come scegliamo quale lingua restituire all’utente;
• cosa facciamo se la traduzione non c’è ancora (fallback);
• come mostriamo valute e formati di date/prezzi per regioni diverse.

Un piccolo esempio tipizzato per il catalogo:

type Locale = "en" | "ru";

interface LocalizedString {
  en: string;
  ru: string;
}

interface Gift {
  id: string;
  title: LocalizedString;
  description: LocalizedString;
  priceCents: number;
  currency: "USD" | "EUR" | "RUB";
}

function getLocalizedTitle(gift: Gift, locale: Locale) {
  return gift.title[locale] ?? gift.title.en;
}

Quindi la localizzazione non è solo frontend, ma anche struttura dei dati nel database e nelle risorse MCP. Torneremo su questo quando parleremo del Gateway (ponte tra ChatGPT e i vostri servizi) e del server MCP.

Descrizioni di tools e JSON Schema

Il quarto layer — descrizioni degli strumenti e dei loro argomenti. Attraverso esse il modello capisce quando deve chiamare il vostro tool e quali argomenti passargli. In MCP sono title, description dello strumento e description per i campi dello schema JSON.

La documentazione dell’Apps SDK sottolinea che il modello usa nomi, descrizioni e documentazione dei parametri per scegliere gli strumenti e costruire gli argomenti.

Un esempio ipotetico di strumento GiftGenius in un server MCP TypeScript:

server.registerTool(
  "suggest_gifts",
  {
    title: "Suggest gifts",
    description: "Suggest 3–5 gift ideas based on recipient profile.",
    inputSchema: {
      type: "object",
      properties: {
        recipient: {
          type: "string",
          description: "Who is the gift for (e.g. mother, colleague)?",
        },
      },
      required: ["recipient"],
    },
  },
  async ({ input }) => { /* ... */ }
);

Ora è tutto in inglese, il modello capisce benissimo. Ma se l’utente scrive in russo? Riuscirà comunque a collegare «mamma» a recipient, ma con campi complessi e termini di dominio aumenta la probabilità di errore. Nella lezione sulle strategie di localizzazione delle descrizioni discuteremo separatamente: descrizioni in inglese unico contro descrizioni localizzate.

A questo punto, nella mappa di localizzazione è importante solo notare: le descrizioni dei tools e del JSON Schema possono anch’esse essere localizzate, e questo influisce sul comportamento del modello.

Commerce e parte legale

Infine, un layer a cui spesso si pensa per ultimo — tutto ciò che riguarda denaro e testi legali:

• nomi di SKU e piani di abbonamento;
• campi title/description nei feed di commerce (prodotti, servizi, abbonamenti);
• Terms of Service, Privacy Policy, Refund Policy;
• email e notifiche (email, push), se l’App invia qualcosa fuori da ChatGPT;
• stati degli ordini ed errori di pagamento che mostrate all’utente («Pagamento rifiutato», «Non disponibile nella tua regione»).

Qui ci sono due aspetti: UX e legge. L’utente deve capire a cosa sta acconsentendo e per cosa paga, nella sua lingua. E allo stesso tempo le traduzioni devono essere giuridicamente corrette: talvolta i legali richiedono che siano considerati giuridicamente vincolanti solo i testi in una lingua (ad esempio, l’inglese), mentre le altre traduzioni siano «di riferimento».

Nella nostra mappa di localizzazione segniamo necessariamente commerce e contenuti legali come layer a parte, perché spesso serve un processo diverso (legali, compliance, allineamento dei testi con il marketing).

3. Profondità della localizzazione: «cosmetica» contro «semantica»

Quando diciamo «localizzare l’App», è utile distinguere due livelli di profondità: cosmetico e semantico.

Localizzazione cosmetica

La cosmetica è tutto ciò che cambia l’aspetto e la leggibilità, ma quasi non cambia il comportamento del sistema. Esempi:

• titoli e etichette tradotti sui pulsanti;
• placeholder tradotti nei campi di input;
• messaggi di errore «umani» nell’UI;
• testo localizzato di un banner marketing nel widget.

Per le app web classiche spesso ci si ferma qui. In ChatGPT App è una parte importante, ma solo la punta dell’iceberg.

Localizzazione semantica

La semantica è ciò che cambia il comportamento del modello e la logica dell’App. Qui la lingua influisce su:

• quale strumento sceglierà il modello;
• come compilerà gli argomenti dello strumento;
• quali dati riterrà «corretti» per quell’utente.

Esempi di localizzazione semantica:

• system‑prompt nella lingua dell’utente che imposta stile e regole di interazione;
• descrizioni dei tools e dei loro campi nella lingua in cui comunica l’utente;
• testi di suggerimenti/istruzioni differenti a seconda del contesto culturale;
• impostazioni dei formati di date/valute che influenzano il parsing e la generazione (31.12.2025 vs 12/31/2025).

Se avete localizzato solo la cosmetica ma non la semantica, la vostra App può sembrare localizzata, ma comportarsi «come inglese» sotto il cofano. Nella mappa di localizzazione è utile indicare chiaramente quali elementi sono critici per il comportamento del modello.

Per il nostro GiftGenius, ad esempio:

• la descrizione del campo budget nel JSON Schema («Budget in the user’s currency») — semantica;
• l’etichetta del pulsante «Trova un regalo» — cosmetica (importante per l’UX, ma il modello non la vede).

Ora che distinguiamo cosmetica e semantica, ha senso rispondere alla domanda: in quante lingue volete che l’App funzioni.

4. ChatGPT App monolingue vs multilingue

Prima di disegnare la mappa, chiarite l’ambizione: state facendo un’App strettamente monolingue o puntate a un pubblico multilingue.

App monolingue

Un’App monolingue è il caso in cui supportate consapevolmente una sola lingua. Per esempio, solo l’inglese.

UI del widget, prompt, descrizioni degli strumenti e dati — tutto in un’unica lingua. Questo semplifica molto la vita:

• un’unica codebase senza ramificazioni linguistiche;
• uno schema di catalogo (senza title_en, title_ru e simili);
• più semplice da mantenere e testare.

Chiaro però che il pubblico è limitato. Nel caso di ChatGPT App significa anche: se un utente arriva con un’altra locale, ChatGPT può comunque mostrare la vostra App, ma dovrà continuamente «traslare» la lingua dell’utente nella lingua interna dell’App. In alcune nicchie va bene, ma per un servizio consumer di regali — difficilmente.

App multilingue

Un’App multilingue è già una decisione architetturale. Qui:

• UI e testi vengono mostrati correttamente in base alla locale dell’utente;
• i dati (cataloghi, descrizioni prodotto) sono anch’essi legati a lingua/regione;
• descrizioni dei tools e system‑prompt possono variare per lingua;
• gli scenari di commerce tengono conto di valute locali, tasse, restrizioni.

In questo caso, un semplice if (locale === "ru") sparso nel codice non basta più. Serve un’architettura: dizionari, risorse localizzabili, un punto unico in cui memorizzare e trattare locale e userLocation, accordi tra widget e server MCP.

La documentazione dell’Apps SDK sottolinea esplicitamente che ChatGPT vi passa locale e userLocation in _meta quando chiama i vostri strumenti, proprio affinché possiate scegliere lato server la lingua corretta e il formato dei dati. Questo è il «carburante» per le App multilingue.

Piccolo confronto

Per chiarezza — un mini‑confronto:

A livello di corso partiremo dall’idea che GiftGenius diventi multilingue (almeno EN/RU), per mostrare uno schema «maturo». Ma molti accorgimenti saranno utili anche per un’App monolingue ben strutturata, se volete essere pronti a espandervi.

5. Dove la lingua influisce davvero sul modello

Ora evidenziamo i punti in cui la lingua influisce direttamente sul comportamento di ChatGPT.

Lingua dell’input utente vs lingua delle descrizioni dei tools

Immaginiamo:

• l’utente scrive: «Trova un regalo per un collega da 50 euro»;
• il vostro tool suggest_gifts è descritto solo in inglese;
• campi dello schema: recipient, budget, currency, interests.

Il modello deve:

1. decidere che in generale va chiamato suggest_gifts;
2. estrarre recipient = "colleague", budget = 50, currency = "EUR";
3. serializzare correttamente questo in argomenti JSON.

Se le descrizioni sono brevi e in un’altra lingua, il modello se la cava, ma la probabilità di riempire i campi in modo errato è maggiore. Per esempio, confondere budget con price_limit o passare un testo nel campo interests, perché nella descrizione del campo c’era qualcosa di vago come «Any extra info about the gift».

Con testo dell’utente in russo e descrizioni in inglese, il modello «salta» continuamente tra le lingue.

Variante con schema localizzato:

const locale = _meta?.["openai/locale"] ?? "en"; // fornito da ChatGPT 
const isRu = locale.startsWith("ru");

server.registerTool(
  "suggest_gifts",
  {
    title: isRu ? "Selezione di regali" : "Suggest gifts",
    description: isRu
      ? "Suggerisci 3–5 idee regalo in base al profilo del destinatario."
      : "Suggest 3–5 gift ideas based on recipient profile.",
    inputSchema: { /* ... */ },
  },
  async ({ input }) => { /* ... */ }
);

Qui è semplificato: in realtà è meglio generare le descrizioni una sola volta all’avvio del server, non a ogni chiamata, ma l’idea è chiara. Possiamo fornire a ChatGPT descrizioni diverse a seconda del locale, per facilitare al modello la comprensione dell’utente.

Lingua dei dati vs lingua della richiesta

Se il vostro catalogo regali è solo in inglese e l’utente interagisce in russo, il modello sceglierà nomi e descrizioni in inglese. A volte va bene, a volte no. Ma è più importante come formattate l’output:

• mostrate all’utente i title/description originali dal server;
• oppure il modello li parafrasa nella lingua dell’utente nel proprio testo;
• oppure il vostro tool restituisce già testo localizzato in base al locale.

Nell’Apps SDK i contenuti strutturati (structured content, i dati strutturati che restituite dai tools) e la risposta testuale possono esistere separatamente. Potete restituire dati strutturati (per esempio, JSON con campi del prodotto) e un testo separato per l’utente; il modello poi decide come renderizzarli o riformularli.

La localizzazione può avvenire a livello di server (dati) o a livello di modello (riformulazione nella lingua desiderata). Preparando la mappa è utile decidere dove volete mantenere la «fonte di verità».

System‑prompt e follow‑up

Se il vostro system‑prompt è solo in inglese e l’utente è italofono, il modello bilancerà continuamente due lingue. Può andare bene, ma a volte volete imporre un tono preciso: per esempio, nella versione italiana dell’App volete uno stile più informale, in quella inglese più formale.

Di conseguenza, nella mappa di localizzazione dovete segnare:

• system‑prompt EN;
• system‑prompt RU;
• template di follow‑up (EN/RU);
• qualsiasi suggerimento «rigido» nel prompt per gli strumenti.

6. Mappa di localizzazione per GiftGenius

Ora raccogliamo tutto ciò che abbiamo discusso su layer, profondità e lingue in una mappa esplicita di localizzazione per GiftGenius. Facciamo ciò che poi farete per la vostra App: costruire una mappa di localizzazione. L’idea è semplice: tabella con colonne per layer e tipo di entità e, in riga, elementi concreti.

Esempio di mappa

Ecco una mappa semplificata per GiftGenius (EN/RU):

suggest_gifts.description

budget.description

A sinistra raggruppiamo per layer, poi — gli elementi concreti. L’ultima colonna aiuta a capire cosa non si può modificare senza allineamento con chi progetta i prompt/il comportamento del modello: tutto ciò che è marcato come semantica influisce sul comportamento di GPT.

Piccolo abbozzo di codice

Per collegare la mappa al codice, si può introdurre un tipo semplice per le entità localizzabili:

type LocalizedTextKey =
  | "ui.title"
  | "ui.recipient_label"
  | "error.no_gifts"
  | "prompt.summary_intro";

type Locale = "en" | "ru";

type Messages = Record<Locale, Record<LocalizedTextKey, string>>;

const messages: Messages = {
  en: {
    "ui.title": "GiftGenius: find a perfect present",
    "ui.recipient_label": "Recipient",
    "error.no_gifts": "No gifts found",
    "prompt.summary_intro": "Here’s why these gifts fit:",
  },
  ru: {
    "ui.title": "GiftGenius: trova il regalo perfetto",
    "ui.recipient_label": "Destinatario",
    "error.no_gifts": "Nessun regalo trovato",
    "prompt.summary_intro": "Ecco perché questi regali sono adatti:",
  },
};

Questi stessi key possono poi essere usati sia nel widget sia nella formazione dei prompt sul server (a condizione che il locale venga passato lungo lo stack — sarà l’argomento della prossima lezione). Così, la vostra «mappa di localizzazione» diventa gradualmente un dizionario tipizzato, non un insieme sparso di stringhe.

7. Pratica: create la mappa di localizzazione per la vostra App

Prima di approfondire tecniche i18n e architettura Gateway/MCP, è importante fare un esercizio noioso ma utilissimo: descrivere onestamente cosa intendete localizzare.

Un buon approccio — aprire un qualsiasi editor (Google Sheets o Notion vanno benissimo) e creare una tabella con colonne:

• categoria/layer (UI, prompt, dati, tools, commerce e parte legale, errori);
• elemento (pulsante specifico, descrizione campo specifico, endpoint specifico con testo);
• esempio valore EN;
• esempio del valore in una seconda lingua (se già disponibile o almeno in bozza);
• etichetta «cosmetica/semantica/giuridicamente importante»;
• owner (chi è responsabile delle modifiche: frontend, server MCP, product, legale).

Poi passate sulla vostra App ed elencate onestamente tutto dove c’è testo o dove la lingua influisce sul formato dei dati.

Per GiftGenius verrebbe fuori più o meno una versione estesa della tabella sopra. Lungo il percorso quasi certamente scoprirete un paio di punti «nascosti»:

• costanti testuali nel codice dei server MCP (per esempio, messaggi di errore);
• valori di default nello structuredContent (per esempio, categorie che non mostravate nell’UI);
• vecchie etichette dei tools che non corrispondono più al comportamento effettivo.

Questo esercizio è particolarmente utile farlo prima di collegare la localizzazione a un processo di business reale (pagamenti, attivazioni di abbonamenti, documenti legali). Rinominare il tool charge_user in un sistema multilingue con ACP e testi legali poi è molto più doloroso.

In generale, se disegnate la mappa di localizzazione in anticipo e indicate onestamente cosa e in quali lingue intendete supportare, vi risparmiate molti grattacapi nei moduli successivi — quando entreranno in gioco MCP, Gateway, commerce e Store.

8. Errori tipici nella pianificazione della localizzazione

Errore n. 1: pensare che localizzazione = «tradurre i pulsanti».
Scenario molto comune: il team estrae con cura tutte le stringhe UI nei dizionari, le traduce ed è felice. Nel frattempo il system‑prompt resta solo in inglese, le descrizioni dei tools anche, e il catalogo prodotti contiene esclusivamente nomi in inglese. Di conseguenza, l’App sembra localizzata, ma il modello dentro continua a vivere nel suo mondo, e il comportamento rimane anglocentrico. Nella pratica questo si manifesta in raccomandazioni strane ed errori negli argomenti dei tools.

Errore n. 2: non distinguere cosmetica e semantica.
A volte il product chiede di «sistemare leggermente la formulazione» nella descrizione di uno strumento o nel system‑prompt, e lo sviluppatore cambia il testo come se fosse una semplice etichetta UI. Ma la description di un campo JSON Schema o una frase nel system‑prompt sono parte del contratto con il modello. Tali modifiche possono cambiare radicalmente come GPT chiama il vostro tool. Se non segnate in anticipo gli elementi semantici nella mappa di localizzazione, è facile rompere accidentalmente il comportamento dell’App.

Errore n. 3: partire con un caos multilingue senza architettura.
Molto allettante all’inizio spargere nel codice if (locale === "ru") e inserire stringhe in russo dove serve. Dopo un paio di settimane l’applicazione diventa un «inferno della localizzazione»: in un componente le stringhe sono nel dizionario, in un altro sono hardcoded in JSX, sul server c’è un terzo schema di naming per le chiavi. Più tardi agganciare un sistema i18n serio e uniformare tutto diventa molto più difficile.

Errore n. 4: dimenticare dati e denaro.
Anche team esperti spesso partono traducendo UI e prompt, ma trascurano che cataloghi prodotti, prezzi, valute e testi legali devono anch’essi tener conto di locale e userLocation. Nelle specifiche del product feed per ChatGPT è infatti definito in modo rigoroso quali campi testuali e prezzi servono per mostrare correttamente i prodotti all’utente. Se non prevedete la multilingua a livello dati, poi dovrete o duplicare il feed o fare migrazioni dolorose.

Errore n. 5: ignorare i segnali della piattaforma su locale e posizione.
ChatGPT già passa nelle chiamate MCP _meta["openai/locale"] e _meta["openai/userLocation"], così potete capire in che lingua e da quale regione interagiscono con voi. Alcuni sviluppatori comunque chiedono all’utente «Seleziona la lingua dell’interfaccia» al primo avvio e non usano questi segnali per scegliere risorse e prezzi. Il risultato è un UX peggiore e un’architettura più complessa del necessario.

Errore n. 6: non definire gli «owner» degli elementi localizzabili.
Quando tutto va in produzione, si scopre che le traduzioni si sono distribuite tra persone diverse: i frontender correggono testi UI, i backender — descrizioni dei tools, lo specialista ML — il system‑prompt, e i legali inviano una versione rivista dei Terms. Se nella mappa di localizzazione non indicate chi è responsabile di quale layer, le modifiche iniziano a entrare in conflitto e alcuni testi vengono aggiornati in un posto e non in un altro.