# 5. Lingua e senso di lettura #

← Temi · Sommario · Funzioni trasversali →

I componenti portano con sé le proprie etichette di interfaccia: menu contestuali, pulsanti dei dialoghi, azioni dei pannelli ancorabili, tooltip delle barre degli strumenti… Queste stringhe sono tradotte dalla libreria, senza che Lei debba fornirle.

## 5.1 Scegliere la lingua #

La lingua è globale al processo. La imposti una sola volta nell'oggetto applicazione, prima dell'apertura della prima finestra:

    // Event open dell'oggetto applicazione
    PBT_SetLanguage("fr")

Codice | Lingua
--- | ---
`en` | Inglese (predefinito)
`fr` | Francese
`de` | Tedesco
`it` | Italiano
`es` | Spagnolo
`pt` | Portoghese

Il dizionario viene iniettato prima del primo rendering di ogni componente: nessuna etichetta inglese lampeggia prima della traduzione. Il cambio a caldo è possibile — tutti i componenti aperti vengono rietichettati immediatamente.

    // Cambio di lingua da un menu dell'applicazione
    PBT_SetLanguage("de")

> Una lingua non si imposta componente per componente: un'applicazione mostra una sola lingua alla volta. È una scelta deliberata (coerenza dell'interfaccia), a differenza del tema che invece è sovrascrivibile localmente.

## 5.2 Adattare un'etichetta: `of_set_translation` #

Non è prigioniero dei dizionari forniti. `of_set_translation(chiave, testo)` sovrascrive una stringa di interfaccia, con priorità sul dizionario di lingua:

    // Vocabolario di settore: parlare di "sezioni" invece che di "pannelli"
    uo_dock.of_set_translation("dock.float", "Stacca la sezione")
    uo_dock.of_set_translation("dock.autohide", "Nascondi la sezione")
    uo_dock.of_set_translation("dock.closePanel", "Chiudi la sezione")

Due impieghi:

- Adattare il vocabolario al settore della Sua applicazione (« sezioni » invece di « pannelli », « filiali » invece di « gruppi »).
- Servire una lingua non fornita: imposti le proprie traduzioni chiave per chiave, nella lingua desiderata, a partire dalla propria tabella di traduzione.

    // Alimentare una lingua propria dal proprio archivio di traduzione
    uo_dock.of_set_translation("dock.float", of_traduire("DOCK_DETACHER"))
    uo_dock.of_set_translation("dock.show",  of_traduire("DOCK_AFFICHER"))

L'override è impostato sull'istanza; viene annullato da `of_reset()`.

### Le famiglie di chiavi #

Le chiavi seguono la forma `<dominio>.<nome>`. Le famiglie principali:

Prefisso | Riguarda
--- | ---
`dock.*` | Pannelli ancorabili: staccare, nascondere, chiudere
`toolbar.*` | Barra degli strumenti: spostare la barra, overflow
`tab.*` | Schede: chiudere
`tile.*` · `tilesbox.*` | Riquadri: dimensioni, messaggio « nessun riquadro »
`ribbon.*` | Barra multifunzione: ridurre, espandere
`mb.*` | Finestra di messaggio: pulsanti standard, mostrare / nascondere la password
`webbrowser.*` | Browser web: menu contestuale (indietro, avanti, ricaricare)
`picture.*` | Immagine: suggerimento di spostamento
`sb.*` | Barra di stato: il suo nome per gli screen reader
`color.*` | Selettore di colore: OK / Annulla

> 💡 Per conoscere la chiave esatta di un'etichetta, apra l'applicazione dimostrativa in inglese e poi in un'altra lingua: la stringa che cambia è quella del dizionario. L'elenco completo delle chiavi è fornito con la libreria.

## 5.3 Senso di lettura: da sinistra a destra / da destra a sinistra #

Per le lingue che si scrivono da destra a sinistra (arabo, ebraico), una sola chiamata ribalta l'intera applicazione:

    // Event open dell'oggetto applicazione
    PBT_SetFlowDirection("rtl")     // "ltr" per impostazione predefinita

Ciò che cambia in tutti i componenti, presenti e futuri:

- l'allineamento naturale dei testi e delle etichette;
- l'ordine delle colonne, delle schede, dei pulsanti della barra degli strumenti;
- il lato delle icone, delle frecce di espansione, dei chevron;
- il lato delle barre di scorrimento e dei pannelli laterali;
- il senso dei menu a discesa e dei popup.

    // Cambio a caldo
    PBT_SetFlowDirection("ltr")

Come il tema e la lingua, il senso di lettura viene iniettato prima del primo rendering: un componente creato dopo il cambio nasce già nel senso corretto.

> ⚠️ Il senso di lettura riguarda solo i componenti PBToolboxAI. I controlli PowerBuilder nativi delle Sue finestre (campi di immissione, DataWindow) restano a Suo carico.

## 5.4 Scrivere codice pronto per l'RTL #

Il ribaltamento è automatico per il layout. Non può esserlo per i valori che imposta Lei stesso: se scrive `"left"` in modo fisso, sarà a sinistra in entrambi i sensi di lettura.

Per questo motivo tutte le proprietà di posizionamento della libreria usano valori logici e non fisici:

Valore logico | Nella scrittura sinistra → destra | Nella scrittura destra → sinistra
--- | --- | ---
`start` | a sinistra | a destra
`end` | a destra | a sinistra

Sono esposti sotto forma di costanti, da leggere sull'oggetto a cui assegna il valore:

    // Allineamento del testo, posizione di una fascia...
    uo_titre.is_align      = uo_titre.ALIGN_START
    uo_onglets.is_position = uo_onglets.POSITION_START

Le famiglie interessate: `ALIGN_START` / `ALIGN_END` (statictext, statusbar, picture), `POSITION_START` / `POSITION_END` (tab, dockcontainer), `MARQUEE_START` / `MARQUEE_END` (statictext).

> I vecchi valori fisici `"left"` e `"right"` restano accettati ovunque: il Suo codice esistente continua a funzionare in modo identico. Sono semplicemente fissi — non si ribalteranno in `rtl`.

### Le due eccezioni volute #

Alcuni posizionamenti non hanno un « inizio di lettura »: restano fisici, ed è intenzionale.

- Toaster — un toast è una finestra di sistema ancorata a un angolo dello schermo. `POSITION_BOTTOM_RIGHT` indica un angolo fisico, non un'estremità di testo.
- Le superfici di disegno — organigramma, diagramma di flusso, grafo di nodi, ritaglio di immagine: vi si collocano elementi a coordinate `x`/`y`. Un piano cartesiano non si ribalta con la lingua; solo le etichette al suo interno seguono il senso di lettura.

## 5.5 Riepilogo #

Impostazione | Portata | Dove chiamarla
--- | --- | ---
`PBT_SetLanguage (string as_lang)` | Intero processo | `open` dell'oggetto applicazione
`of_set_translation (string as_clé, string as_texte)` | Una istanza | Dopo la creazione del componente
`PBT_SetFlowDirection (string as_sens)` | Intero processo | `open` dell'oggetto applicazione

Le tre impostazioni globali — tema, lingua, senso di lettura — si impostano insieme, nello stesso punto:

    // Event open dell'oggetto applicazione
    PBT_SetLicense(gs_titulaire, gs_cle_licence)
    PBT_SetDefaultTheme("fluent-light")
    PBT_SetLanguage("fr")
    PBT_SetFlowDirection("ltr")
    PBT_Warmup()

    Open(w_principale)

← Temi · Sommario · Funzioni trasversali →