Serviço ScriptForge.L10N

Este serviço fornece diversos métodos relacionados à tradução de Strings com impacto mínimo no código fonte do programa. Os métodos disponibilizados pelo serviço L10N podem ser usados para:

• Criar arquivos POT que podem ser usados como modelos para tradução de todas as strings de um programa.

• Buscar Strings traduzidas durante a execução para o idioma definido na propriedade Locale.

A sigla L10N significa "Localization" (em inglês) e refere-se a um conjunto de procedimentos para tradução de softwares para países ou regiões específicas.

Arquivos PO têm sido promovidos na comunidade de software livre como um meio para fornecer interfaces de usuário em diversos idiomas. Isso é feito através de arquivos texto legíveis por humanos com uma estrutura bem definida que especifica, para qualquer idioma, a String no idioma original e a String traduzida.

A principal vantagem do formato PO é a dissociação do programador e o tradutor. Arquivos PO são arquivos texto independentes, então o programador pode enviar um modelo POT para o tradutor, que irá traduzir seu conteúdo e retornar um arquivo PO com a tradução de cada linguagem suportada.

O serviço L10N é baseado na implementação GNU dos arquivos PO (do inglês, "portable objects"). Para saber mais sobre esse formato de arquivos, visite a página GNU gettext Utilities: PO Files.

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

• AddText: Usado pelo programador para construir um conjunto de strings que serão traduzidas mais tarde.

• AddTextsFromDialog: Extrai todas as strings de uma instância do serviço Dialog.

• ExportToPOTFile: Exporta as Strings adicionados pelo método AddText para um arquivo no formato POT.

• GetText: Busca a String traduzida em tempo de execução.

Note que os primeiros dois métodos são usados para construir o conjunto de Strings a serem traduzidas e posteriormente exportá-las para um arquivo POT. Contudo, não é obrigatório criar os arquivos POT usando esses métodos. Como os arquivo POT são, na verdade, arquivos texto, o programador poderia tê-los criado independentemente usando qualquer editor de texto.

Invocação do serviço

Antes de usar o serviço L10N a biblioteca ScriptForge precisa ser carregada ou importada:

• Macros BASIC precisam carregar a biblioteca ScriptForge usando a seguinte instrução:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Scripts Python exigem uma importação do módulo scriptforge:
from scriptforge import CreateScriptService

Há várias formas de invocar o serviço L10N usando cinco argumentos opcionais que especificam a pasta onde os arquivos PO estão armazenados, a localidade e a codificação a ser usada, bem como o arquivo POs que será usado em caso de erro e sua codificação.

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

foldername: Pasta contendo os arquivos PO. Deve ser expresso usando a notação FileSystem.FileNaming.

locale: String no formato "la-CO" (language-COUNTRY - idioma-PAÍS) ou no formato "la" (apenas idioma).

encoding: Codificação de caracteres a ser usada. A codificação padrão é "UTF-8".

locale2: String especificando a localidade a ser usada em caso de erro, ou seja, quando o arquivo PO correspondente à localidade especificada no parâmetro locale não existir. Este parâmetro é expresso no formato "la-CO" (do inglês, language-COUNTRY, ou em português linguagem-PAÍS) ou apenas "la" (linguagem).

encoding2: O conjunto de caracteres do arquivo PO de reserva correspondente ao argumento locale2. A codificação padrão é "UTF-8".

Para saber mais sobre os nomes dos conjuntos de caracteres, visite a página IANA's Character Set (página somente no inglês). Note que o LibreOffice não implementa todos os conjuntos de caracteres existentes.

O exemplo a seguir cria uma instância do serviço L10N sem argumentos opcionais. Isto habilitará apenas os métodos AddText e ExportToPOTFile, os quais são úteis para a criação de arquivos POT.

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

O exemplo abaixo especifica o diretório que contém os arquivos PO. Como a localidade não foi definida, a instância do serviço usará a localidade definida para a interface do usuário do LibreOffice, que é a mesma localidade definida na propriedade OfficeLocale do serviço Platform.

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

O exemplo acima resultará em um erro de execução se o arquivo PO correspondente à localidade definida em OfficeLocale não existir no diretório especificado.

No exemplo abaixo, a localidade é explicitamente definida para Francês da Bélgica ("fr-BE"), logo o serviço irá carregar o arquivo "fr-BE.po" localizado no diretório "C:\myPOFiles". Se o arquivo não existir, um erro ocorrerá.

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

Para evitar erros, é possível especificar uma localidade e codificação de caracteres de preferência e de reserva. O exemplo a seguir primeiro tentará carregar o arquivo "fr-BE.po" do diretório especificado e se o arquivo não existir, o arquivo "en-US.po" será carregado.

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

