# 5. Idioma e sentido de leitura #

← Temas · Índice · Funcionalidades transversais →

Os componentes incluem as suas próprias etiquetas de interface: menus de contexto, botões de diálogo, ações dos painéis acopláveis, tooltips das barras de ferramentas… Estas cadeias são traduzidas pela biblioteca, sem que seja necessário fornecê-las.

## 5.1 Escolher o idioma #

O idioma é global ao processo. Deve ser definido uma única vez no objeto aplicação, antes da abertura da primeira window:

    // Event open do objeto aplicacao
    PBT_SetLanguage("fr")

Código | Idioma
--- | ---
`en` | Inglês (predefinição)
`fr` | Francês
`de` | Alemão
`it` | Italiano
`es` | Espanhol
`pt` | Português

O dicionário é injetado antes da primeira representação de cada componente: nenhuma etiqueta inglesa pisca antes da tradução. A mudança a quente é possível — todos os componentes abertos são reetiquetados imediatamente.

    // Mudanca de idioma a partir de um menu da aplicacao
    PBT_SetLanguage("de")

> Um idioma não se define componente a componente: uma aplicação apresenta um único idioma de cada vez. Trata-se de uma opção deliberada (coerência da interface), ao contrário do tema, que pode ser substituído localmente.

## 5.2 Adaptar uma etiqueta: `of_set_translation` #

O utilizador não está preso aos dicionários fornecidos. `of_set_translation(chave, texto)` substitui uma cadeia de interface, com prioridade sobre o dicionário de idioma:

    // Vocabulario de negocio: falar de "seccoes" em vez de "paineis"
    uo_dock.of_set_translation("dock.float", "Desacoplar a seccao")
    uo_dock.of_set_translation("dock.autohide", "Ocultar a seccao")
    uo_dock.of_set_translation("dock.closePanel", "Fechar a seccao")

Dois usos:

- Adaptar o vocabulário ao negócio da aplicação («secções» em vez de «painéis», «agências» em vez de «grupos»).
- Servir um idioma não fornecido: definir traduções próprias, chave a chave, no idioma pretendido, a partir da tabela de tradução da aplicação.

    // Alimentar um idioma proprio a partir do repositorio de traducao
    uo_dock.of_set_translation("dock.float", of_traduire("DOCK_DETACHER"))
    uo_dock.of_set_translation("dock.show",  of_traduire("DOCK_AFFICHER"))

A substituição é definida na instância; é anulada por `of_reset()`.

### As famílias de chaves #

As chaves seguem a forma `<domínio>.<nome>`. As principais famílias:

Prefixo | Diz respeito a
--- | ---
`dock.*` | Painéis acopláveis: desacoplar, ocultar, fechar
`toolbar.*` | Barra de ferramentas: deslocar a barra, excedente
`tab.*` | Separadores: fechar
`tile.*` · `tilesbox.*` | Mosaicos: tamanhos, mensagem «nenhum mosaico»
`ribbon.*` | Friso: recolher, expandir
`mb.*` | Caixa de mensagem: botões padrão, mostrar / ocultar a palavra-passe
`webbrowser.*` | Navegador web: menu de contexto (retroceder, avançar, recarregar)
`picture.*` | Imagem: indicação de deslocamento
`sb.*` | Barra de estado: o seu nome para leitores de ecrã
`color.*` | Seletor de cor: OK / Cancelar

> 💡 Para conhecer a chave exata de uma etiqueta, abra a aplicação de demonstração em inglês e depois noutro idioma: a cadeia que muda é a do dicionário. A lista completa das chaves é fornecida com a biblioteca.

## 5.3 Sentido de leitura: da esquerda para a direita / da direita para a esquerda #

Para os idiomas que se escrevem da direita para a esquerda (árabe, hebraico), uma única chamada inverte toda a aplicação:

    // Event open do objeto aplicacao
    PBT_SetFlowDirection("rtl")     // "ltr" por predefinicao

O que isto altera em todos os componentes, presentes e futuros:

- o alinhamento natural dos textos e das etiquetas;
- a ordem das colunas, dos separadores, dos botões de barra de ferramentas;
- o lado dos ícones, das setas de expansão, dos chevrons;
- o lado das barras de deslocamento e dos painéis laterais;
- o sentido dos menus pendentes e dos popups.

    // Mudanca a quente
    PBT_SetFlowDirection("ltr")

Tal como o tema e o idioma, o sentido de leitura é injetado antes da primeira representação: um componente criado após a mudança nasce já no sentido correto.

> ⚠️ O sentido de leitura diz respeito apenas aos componentes PBToolboxAI. Os controlos PowerBuilder nativos das windows (campos de introdução, DataWindows) continuam a cargo do utilizador.

## 5.4 Escrever código preparado para o RTL #

O espelhamento é automático para a disposição. Não o pode ser para os valores definidos pelo próprio utilizador: se `"left"` for escrito de forma fixa, ficará à esquerda nos dois sentidos de leitura.

É por isso que todas as propriedades de posicionamento da biblioteca utilizam valores lógicos, e não físicos:

Valor lógico | Em escrita esquerda → direita | Em escrita direita → esquerda
--- | --- | ---
`start` | à esquerda | à direita
`end` | à direita | à esquerda

São expostos sob a forma de constantes, a ler no objeto ao qual o valor é atribuído:

    // Alinhamento de texto, posicao de uma faixa...
    uo_titre.is_align      = uo_titre.ALIGN_START
    uo_onglets.is_position = uo_onglets.POSITION_START

As famílias envolvidas: `ALIGN_START` / `ALIGN_END` (statictext, statusbar, picture), `POSITION_START` / `POSITION_END` (tab, dockcontainer), `MARQUEE_START` / `MARQUEE_END` (statictext).

> Os antigos valores físicos `"left"` e `"right"` continuam a ser aceites em todo o lado: o código existente continua a funcionar de forma idêntica. Estão simplesmente fixados — não se invertem em `rtl`.

### As duas exceções deliberadas #

Alguns posicionamentos não têm um «início de leitura»: mantêm-se físicos, e isso é intencional.

- Toaster — um toast é uma janela do sistema ancorada a um canto do ecrã. `POSITION_BOTTOM_RIGHT` designa um canto físico, não uma extremidade de texto.
- As superfícies de desenho — organigrama, diagrama de fluxo, grafo de nós, recorte de imagem: nelas são colocados elementos em coordenadas `x`/`y`. Um plano cartesiano não se inverte com o idioma; apenas as etiquetas no seu interior seguem o sentido de leitura.

## 5.5 Resumo #

Definição | Âmbito | Onde chamar
--- | --- | ---
`PBT_SetLanguage (string as_lang)` | Processo inteiro | `open` do objeto aplicação
`of_set_translation (string as_clé, string as_texte)` | Uma instância | Após a criação do componente
`PBT_SetFlowDirection (string as_sens)` | Processo inteiro | `open` do objeto aplicação

As três definições globais — tema, idioma, sentido de leitura — são estabelecidas em conjunto, no mesmo local:

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

    Open(w_principale)

← Temas · Índice · Funcionalidades transversais →