ScriptForge. Serviço L10N

Este serviço disponibiliza vários métodos relacionados com a tradução de cadeias de caracteres, com um impacto mínimo no código-fonte do programa. Os métodos disponibilizados pelo serviço L10N podem ser utilizados principalmente para:

Crie ficheiros POT que possam ser utilizados como modelos para a tradução de todas as cadeias de texto do programa.
Obter cadeias traduzidas em tempo de execução para o idioma definido na propriedade Locale.

A sigla L10N significa «Localização» e refere-se a um conjunto de procedimentos destinados à tradução de software para um país ou região específicos.

Os ficheiros PO têm vindo a ser promovidos há muito tempo na comunidade do software livre como um meio de proporcionar interfaces de utilizador multilingues. Isto é conseguido através da utilização de ficheiros de texto legíveis por humanos, com uma estrutura bem definida que especifica, para qualquer idioma, a cadeia de caracteres do idioma de origem e a cadeia de caracteres localizada.

A principal vantagem do formato PO é a separação entre o programador e o tradutor. Os ficheiros PO são ficheiros de texto independentes, pelo que o programador pode enviar ficheiros de modelo POT aos tradutores, que, por sua vez, traduzirão o seu conteúdo e devolverão os ficheiros PO traduzidos para cada idioma suportado.

O serviço L10N baseia-se na implementação GNU dos ficheiros PO (objeto portátil). Para saber mais sobre este formato de ficheiro, visite Utilitários GNU gettext: Ficheiros PO.

Este serviço implementa os métodos abaixo indicados:

AddText: Utilizado pelo programador para criar um conjunto de cadeias de caracteres que serão traduzidas posteriormente.
AddTextsFromDialog: Extraia todas as cadeias de caracteres de uma instância do serviço Dialog.
ExportToPOTFile: Exporta as cadeias de caracteres adicionadas pelo método AddText para um ficheiro POT.
GetText: Obtém as cadeias traduzidas em tempo de execução.

Note-se que os dois primeiros métodos são utilizados para criar um conjunto de cadeias de texto traduzíveis e exportá-las para um ficheiro POT. No entanto, não é obrigatório criar ficheiros POT utilizando estes métodos. Uma vez que se trata de ficheiros de texto, o programador poderia tê-los criado utilizando qualquer editor de texto.

Chamada de serviço

Antes de utilizar o serviço L10N, é necessário carregar ou importar a biblioteca ScriptForge:

• As macros básicas requerem o carregamento da biblioteca ScriptForge através da seguinte instrução:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Os scripts Python requerem a importação do módulo scriptforge:
from scriptforge import CreateScriptService

Existem várias formas de invocar o serviço L10N utilizando até cinco argumentos opcionais que especificam a pasta onde os ficheiros PO estão armazenados, a localização e a codificação a utilizar, bem como um ficheiro PO de reserva e a respetiva codificação.

Sintaxe:

CreateScriptService("L10N", opt foldername: str, opt locale: str, encoding: str = "UTF-8", opt locale2: str, encoding2: str = "UTF-8"): svc

nome da pasta: A pasta que contém os ficheiros PO. Deve ser expressa na notação FileSystem.FileNaming.

locale: Uma cadeia de caracteres no formato «la-CO» (língua-PAÍS) ou apenas no formato «la» (língua).

codificação: O conjunto de caracteres a utilizar. A codificação predefinida é «UTF-8».

locale2: Uma cadeia de caracteres que especifica a localização alternativa a utilizar caso o ficheiro PO correspondente à localização definida no parâmetro locale não exista. Este parâmetro é expresso apenas na forma «la-CO» (língua-PAÍS) ou «la» (língua).

encoding2: O conjunto de caracteres do ficheiro PO de recurso correspondente ao argumento locale2. A codificação predefinida é «UTF-8».

Para saber mais sobre os nomes dos conjuntos de caracteres, visite a página Conjuntos de Caracteres da IANA. Tenha em atenção que o LibreOffice não implementa todos os conjuntos de caracteres existentes.

Exemplo:

Em Basic

O exemplo seguinte instancia o serviço L10N sem quaisquer argumentos opcionais. Isto ativará apenas os métodos AddText e ExportToPOTFile, o que é útil para criar ficheiros POT.


      GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
      Dim myPO As Variant
      Set myPO = CreateScriptService("L10N")

O exemplo abaixo especifica a pasta que contém os ficheiros PO. Como a localização não está definida, a instância do serviço utilizará a localização definida para a interface de utilizador do LibreOffice, que é a mesma localização definida na propriedade OfficeLocale do serviço Platform.


      Set myPO = CreateScriptService("L10N", "C:\myPOFiles")

O exemplo acima resultará num erro de execução se o ficheiro PO correspondente à localização OfficeLocale não existir na pasta especificada.

No exemplo abaixo, a localização é explicitamente definida como francês belga («fr-BE»), pelo que o serviço irá carregar o ficheiro «fr-BE.po» a partir da pasta «C:\myPOFiles». Se o ficheiro não existir, ocorrerá um erro.


      Set myPO = CreateScriptService("L10N", "C:\myPOFiles", "fr-BE", "UTF-8")

