# 5. Idioma y sentido de lectura #

← Temas · Índice · Funciones transversales →

Los componentes llevan sus propias etiquetas de interfaz: menús contextuales, botones de diálogo, acciones de los paneles acoplables, tooltips de las barras de herramientas… Estas cadenas están traducidas por la biblioteca, sin que usted tenga que proporcionarlas.

## 5.1 Elegir el idioma #

El idioma es global al proceso. Establézcalo una sola vez en el objeto aplicación, antes de la apertura de la primera ventana:

    // Event open del objeto aplicacion
    PBT_SetLanguage("fr")

Código | Idioma
--- | ---
`en` | Inglés (predeterminado)
`fr` | Francés
`de` | Alemán
`it` | Italiano
`es` | Español
`pt` | Portugués

El diccionario se inyecta antes de la primera representación de cada componente: ninguna etiqueta inglesa parpadea antes de la traducción. El cambio en caliente es posible: todos los componentes abiertos se vuelven a etiquetar inmediatamente.

    // Cambio de idioma desde un menu de la aplicacion
    PBT_SetLanguage("de")

> Un idioma no se ajusta componente por componente: una aplicación muestra un solo idioma a la vez. Es una decisión deliberada (coherencia de la interfaz), al contrario que el tema, que sí es anulable localmente.

## 5.2 Adaptar una etiqueta: `of_set_translation` #

Usted no es prisionero de los diccionarios entregados. `of_set_translation(clave, texto)` anula una cadena de interfaz, con prioridad sobre el diccionario de idioma:

    // Vocabulario de negocio: hablar de "secciones" en lugar de "paneles"
    uo_dock.of_set_translation("dock.float", "Desacoplar la seccion")
    uo_dock.of_set_translation("dock.autohide", "Ocultar la seccion")
    uo_dock.of_set_translation("dock.closePanel", "Cerrar la seccion")

Dos usos:

- Adaptar el vocabulario al negocio de su aplicación («secciones» en lugar de «paneles», «sucursales» en lugar de «grupos»).
- Ofrecer un idioma no incluido: establezca sus propias traducciones clave por clave, en el idioma que desee, a partir de su propia tabla de traducción.

    // Alimentar un idioma propio desde su repositorio de traduccion
    uo_dock.of_set_translation("dock.float", of_traduire("DOCK_DETACHER"))
    uo_dock.of_set_translation("dock.show",  of_traduire("DOCK_AFFICHER"))

La anulación se establece sobre la instancia; se cancela con `of_reset()`.

### Las familias de claves #

Las claves siguen la forma `<dominio>.<nombre>`. Las principales familias:

Prefijo | Se refiere a
--- | ---
`dock.*` | Paneles acoplables: desacoplar, ocultar, cerrar
`toolbar.*` | Barra de herramientas: mover la barra, desbordamiento
`tab.*` | Pestañas: cerrar
`tile.*` · `tilesbox.*` | Mosaicos: tamaños, mensaje «ningún mosaico»
`ribbon.*` | Cinta de opciones: contraer, expandir
`mb.*` | Cuadro de mensaje: botones estándar, mostrar / ocultar la contraseña
`webbrowser.*` | Navegador web: menú contextual (atrás, adelante, recargar)
`picture.*` | Imagen: indicación de desplazamiento
`sb.*` | Barra de estado: su nombre para los lectores de pantalla
`color.*` | Selector de color: Aceptar / Cancelar

> 💡 Para conocer la clave exacta de una etiqueta, abra la aplicación de demostración en inglés y después en otro idioma: la cadena que cambia es la del diccionario. La lista completa de las claves se entrega con la biblioteca.

## 5.3 Sentido de lectura: de izquierda a derecha / de derecha a izquierda #

Para los idiomas que se escriben de derecha a izquierda (árabe, hebreo), una sola llamada invierte toda la aplicación:

    // Event open del objeto aplicacion
    PBT_SetFlowDirection("rtl")     // "ltr" de forma predeterminada

Lo que esto cambia en todos los componentes, presentes y futuros:

- la alineación natural de los textos y de las etiquetas;
- el orden de las columnas, de las pestañas, de los botones de barra de herramientas;
- el lado de los iconos, de las flechas de expansión, de los galones;
- el lado de las barras de desplazamiento y de los paneles laterales;
- el sentido de los menús desplegables y de las ventanas emergentes.

    // Cambio en caliente
    PBT_SetFlowDirection("ltr")

Al igual que el tema y el idioma, el sentido de lectura se inyecta antes de la primera representación: un componente creado después del cambio nace ya en el sentido correcto.

> ⚠️ El sentido de lectura solo afecta a los componentes PBToolboxAI. Los controles PowerBuilder nativos de sus ventanas (campos de entrada, DataWindows) siguen siendo responsabilidad suya.

## 5.4 Escribir código preparado para el RTL #

El reflejo es automático para el diseño. No puede serlo para los valores que usted mismo establece: si escribe `"left"` de forma fija, estará a la izquierda en ambos sentidos de lectura.

Por eso todas las propiedades de colocación de la biblioteca utilizan valores lógicos, y no físicos:

Valor lógico | En escritura izquierda → derecha | En escritura derecha → izquierda
--- | --- | ---
`start` | a la izquierda | a la derecha
`end` | a la derecha | a la izquierda

Se exponen en forma de constantes, que deben leerse sobre el objeto al que asigna el valor:

    // Alineacion de texto, posicion de una banda...
    uo_titre.is_align      = uo_titre.ALIGN_START
    uo_onglets.is_position = uo_onglets.POSITION_START

Las familias afectadas: `ALIGN_START` / `ALIGN_END` (statictext, statusbar, picture), `POSITION_START` / `POSITION_END` (tab, dockcontainer), `MARQUEE_START` / `MARQUEE_END` (statictext).

> Los antiguos valores físicos `"left"` y `"right"` siguen siendo aceptados en todas partes: su código existente continúa funcionando de forma idéntica. Simplemente están fijados: no se invertirán en `rtl`.

### Las dos excepciones deliberadas #

Algunas colocaciones no tienen un «inicio de lectura»: siguen siendo físicas, y es intencionado.

- Toaster — un toast es una ventana del sistema anclada a una esquina de la pantalla. `POSITION_BOTTOM_RIGHT` designa una esquina física, no un extremo de texto.
- Las superficies de dibujo — organigrama, diagrama de flujo, grafo de nodos, recorte de imagen: en ellas usted coloca elementos en coordenadas `x`/`y`. Un plano cartesiano no se invierte con el idioma; solo las etiquetas de su interior siguen el sentido de lectura.

## 5.5 Resumen #

Ajuste | Alcance | Dónde llamarlo
--- | --- | ---
`PBT_SetLanguage (string as_lang)` | Proceso entero | `open` del objeto aplicación
`of_set_translation (string as_clé, string as_texte)` | Una instancia | Después de crear el componente
`PBT_SetFlowDirection (string as_sens)` | Proceso entero | `open` del objeto aplicación

Los tres ajustes globales — tema, idioma, sentido de lectura — se establecen juntos, en el mismo lugar:

    // Event open del objeto aplicacion
    PBT_SetLicense(gs_titulaire, gs_cle_licence)
    PBT_SetDefaultTheme("fluent-light")
    PBT_SetLanguage("fr")
    PBT_SetFlowDirection("ltr")
    PBT_Warmup()

    Open(w_principale)

← Temas · Índice · Funciones transversales →