Documentazione AEM as a Cloud Service Guida utente

Aggiungere una lingua per un modulo adattivo basato sui componenti core

Ultimo aggiornamento: 5 maggio 2025

Si applica a:
Experience Manager as a Cloud Service

Argomenti:
Moduli adattivi

Creato per:

Utente
Sviluppatore

Versione	Collegamento articolo
Componenti di base	Fai clic qui
Componenti core	Questo articolo

La funzionalità di supporto per la lingua da destra a sinistra è disponibile nel programma per l'adozione anticipata. Per partecipare al programma per i primi utilizzatori, richiedi l’accesso alla funzionalità inviando una e-mail dal tuo account ufficiale all’indirizzo aem-forms-ea@adobe.com.

AEM Forms fornisce supporto predefinito per le lingue inglese (en), spagnolo (es), francese (fr), italiano (it), tedesco (de), giapponese (ja), portoghese-brasiliano (pt-BR), cinese (zh-CN), cinese-Taiwan (zh-TW) e coreano (ko-KR). È possibile aggiungere il supporto anche per altre lingue, come Hindi(hi_IN). È inoltre possibile presentare Forms adattivo in una lingua RTL (Right-to-Left) come l’arabo, il persiano e l’urdu aggiungendo queste lingue.

video poster

https://video.tv.adobe.com/v/3433132/adaptive-forms-rtl--arabic-hebrew-farsi

In che modo AEM Forms determina le impostazioni locali di un modulo adattivo?

Per una corretta localizzazione è fondamentale comprendere in che modo AEM Forms seleziona le impostazioni locali per il rendering di un modulo adattivo. Ecco una suddivisione del processo di selezione:

Selezione delle impostazioni locali basata su priorità

Per determinare le impostazioni locali di un modulo adattivo, AEM Forms dà priorità ai seguenti metodi:

Selettore impostazioni locali URL ([impostazioni locali]):

Il sistema assegna la priorità alle impostazioni locali specificate nell'URL utilizzando il selettore [impostazioni locali]. Questo formato consente la memorizzazione nella cache per prestazioni migliori.

Formato: l'URL segue questo formato: http:/[URL server AEM Forms]/content/forms/af/[afName].[impostazioni locali].html?wcmmode=disabled.

Esempio: https://[server]/content/forms/af/contact-us.hi.html esegue il rendering del modulo in hindi.
afAcceptLang Parametro richiesta:

Per ignorare le impostazioni locali del browser dell'utente, è possibile utilizzare il parametro afAcceptLang nell'URL.

Esempio: https://[server]/forms/af/survey.ca-fr.html?afAcceptLang=ca-fr forza il rendering del modulo in francese canadese.
Impostazioni locali browser utente (intestazione Accept-Language):

Se non vengono specificate altre impostazioni locali, AEM Forms considera le impostazioni locali del browser dell'utente inviate utilizzando l'intestazione Accept-Language.

Meccanismo di fallback:

Se non è disponibile una libreria client (procedura per aggiungere una nuova lingua, descritta più avanti in questo documento) per le impostazioni locali richieste, AEM Forms verifica la presenza di una libreria basata sul codice della lingua.

Esempio: se viene richiesto en_ZA (inglese sudafricano) e non esiste una libreria en_ZA, utilizza en (inglese) se disponibile.

Se non viene trovata alcuna libreria client adatta, viene utilizzato il dizionario predefinito (principalmente en) per la lingua di creazione del modulo.

In assenza di informazioni sulle impostazioni internazionali, il modulo adattivo viene visualizzato nella lingua originale utilizzata durante lo sviluppo.

Prerequisiti per l'aggiunta di una lingua

Prima di iniziare ad aggiungere una nuova lingua per il Forms adattivo, verifica di disporre dei seguenti elementi:

Software:

Editor di testo normale (IDE): mentre qualsiasi editor di testo normale può funzionare, un ambiente di sviluppo integrato (IDE) come Microsoft Visual Studio Code offre funzionalità avanzate per semplificarne la modifica.
Git: questo sistema di controllo della versione è necessario per gestire le modifiche al codice. Se non è installato, scaricarlo da https://git-scm.com.

Archivio codici:

Clona l’archivio dei componenti core di Forms adattivi: per aggiungere una lingua è necessaria una libreria client da questo archivio. Per clonare l’archivio:

Apri la riga di comando o la finestra del terminale.
Passa alla posizione desiderata sul computer in cui desideri memorizzare l’archivio (ad esempio, /adaptive-forms-core-components).
Esegui il comando seguente per clonare l’archivio:
git clone https://github.com/adobe/aem-core-forms-components.git
Questo comando scarica l'archivio e crea una cartella denominata aem-core-forms-components nel computer. In questa guida questa cartella viene indicata come [Adaptive Forms Core Components repository].