Para evitar erros, é possível especificar uma localização e uma codificação preferenciais e alternativas. O exemplo seguinte tentará, em primeiro lugar, carregar o ficheiro «fr-BE.po» a partir da pasta especificada e, caso este não exista, será carregado o ficheiro «en-US.po».


      Set myPO = CreateScriptService("L10N", "C:\myPOFiles", "fr-BE", "UTF-8", "en-US", "UTF-8")

Os ficheiros PO devem ser nomeados no formato «la-CO.po» ou «la.po», em que «la» se refere ao idioma e «CO» ao país. Alguns exemplos são: «en-US.po», «fr-BE.po» ou «fr.po».

Recomenda-se libertar os recursos após a utilização:


      Set myPO = myPO.Dispose()

Em Python

Os exemplos acima podem ser traduzidos para Python da seguinte forma:


      from scriptforge import CreateScriptService
      myPO = CreateScriptService('L10N')


      myPO = CreateScriptService('L10N', r'C:\myPOFiles')


      myPO = CreateScriptService('L10N', r'C:\myPOFiles', 'fr-BE')


      myPO = CreateScriptService('L10N', r'C:\myPOFiles', 'fr-BE', 'UTF-8', 'en-US', 'UTF-8')
      myPO = myPO.Dispose()

Podem coexistir várias instâncias do serviço L10N. No entanto, cada instância deve utilizar um diretório distinto para os seus ficheiros PO.

Características

Nome	Apenas leitura	Tipo	Descrição
Folder	Sim	String	A pasta que contém os ficheiros PO (consulte a propriedade FileSystem.FileNaming para saber mais sobre a notação utilizada).
Languages	Sim	Array	Uma matriz com índice zero que lista todos os nomes base (sem a extensão «.po») dos ficheiros PO encontrados na pasta Folder especificada.
Locale	Sim	String	A combinação de idioma e PAÍS atualmente ativa. Esta propriedade estará inicialmente vazia se o serviço tiver sido instanciado sem nenhum dos argumentos opcionais.

Lista de métodos do serviço L10N
AddText AddTextsFromDialog	ExportToPOTFile	GetText

AddText

Adiciona uma nova entrada à lista de cadeias de caracteres localizáveis. Esta ainda não pode existir.

O método devolve True se for bem-sucedido.

Sintaxe:

svc.AddText(context: str = '', msgid: str = '', comment: str = ''): bool

Parâmetros:

contexto: A chave para recuperar a cadeia traduzida com o método GetText. Este parâmetro tem um valor predefinido de "".

msgid: A cadeia de caracteres não traduzida, que corresponde ao texto que aparece no código do programa. Não pode estar vazia. O msgid torna-se a chave para recuperar a cadeia de caracteres traduzida através do método GetText quando o context está vazio.

A cadeia msgid pode conter qualquer número de marcadores de substituição (%1 %2 %3 ...) para modificar dinamicamente a cadeia em tempo de execução.

comentário: Comentário opcional a ser adicionado junto com a cadeia de caracteres para ajudar os tradutores.

Exemplo:

O exemplo abaixo cria um conjunto de cadeias de caracteres em inglês:

Em Basic


      myPO.AddText(, "This is a string to be included in a POT file")
      myPO.AddText("CTX1", "A string with a context")
      myPO.AddText(, "Provide a String value", Comment := "Do not translate the word String")

Em Python


      myPO.AddText(msgid = 'This is a string to be included in a POT file')
      myPO.AddText('CTX1', 'A string with a context')
      myPO.AddText(msgid = 'Provide a String value', comment = 'Do not translate the word String')

AddTextsFromDialog

Extrai automaticamente cadeias de texto de uma caixa de diálogo e adiciona-as à lista de cadeias de texto localizáveis. São extraídas as seguintes cadeias de texto:

O título da caixa de diálogo.
A legenda dos seguintes tipos de controlos: Botão, Caixa de seleção, Linha fixa, Texto fixo, Caixa de grupo e Botão de opção.
A legenda dos seguintes tipos de controlos: Botão, Caixa de seleção, Linha fixa, Texto fixo, Caixa de grupo e Botão de opção.
A dica de ferramenta ou o texto de ajuda apresentado quando se passa o rato por cima do controlo.

O método devolve True se for bem-sucedido.

A caixa de diálogo da qual serão extraídas as cadeias de caracteres não deve estar aberta quando o método for chamado.

Quando for criada uma instância do serviço L10N a partir de um ficheiro PO existente, utilize o método GetTextsFromL10N do serviço Dialog para carregar automaticamente todas as cadeias traduzidas na caixa de diálogo.

Sintaxe:

svc.AddTextsFromDialog(dialog: svc): bool

Parâmetros:

dialog: uma instância do serviço Dialog correspondente à caixa de diálogo da qual serão extraídas as cadeias de caracteres.

