Conteúdo
Índice 🔎︎

# 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 três métodos listados abaixo:

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

- 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

Para invocar o serviço L10N, dois parâmetros adicionais podem ser especificados para determinar a pasta onde os arquivos PO estão localizados e as configurações de localização a serem usadas, conforme descrito abaixo:

### Sintaxe:

            CreateScriptService("L10N" [, FolderName As String [, Locale as String]])

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

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

Este serviço é totalmente compatível com as linguagens Basic e Python. Todos os exemplos são descritos usando a linguagem de programação Basic e podem ser facilmente convertidos para Python.

### Exemplo:

O exemplo a seguir cria uma instância do serviço L10N sem argumentos opcionais. Isto irá habilitar apenas os métodos AddText e ExportToPOTFile.

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

O exemplo abaixo especifica a pasta contendo os arquivos PO. Como a localidade não é definida, a instância do serviço usará as configurações de localização correntes do LibreOffice.

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

No exemplo abaixo, tanto o nome da pasta como as configurações de localização são explicitamente definidas para o idioma Português do Brasil.

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

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

## Propriedades

Nome | Somente leitura | Tipo | Descrição
Folder | Sim | String | Pasta contendo os arquivos PO (consulte a propriedade FileSystem.FileNaming para saber mais sobre a notação usada).
Languages | Sim | Array | Array indexado em zero listando todos os nomes base (nomes de arquivos PO sem a extensão ".po") dos arquivos encontrados na pasta especificada em Folder.
Locale | Sim | String | Combinação idioma-PAÍS atualmente ativa. Esta propriedade é inicializada como vazia se o serviço for instanciado sem que os argumentos opcionais tenham sido especificados.

Lista de Métodos no Serviço L10N
AddText | ExportToPOTFile | GetText

## AddText

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

### Sintaxe:

           myPO.AddText(Context As String, MsgId As String, [Comment As String]) As Boolean

### Parâmetros:

Context: Chave para recuperar a String traduzida com o método GetText. Este parâmetro tem como valor padrão uma String vazia "".

MsgId: A String não traduzida, que é o texto usado no código fonte do programa. Não pode ser uma String vazia. O valor MsgId torna-se a chave para recuperar a String traduzida usando o método GetText quando o parâmetro Context estiver vazio.

A String MsgId pode conter qualquer número de marcadores de posição (%1 %2 %3 ...) para dinamicamente modificar a string em tempo de execução.

Comment: Comentário adicional a ser incluído juntamente com a String com a finalidade de ajudar os tradutores.

### Exemplo:

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

## ExportToPOTFile

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

Para construir um conjunto de Strings você pode usar tanto uma sucessão de chamadas do método AddText, como invocar o serviço L10N com o parâmetro FolderName presente. Também é possível empregar uma combinação dessas duas técnicas.

### Sintaxe:

             myPO.ExportToPOTFile(FileName As String, [Header As String], [Encoding As String])

### Parâmetros:

FileName: Arquivo de saída especificado com a notação FileSystem.FileNaming.

Header: Comentários a serem inseridos no cabeçalho do arquivo POT gerado.

Não inclua o caractere inicial "#". Se você quiser que o cabeçalho seja quebrado em múltiplas linhas, insira a sequência de escape (\n) onde considerar necessário. Um cabeçalho padrão será inserido juntamente com o texto especificado no argumento Header.

Encoding: Codificação de caracteres a ser usada. O padrão é "UTF-8".

### Exemplo:

             myPO.ExportToPOTFile("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

Recupera a String traduzida correspondente ao argumento MsgId dado.

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.

### Sintaxe:

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

            myPO.GetText(MsgId As String[, Arg1[, Arg2[, ...]]]) As String
            myPO._(MsgId As String[, Arg1[, Arg2[, ...]]]) As String

Na biblioteca ScriptForge, todos os métodos que se iniciam com o caractere "_" são reservados para uso interno. Contudo, o atalho _ usado para o método GetText é a única exceção a esta regra, portanto pode ser usado em scripts Basic com segurança.

### Parâmetros:

MsgId: String não traduzida, a qual é usada 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 ...), os quais 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.

Arg1, ...: 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.

### Exemplo:

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:\MyPOFolder\")
          myPO.GetText("Welcome %1! Hope you enjoy this program", "John")
          ' "¡Bienvenido John! Espero que disfrutes de este programa"

Todas as rotinas básicas ou identificadores do ScriptForge que possuem o caractere "_" como prefixo são reservados apenas para uso interno. Elas não devem ser usadas em macros Basic.

Tópicos relacionados

Serviço ScriptForge.FileSystem

Tradução de controles no editor de diálogo