Aggiungi una lingua

Per aggiungere il supporto per nuove lingue a un modulo adattivo basato su componenti core, effettua le seguenti operazioni:

Clonare l’archivio Git di AEM as a Cloud Service

Aprire la riga di comando e scegliere una directory in cui archiviare l'archivio AEM as a Cloud Service, ad esempio /cloud-service-repository/.
Esegui il comando seguente per clonare l’archivio:
git clone https://git.cloudmanager.adobe.com/<organization-name>/<program id>/
Per clonare l’archivio Git, sono necessarie alcune informazioni:
- Nome organizzazione: identifica il team o il progetto in Adobe Experience Manager as a Cloud Service (AEM as a Cloud Service).
- ID programma: specifica il programma associato all'archivio.
- Credenziali: è necessario un nome utente e una password (o un token di accesso personale) per accedere al repository in modo sicuro.
Dove trovare queste informazioni?

Per istruzioni dettagliate su come individuare questi dettagli, consulta l'articolo di Adobe Experience League "Accesso a Git".

Il progetto è pronto!

Al termine del comando viene visualizzata una nuova cartella creata nella directory locale. Questa cartella prende il nome dal programma (ad esempio, program-id). Questa cartella contiene tutti i file e il codice scaricati dall’archivio Git di AEM as a Cloud Service.

In questa guida questa cartella viene indicata come [AEMaaCS project directory].

Aggiungere le nuove impostazioni locali al servizio di localizzazione della Guida TV

