# 5. Langue et sens de lecture #

← Thèmes · Sommaire · Fonctions transverses →

Les composants comportent leurs propres libellés d'interface : menus contextuels, boutons de dialogue, actions des panneaux dockables, info-bulles des barres d'outils… Ces chaînes sont traduites par la bibliothèque, sans que vous ayez à les fournir.

## 5.1 Choisir la langue #

La langue est globale au processus. Posez-la une fois dans l'objet application, avant l'ouverture de la première fenêtre :

    // Event open de l'objet application
    PBT_SetLanguage("fr")

Code | Langue
--- | ---
`en` | Anglais (défaut)
`fr` | Français
`de` | Allemand
`it` | Italien
`es` | Espagnol
`pt` | Portugais

Le dictionnaire est injecté avant le premier rendu de chaque composant : aucun libellé anglais ne clignote avant la traduction. Le changement à chaud est possible — tous les composants ouverts se re-libellent immédiatement.

    // Bascule de langue depuis un menu de l'application
    PBT_SetLanguage("de")

> Une langue ne se règle pas composant par composant : une application affiche une seule langue à la fois. C'est un choix délibéré (cohérence de l'interface), à l'inverse du thème qui, lui, est surchargeable localement.

## 5.2 Adapter un libellé : `of_set_translation` #

Vous n'êtes pas prisonnier des dictionnaires livrés. `of_set_translation(clé, texte)` surcharge une chaîne d'interface, en priorité sur le dictionnaire de langue :

    // Vocabulaire metier : parler de "volets" plutot que de "panneaux"
    uo_dock.of_set_translation("dock.float", "Detacher le volet")
    uo_dock.of_set_translation("dock.autohide", "Masquer le volet")
    uo_dock.of_set_translation("dock.closePanel", "Fermer le volet")

Deux usages :

- Adapter le vocabulaire au métier de votre application (« volets » plutôt que « panneaux », « agences » plutôt que « groupes »).
- Servir une langue non fournie : posez vos propres traductions clé par clé, dans la langue de votre choix, depuis votre propre table de traduction.

    // Alimenter une langue maison depuis votre referentiel de traduction
    uo_dock.of_set_translation("dock.float", of_traduire("DOCK_DETACHER"))
    uo_dock.of_set_translation("dock.show",  of_traduire("DOCK_AFFICHER"))

La surcharge est posée sur l'instance ; elle est annulée par `of_reset()`.

### Les familles de clés #

Les clés suivent la forme `<domaine>.<nom>`. Les principales familles :

Préfixe | Concerne
--- | ---
`dock.*` | Panneaux dockables : détacher, masquer, fermer
`toolbar.*` | Barre d'outils : déplacer la barre, débordement
`tab.*` | Onglets : fermer
`tile.*` · `tilesbox.*` | Tuiles : tailles, message « aucune tuile »
`ribbon.*` | Ruban : réduire, développer
`mb.*` | Boîte de message : boutons standard, afficher / masquer le mot de passe
`webbrowser.*` | Navigateur : menu contextuel (précédent, suivant, actualiser)
`picture.*` | Image : indication de déplacement
`sb.*` | Barre d'état : son nom pour les lecteurs d'écran
`color.*` | Sélecteur de couleur : OK / Annuler

> 💡 Pour connaître la clé exacte d'un libellé, ouvrez l'application de démonstration en anglais puis dans une autre langue : la chaîne qui change est celle du dictionnaire. La liste complète des clés est fournie avec la bibliothèque.

## 5.3 Sens de lecture : gauche-à-droite / droite-à-gauche #

Pour les langues qui s'écrivent de droite à gauche (arabe, hébreu), un seul appel bascule toute l'application :

    // Event open de l'objet application
    PBT_SetFlowDirection("rtl")     // "ltr" par defaut

Ce que cela change dans tous les composants, présents et futurs :

- l'alignement naturel des textes et des libellés ;
- l'ordre des colonnes, des onglets, des boutons de barre d'outils ;
- le côté des icônes, des flèches d'expansion, des chevrons ;
- le côté des barres de défilement et des panneaux latéraux ;
- le sens des menus déroulants et des popups.

    // Bascule a chaud
    PBT_SetFlowDirection("ltr")

Comme le thème et la langue, le sens de lecture est injecté avant le premier rendu : un composant créé après la bascule naît déjà dans le bon sens.

> ⚠️ Le sens de lecture ne concerne que les composants PBToolboxAI. Les contrôles PowerBuilder natifs de vos fenêtres (champs de saisie, DataWindows) restent à votre charge.

## 5.4 Écrire du code prêt pour le RTL #

Le miroir est automatique pour la mise en page. Il ne peut pas l'être pour les valeurs que vous posez vous-même : si vous écrivez `"left"` en dur, ce sera à gauche dans les deux sens de lecture.

C'est pourquoi toutes les propriétés de placement de la bibliothèque utilisent des valeurs logiques, et non physiques :

Valeur logique | En écriture gauche → droite | En écriture droite → gauche
--- | --- | ---
`start` | à gauche | à droite
`end` | à droite | à gauche

Elles sont exposées sous forme de constantes, à lire sur l'objet auquel vous affectez la valeur :

    // Alignement de texte, position d'un bandeau...
    uo_titre.is_align      = uo_titre.ALIGN_START
    uo_onglets.is_position = uo_onglets.POSITION_START

Les familles concernées : `ALIGN_START` / `ALIGN_END` (statictext, statusbar, picture), `POSITION_START` / `POSITION_END` (tab, dockcontainer), `MARQUEE_START` / `MARQUEE_END` (statictext).

> Les anciennes valeurs physiques `"left"` et `"right"` restent acceptées partout : votre code existant continue de fonctionner à l'identique. Elles sont simplement figées — elles ne se retourneront pas en `rtl`.

### Les deux exceptions volontaires #

Certains placements n'ont pas de « début de lecture » : ils restent physiques, et c'est intentionnel.

- Toaster — un toast est une fenêtre système ancrée à un coin de l'écran. `POSITION_BOTTOM_RIGHT` désigne un coin physique, pas une extrémité de texte.
- Les surfaces de dessin — organigramme, diagramme de flux, graphe de nœuds, recadrage d'image : vous y placez des éléments à des coordonnées `x`/`y`. Un plan cartésien ne se retourne pas avec la langue ; seuls les libellés à l'intérieur suivent le sens de lecture.

## 5.5 Récapitulatif #

Réglage | Portée | Où l'appeler
--- | --- | ---
`PBT_SetLanguage (string as_lang)` | Processus entier | `open` de l'objet application
`of_set_translation (string as_clé, string as_texte)` | Une instance | Après création du composant
`PBT_SetFlowDirection (string as_sens)` | Processus entier | `open` de l'objet application

Les trois réglages globaux — thème, langue, sens de lecture — se posent ensemble, au même endroit :

    // Event open de l'objet application
    PBT_SetLicense(gs_titulaire, gs_cle_licence)
    PBT_SetDefaultTheme("fluent-light")
    PBT_SetLanguage("fr")
    PBT_SetFlowDirection("ltr")
    PBT_Warmup()

    Open(w_principale)

← Thèmes · Sommaire · Fonctions transverses →