Arquivos PO devem ser nomeados no formato "la-CO.po" ou "la.po", onde "la" refere-se ao idioma e "CO" refere-se ao país. Alguns exemplos são: "en-US.po", "fr-BE.po" ou "fr.po".

É recomendado liberar recursos após o uso:

      Set myPO = myPO.Dispose()
    

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

      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()
    

Várias instâncias do serviço L10N podem coexistir. Contudo, cada instância deve usar uma pasta diferente para os arquivos PO.

Propriedades

AddText

Adiciona uma nova entrada na lista de Strings a serem traduzidas. A nova String não pode existir previamente.

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

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

context: A chave para recuperar a string traduzida com o método GetText. Este parâmetro possui um valor padrão de "".

msgid: A string não traduzida, que é o texto que aparece no código do programa. Essa não deve estar vazia. A msgid torna-se a chave para recuperar a string traduzida via método GetText quando context está vazio.

A string msgid pode conter qualquer número de espaços reservados (%1 %2 %3 ...) para modificar dinamicamente a string em tempo de execução.

comment: Comentário opcional a ser adicionado ao lado da string para ajudar os tradutores.

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

      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")
    

      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 as strings de uma caixa de diálogo e as adiciona à lista de strings de texto traduzíveis. As seguintes strings são extraídas:

• O título da caixa de diálogo.

• Os rótulos dos seguintes tipos de controle: botão, caixa de seleção, linha fixa, texto fixo, caixa de grupo e botão de rádio.

• Strings estáticas em caixas de listas (ListBoxes) e caixas de combinação (ComboBoxes).

• A dica de ferramenta ou texto de ajuda exibido ao passar o mouse sobre o controle.

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

A caixa de diálogo da qual as strings serão extraídas não deve estar aberta ao chamar o método.

Quando criar uma instância de serviço L10N a partir de um arquivo PO existente, use o método GetTextsFromL10N do serviço Dialog para carregar automaticamente todas as strings traduzidas na caixa de diálogo.

svc.AddTextsFromDialog(dialog: svc): bool

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

O exemplo a seguir extrai todas as strings da caixa de diálogo "MyDialog" armazenada na biblioteca "Standard" e as exporta para um arquivo POT:

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

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

ExportToPOTFile

Exporta um conjunto de Strings não traduzidas para um arquivo POT.

Para construir um conjunto de strings, você pode utilizar tanto uma sucessão de chamadas de método AddText ou por uma invocação bem-sucedida do serviço L10N com o presente argumento foldername. Também é possível utilizar uma combinação de ambas as técnicas.

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

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

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

header: Comentários que serão adicionados ao topo do arquivo POT gerado.

Não inclua nenhum caractere inicial "#". Se você deseja que o cabeçalho seja dividido em várias linhas, insira sequências de escape (\n) onde for relevante. Um cabeçalho padrão será adicionado ao lado do texto especificado no argumento header.

encoding: O conjunto de caracteres a ser utilizado (Padrão = "UTF-8").

       ' 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 arquivo gerado deve passar com sucesso pelo comando GNU msgfmt --check.

GetText

Obtém a string traduzida correspondente ao argumento informado msgid.

Uma lista de argumentos pode ser definida para substituir os marcadores de posição (%1, %2, ...) na String.

Se nenhuma String traduzida for encontrada, o método retorna a String sem tradução após substituir todos os marcadores de posição pelos argumentos especificados.

Este método pode ser chamado tanto por seu nome completo GetText como por seu nome reduzido _ (um único caractere underscore):

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 caractere "_" são reservados apenas para uso interno. Entretanto, o atalho _ utilizado para GetText é a única exceção a essa regra, portanto, pode ser usado com segurança em scripts Basic e Python.

MsgId: A string não traduzida, que é o texto que aparece no código fonte do programa. Não pode ser uma string vazia. Pode conter um número qualquer de marcadores de posição (%1 %2 %3 ...), que podem ser usados para inserir textos dinamicamente em tempo de execução.

Além de usar uma única string msgId, este método também aceita os seguintes formatos:

• A string context com a qual o método irá recuperar o msgId no arquivo PO, ou;

• Uma combinação context|msgId, instruindo o método a recuperar o msgId usando um valor context especificado. A segunda parte do argumento é usada para melhorar a legibilidade do código.

args: Valores a serem inseridos nos marcadores de posição. Qualquer tipo de dados é permitido, porém apenas strings, números ou datas serão considerados.

Considere o código a seguir rodando em uma instalação do LibreOffice com a localidade definida para "es-ES". Além disso, há um arquivo "es-ES.po" dentro da pasta especificada que traduz as Strings passadas 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"
    

      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 em Basic que possuem o caractere "_" como prefixo são reservadas para uso interno. Elas não devem ser usadas em macros escritas em Basic ou em Python.