Apri la cartella dell’archivio in un editor.
Individuare il file Guide Localization Service.cfg.json. Questo file controlla le lingue supportate dall’applicazione AEM Forms. È possibile modificare questo file per aggiungere una nuova lingua.
- File esistente: se il file esiste già, individualo nella directory del progetto AEM Forms. La posizione tipica è:
  [AEMaaCS project directory]/ui.config/src/main/content/jcr_root/apps/<appid>/osgiconfig/config`.
  Sostituisci <appid> con l'ID app specifico del progetto. Puoi trovare <appid> per il progetto AEM nel file archetype.properties.
- Nuovo file: se il file non esiste, è necessario crearlo nella stessa posizione indicata in precedenza. Non copiare e incollare il nome del file da questo documento, ma digitarlo manualmente. Il nome file Guide Localization Service.cfg.json include spazi. Questo è intenzionale e non è un errore di battitura nella documentazione.
  
  Di seguito è riportato un esempio di file con l'elenco delle impostazioni internazionali supportate da OOTB:
  { "supportedLocales":[ "en", "fr", "de", "ja", "pt-br", "zh-cn", "zh-tw", "ko-kr", "it", "es" ] }
Aggiungi al file il codice locale per la lingua desiderata.
1. Utilizzare Elenco di codici ISO 639-1 per trovare il codice di due lettere che rappresenta la lingua desiderata.
2. Includere il codice locale nel file Guide Localization Service.cfg.json. Di seguito sono riportati alcuni esempi:
  - Lingue da sinistra a destra:
    - Inglese (Stati Uniti): en-US
    - Spagnolo (Spagna): es-ES
    - Francese (Francia): fr-FR
  - Lingue da destra a sinistra:
    - Arabo (Emirati Arabi Uniti): ar-ae
    - Ebraico: he (o iw come riferimento storico)
    - Farsi: fa
Dopo aver apportato le modifiche, verificare che il file Guide Localization Service.cfg.json sia formattato correttamente come file JSON valido. Errori nella formattazione JSON possono impedirne il corretto funzionamento. Salva il file.

Utilizzo della libreria client di esempio per una facile aggiunta delle impostazioni internazionali

AEM Forms fornisce un'utile libreria client di esempio, clientlib-it-custom-locale, per semplificare l'aggiunta di nuove impostazioni internazionali. Questa libreria fa parte dell'archivio dei componenti core di Forms adattivi, disponibile su GitHub.

Prima di iniziare, assicurati di disporre di una copia locale dell'[archivio dei componenti core di Forms adattivi]. In caso contrario, puoi facilmente clonarlo utilizzando Git con il seguente comando:

git clone https://github.com/adobe/aem-core-forms-components.git

Questo comando scarica l’intero archivio, inclusa la libreria clientlib-it-custom-locale, in una directory denominata aem-core-forms-components sul computer.

Directory dellarchivio dei componenti core di Forms adattivi nel computer locale

Integrare la libreria client di esempio

Ora incorporiamo la libreria clientlib-it-custom-locale nella directory del progetto AEM as a Cloud Service [AEMaaCS]:

Individua la libreria client di esempio:

Nella copia locale dell'[archivio dei componenti core adattivi di Forms], passa al percorso seguente:
/aem-core-forms-components/it/apps/src/main/content/jcr_root/apps/forms-core-components-it/clientlibs
Copiare e incollare la libreria:
1. Copia la cartella clientlib-it-custom-locale.
2. Passa alla seguente directory all'interno della [directory del progetto AEMaaCS]:
  /ui.apps/src/main/content/jcr_root/apps/<app-id>/clientlib
  Importante: sostituisci <app-id> con l'ID effettivo dell'applicazione.
3. Incolla la cartella clientlib-it-custom-locale copiata in questa directory.
Aggiorna il percorso aemLangUrl in languageinit.js
1. Passa alla seguente directory all'interno della [directory del progetto AEMaaCS]:
  /ui.apps/src/main/content/jcr_root/apps/<app-id>/clientlib/clientlib-it-custom-locale/js
2. Apri il file languageinit.js nell'editor.
3. Individuare la riga seguente nel file languageinit.js:
  
  const aemLangUrl = /etc.clientlibs/forms-core-components-it/clientlibs/clientlib-it-custom-locale/resources/i18n/${lang}.json;
4. Sostituisci forms-core-components-it con il tuo <app-id> (ID effettivo dell'applicazione) nella riga precedente.
  
  const aemLangUrl = '/etc.clientlibs/<app-id>/clientlibs/clientlib-it-custom-locale/resources/i18n/${lang}.json';

NOTE

Se non sostituisci forms-core-components-it con il nome del progetto o <app-id>, la traduzione del componente selezione data non riesce.

Crea un file per la nuova lingua:

Passare alla directory delle impostazioni internazionali:

All'interno di [AEMaaCS project directory], passa al seguente percorso:
/ui.apps/src/main/content/jcr_root/apps/<program-id>/clientlibs/clientlib-it-custom-locale/resources/i18n/
Importante: sostituisci <program-id> con il tuo ID applicazione effettivo.
Individua il file di esempio in lingua inglese:

AEM Forms fornisce un file locale inglese di esempio (.json) su GitHub.

Il file in lingua inglese include il set di stringhe predefinito come riferimento. Il file specifico della lingua deve simulare la struttura del file in lingua inglese.

Per lingue come l'arabo, l'ebraico e il farsi, il testo legge da destra a sinistra (RTL) invece che da sinistra a destra (LTR) come l'inglese. Per garantire la corretta visualizzazione dei moduli in queste lingue, si consiglia di utilizzare i file locali di esempio come guida. Questi file forniscono un riferimento per la formattazione di testo, date e altri elementi per le lingue RTL. È possibile trovare i file delle impostazioni locali di esempio per:
- Arabo
- Ebraico
- farsi
Sfruttando questi file di esempio, è possibile garantire che i moduli forniscano un’esperienza fluida agli utenti che lavorano in lingue RTL.
Creare il file delle impostazioni internazionali:
1. Creare un nuovo file .json nella directory i18n.
2. Denomina il file utilizzando il codice locale appropriato per la lingua desiderata (ad esempio, fr-FR.json per il francese e ar-ae.json per l’arabo). La struttura di questo file deve rispecchiare il file delle impostazioni locali in inglese.
Struttura e traduzione:
1. Apri il file appena creato in un editor di testo.
2. Sostituisci i valori in inglese con le traduzioni corrispondenti per la tua lingua di destinazione.
3. Una volta completata la traduzione delle stringhe, salva il file.

Aggiunta del supporto delle impostazioni locali al dizionario

Questo passaggio si applica solo alle lingue diverse da quelle comunemente supportate: inglese (en), tedesco (de), spagnolo (es), francese (fr), italiano (it), portoghese brasiliano (pt-br), cinese (semplificato - zh_cn), cinese (tradizionale - zh_tw), giapponese (ja) e coreano (ko_kr).

Individua la cartella di configurazione:

Passa alla seguente directory nella directory del progetto [AEMaaCS]:
/ui.content/src/main/content/jcr_root/etc
Crea le cartelle necessarie (se mancanti):

Se la cartella etc non esiste nella cartella jcr_root, creala. All'interno di etc, creare un'altra cartella denominata languages se manca.
Creare il file di configurazione delle impostazioni locali:

Nella cartella languages, creare un nuovo file denominato .content.xml. Non copiare e incollare il nome del file da questo documento, ma digitarlo manualmente.

Apri questo file e incolla il seguente contenuto, sostituendo [LOCALE_CODE] con il codice locale effettivo (ad esempio, ar-ae per arabo).
<?xml version="1.0" encoding="UTF-8"?> <jcr:root xmlns:jcr="http://www.jcp.org/jcr/1.0" xmlns:nt="http://www.jcp.org/jcr/nt/1.0" jcr:primaryType="nt:unstructured" languages="[de,es,fr,it,pt-br,zh-cn,zh-tw,ja,ko-kr,hi]"/>
AVVISO: non sostituire l'elenco esistente. Aggiungi invece il nuovo codice locale tra parentesi quadre, separate da virgole, come segue (utilizzando ar-ae come esempio):
languages="[de,es,fr,it,pt-br,zh-cn,zh-tw,ja,ko-kr,hi,ar-ae]"
Includi le nuove cartelle nel file filter.xml:

Passa al file /ui.content/src/main/content/meta-inf/vault/filter.xml nella directory del progetto [AEMaaCS].

Apri il file e aggiungi la seguente riga alla fine:
<filter root="/etc/languages"/>
Salva il file.

Distribuire le nuove impostazioni locali create nell'ambiente AEM

Ora tutti potete utilizzare le nuove impostazioni internazionali con il vostro Forms adattivo. È possibile

Distribuire la directory di progetto AEM as a Cloud Service [AEMaaCS] nell'ambiente di sviluppo locale per provare la nuova configurazione locale nel computer locale. Per implementare nell’ambiente di sviluppo locale:
1. Assicurati che l’ambiente di sviluppo locale sia operativo. Se non hai già configurato un ambiente di sviluppo locale, consulta la guida su Configurare l'ambiente di sviluppo locale per AEM Forms.
2. Aprire la finestra del terminale o il prompt dei comandi.
3. Passa alla [directory del progetto AEMaaCS]
4. Esegui il comando seguente:
  mvn -PautoInstallPackage clean install
Distribuisci la directory del progetto AEM as a Cloud Service [AEMaaCS] nell'ambiente di Cloud Service. Per eseguire l’implementazione nell’ambiente di Cloud Service:
1. Eseguire il commit delle modifiche:
  
  Dopo aver aggiunto la nuova configurazione delle impostazioni locali, eseguire il commit delle modifiche con un messaggio Git chiaro che descrive l'aggiunta delle impostazioni locali (ad esempio, "È stato aggiunto il supporto per [Nome impostazioni locali]").
2. Distribuisci il codice aggiornato:
  
  Attiva una distribuzione del codice tramite la pipeline full stack esistente. In questo modo viene automaticamente creato e distribuito il codice aggiornato con il nuovo supporto delle impostazioni internazionali.
  
  Se non hai già configurato una pipeline, consulta la guida su come impostare una pipeline per AEM Forms as a Cloud Service.

Anteprima di un modulo adattivo con le nuove impostazioni internazionali aggiunte

Questi passaggi ti guidano attraverso l’anteprima di un modulo adattivo con le nuove impostazioni locali aggiunte:

Accedi all’istanza AEM Forms as a Cloud Service.
Vai a Forms > Forms e documenti.
Selezionare un modulo adattivo e fare clic su Aggiungi dizionario. Viene visualizzata la procedura guidata Aggiungi dizionario al progetto di traduzione.
Specifica il Titolo progetto e seleziona le Lingue di destinazione dal menu a discesa nella procedura guidata Aggiungi dizionario al progetto di traduzione.
Fai clic su Fine ed esegui il progetto di traduzione creato.
Vai a Forms > Forms e documenti.
Selezionare il modulo adattivo e scegliere l'opzione Anteprima come HTML.
Aggiungi &afAcceptLang=<locale-name> all'URL di anteprima e premi il tasto Invio. Sostituisci <locale-name> con il tuo codice locale effettivo. Il modulo adattivo viene visualizzato nella lingua specificata.

Procedure consigliate per il supporto della nuova localizzazione

Adobe consiglia di creare un progetto di traduzione dopo la creazione di un modulo adattivo. Ciò semplifica il processo di localizzazione.
Quando i componenti Casella numerica e Selettore data vengono convertiti in una lingua specifica, possono verificarsi problemi di formattazione. Per ovviare a questo problema, è stata incorporata un'opzione Lingua nella finestra di dialogo Configura del componente Selezione data e del componente Casella numerica.
Gestione dei nuovi campi:
- Traduzione automatica: se utilizzi la traduzione automatica, devi ricreare il dizionario ed eseguire nuovamente il progetto di traduzione dopo aver aggiunto nuovi campi a un modulo adattivo esistente. I nuovi campi aggiunti dopo il progetto di traduzione iniziale non vengono tradotti.
- Traduzione umana: per i flussi di lavoro di traduzione umana, esporta il dizionario utilizzando l'interfaccia utente in [AEM Forms Server]/libs/cq/i18n/gui/translator.html. Aggiorna il dizionario per i nuovi campi e carica la versione rivista.

Consulta anche

recommendation-more-help