Internazionalizzazione

Aggiungi il supporto multilingua alla tua app. Usa la Proyecta Content API per la localizzazione editoriale, oppure chiedi all’AI di configurare un framework i18n direttamente nel codice.

Proyecta supporta due approcci complementari per internazionalizzare le app che costruisci:

1. Localizzazione dei contenuti tramite la Proyecta Content API — per contenuti editoriali (articoli di blog, FAQ, testi di marketing) che devono essere tradotti in più lingue
2. i18n a livello di codice tramite un framework di traduzione — per le stringhe dell’interfaccia, date, valute e cambio di lingua in fase di esecuzione

Entrambi funzionano oggi. Quale scegliere dipende da cosa stai traducendo.

Proyecta stesso viene distribuito con 24 localizzazioni, quindi il prodotto conosce bene l’i18n. Gli stessi pattern si applicano alle app che costruisci al suo interno.

Opzione 1: Localizzazione dei contenuti (Proyecta Content API)

Se stai costruendo un sito ricco di contenuti — blog, knowledge base, pagine di marketing, catalogo prodotti — usa il supporto nativo per le localizzazioni. Indica all’AI quali lingue supporti ("Make the site available in English, Spanish and French") e le registrerà per te, con l’inglese come lingua predefinita. Poi recupera i contenuti nella lingua del visitatore.

Sul frontend, gli hook tipizzati per i contenuti del template risolvono i campi localizzati per te — passa la lingua attiva del visitatore e ogni campo localized viene restituito come singolo valore tradotto:

import { useCollection, useEntry } from '@/hooks/useContent';
import { useTranslation } from 'react-i18next';

function Blog({ slug }: { slug: string }) {
    const { i18n } = useTranslation();

    // List a collection in the current locale
    const { data: posts } = useCollection('posts', { locale: i18n.language });

    // Or read one entry by slug in the current locale
    const { data: post } = useEntry('posts', slug, { locale: i18n.language });

    // ...render posts / post
}

Internamente, il CMS segue una catena di fallback — la lingua richiesta → i suoi fallback configurati → la lingua predefinita — e riporta il codice effettivamente usato su ogni voce tramite localeResolved. Ometti locale per i siti in una sola lingua e i campi vengono restituiti come valori grezzi.

Questa è la scelta giusta quando:

• Chi traduce i contenuti non scrive codice
• Vuoi che le traduzioni siano versionabili
• Hai bisogno di pubblicazione specifica per lingua (la pubblicazione programmata è in arrivo — al momento le voci richiedono la pubblicazione manuale tramite API)

Consulta Gestione dei contenuti per la documentazione completa della Content API.

Opzione 2: Framework i18n a livello di codice

Per le stringhe dell’interfaccia — etichette, pulsanti, messaggi di errore, date, valute — chiedi all’AI di configurare un framework i18n direttamente nel tuo progetto:

Add internationalization to my app.
Support English, Spanish, French, and Arabic.
Add message catalogs in src/locales/.
Add a language switcher in the header.
Use locale-prefixed URLs like /en/about and /es/about.
Make sure RTL layout works correctly for Arabic.

L’AI si occuperà di:

1. Scegliere un framework — l’AI usa i18next con react-i18next (lo standard di Proyecta)
2. Creare i file di catalogo in src/locales/ (un JSON per lingua)
3. Racchiudere i testi nelle chiamate t() (dall’hook useTranslation di react-i18next)
4. Aggiungere un componente selettore della lingua
5. Configurare il routing degli URL con i prefissi di lingua
6. Gestire i layout RTL (dir="rtl") per l’arabo, l’ebraico, ecc.
7. Formattare numeri, date e valute in base alla lingua

Traduzione automatica con l’AI

Una volta che la lingua base è pronta, l’AI è molto efficace nel produrre gli altri file di catalogo:

• "Translate every string in src/locales/en.json into Spanish, French, German, and Japanese. Use natural, idiomatic phrasing — don't translate brand names."
• "My app is fully built in English. Add Spanish translations for everything and an es/ route prefix."

Per contenuti ad alto rischio (testi legali, medici, finanziari), fai revisionare l’output dell’AI da un traduttore umano prima di pubblicare.

Combinare entrambi gli approcci

La maggior parte delle app reali usa entrambi: i18n a livello di codice per la struttura dell’interfaccia (pulsanti, errori, navigazione) e la Content API per i contenuti editoriali (articoli, descrizioni di prodotto). Coesistono senza problemi — il tuo framework i18n gestisce i file di catalogo in fase di build, la Content API serve le voci localizzate in fase di esecuzione.

Best practice

1. Scegli la lingua base e finalizza i testi prima. Tradurre un target in continuo cambiamento è frustrante.
2. Traduci in batch. Non tradurre man mano — aspetta che una funzionalità sia stabile.
3. Testa l’RTL per tempo se supporti l’arabo o l’ebraico. I bug RTL rimangono nascosti finché non vai a cercarli.
4. Includi lang e dir sull’elemento <html>. Browser e screen reader ne dipendono.
5. Usa Intl per la formattazione. Non scrivere da zero la formattazione di date o valute — usa Intl.DateTimeFormat e Intl.NumberFormat.

Prossimamente

• Interfaccia di gestione delle lingue nel builder — scegli le lingue, visualizza la copertura delle traduzioni, modifica i cataloghi senza uscire da Proyecta
• Traduzione automatica al salvataggio per le nuove stringhe
• Template di progetto pronti per l’i18n con il framework già configurato