Exemplo:

O exemplo seguinte extrai todas as cadeias de caracteres da caixa de diálogo «MyDialog» armazenadas na biblioteca «Standard» e exporta-as para um ficheiro POT:

Em Basic


      oDlg = CreateScriptService("Dialog", "GlobalScope", "Standard", "MyDialog")
      myPO = CreateScriptService("L10N")
      myPO.AddTextsFromDialog(oDlg)
      myPO.ExportToPOTFile("C:\en-US.pot")

Em Python


      dlg = CreateScriptService("Dialog", "GlobalScope", "Standard", "Dialog1")
      myPO = CreateScriptService("L10N")
      myPO.AddTextsFromDialog(dlg)
      myPO.ExportToPOTFile("C:\en-US.pot")

ExportToPOTFile

Exporta um conjunto de cadeias de texto não traduzidas como um ficheiro POT.

Para criar um conjunto de cadeias de caracteres, pode utilizar uma sucessão de chamadas ao método AddText ou uma invocação bem-sucedida do serviço L10N com o argumento foldername presente. Também é possível utilizar uma combinação de ambas as técnicas.

O método devolve True se for bem-sucedido.

Sintaxe:

svc.ExportToPOTFile(filename: str, header: str = '', encoding:str = 'UTF-8'): bool

Parâmetros:

nome do ficheiro: O nome completo do ficheiro de saída na notação FileSystem.FileNaming.

cabeçalho: Comentários que serão adicionados no início do ficheiro POT gerado.

Não inclua quaisquer caracteres «#» no início. Se pretender que o cabeçalho seja dividido em várias linhas, insira sequências de escape (\n) sempre que for necessário. Será adicionado um cabeçalho padrão juntamente com o texto especificado no argumento header.

codificação: O conjunto de caracteres a utilizar (predefinição = «UTF-8»).

Exemplo:


       ' Basic
       myPO.ExportToPOTFile("C:\myFile.pot", Header := "First line of the header\nSecond line of the header")


      # Python
      myPO.ExportToPOTFile('C:\myFile.pot', header = 'First line of the header\nSecond line of the header')

O ficheiro gerado deve passar com sucesso no comando GNU msgfmt --check.

GetText

Recupera a cadeia traduzida correspondente ao argumento msgid fornecido.

É possível especificar uma lista de argumentos para substituir os marcadores de lugar (%1, %2, ...) na cadeia de caracteres.

Se não for encontrada nenhuma cadeia traduzida, o método devolve a cadeia não traduzida após substituir os marcadores de lugar pelos argumentos especificados.

Sintaxe:

Este método pode ser chamado tanto pelo nome completo GetText como pelo atalho _ (um único sublinhado):

svc.GetText(msgid: str, args: any[0..*]): str

svc._(msgid: str, args: any[0..*]): str

Na biblioteca ScriptForge, todos os métodos que começam com o carácter «_» estão reservados exclusivamente para uso interno. No entanto, o atalho _ utilizado para GetText é a única exceção a esta regra, pelo que pode ser utilizado com segurança em scripts Basic e Python.

Parâmetros:

msgid: A cadeia de caracteres não traduzida, que corresponde ao texto que aparece no código do programa. Não pode estar vazia. Pode conter qualquer número de marcadores de posição (%1 %2 %3 ...) que podem ser utilizados para inserir texto dinamicamente em tempo de execução.

Para além de utilizar uma única cadeia msgid, este método também aceita os seguintes formatos:

A cadeia de caracteres context com a qual o método irá recuperar o msgid no ficheiro PO, ou;
Uma combinação context|msgid, que instrui o método a recuperar o msgid utilizando o valor especificado de context. A segunda parte do argumento é utilizada para melhorar a legibilidade do código.

args: Valores a inserir nos marcadores de posição. É permitido qualquer tipo de variável, mas apenas serão considerados valores do tipo cadeia de caracteres, números e datas.

Exemplo:

Em Basic

Suponha que o código seguinte esteja a ser executado numa instalação do LibreOffice com a localização definida como «es-ES». Além disso, existe um ficheiro «es-ES.po» dentro da pasta especificada que traduz a cadeia de caracteres passada ao método GetText:


      myPO = CreateScriptService("L10N", "C:\myPOFiles\")
      myPO.GetText("Welcome %1! Hope you enjoy this program", "John")
      ' "¡Bienvenido John! Espero que disfrutes de este programa"

Em Python


      myPO = CreateScriptService('L10N', r"C:\myPOFiles")
      myPO.GetText('Welcome %1! Hope you enjoy this program', 'John')
      # "¡Bienvenido John! Espero que disfrutes de este programa"

Todas as rotinas ou identificadores do ScriptForge Basic que tenham o caractere de sublinhado «_» como prefixo estão reservados para uso interno. Não se destinam a ser utilizados em macros do Basic ou em scripts Python.

ScriptForge.FileSystem serviço

Tradução de controlos no editor de caixas de diálogo