ScriptForge.L10N service

This service provides a number of methods related to the translation of strings with minimal impact on the program's source code. The methods provided by the L10N service can be used mainly to:

• Create POT files that can be used as templates for translation of all strings in the program.

• Get translated strings at runtime for the language defined in the Locale property.

The acronym L10N stands for Localization and refers to a set of procedures for translating software to a specific country or region.

PO files have long been promoted in the free software community as a means to providing multilingual user interfaces. This is accomplished through the use of human-readable text files with a well defined structure that specifies, for any given language, the source language string and the localized string.

The main advantage of the PO format is dissociation of the programmer and the translator. PO files are independent text files, so the programmer can send POT template files to translators, who will then translate their contents and return the translated PO files for each supported language.

The L10N service is based on the GNU implementation of PO (portable object) files. To learn more about this file format, visit GNU gettext Utilities: PO Files.

This service implements the three methods listed below:

• AddText: Used by the programmer to build a set of strings that will be translated later.

• ExportToPOTFile: Exports the strings added by the AddText method to a POT file.

• GetText: Gets the translated strings at runtime.

Note that the first two methods are used to build a set of translatable strings and export them to a POT file. However, it is not mandatory to create POT files using these methods. Since they are text files, the programmer could have created them using any text editor.

Service invocation

To invoke the L10N service, two optional arguments can be specified to determine the folder where PO files are located and the locale to be used, as described below.

Syntax:

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

FolderName: The folder containing the PO files. It must be expressed in the FileSystem.FileNaming notation.

Locale: A string in the form "la-CO" (language-COUNTRY) or in the form "la" (language) only.

Several instances of the L10N service may coexist. However, each instance must use a separate directory for its PO files.

This service is fully supported in both Basic and Python languages. All examples are expressed using the Basic programming language and can be easily converted to Python.

Example:

The following example instantiates the L10N service without any optional arguments. This will only enable the AddText and ExportToPOTFile methods.

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

The example below specifies the folder containing the PO files. Because the locale is not defined, the service instance will use the current LibreOffice locale settings.

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

In the example below, both the folder name and locale settings are explicitly defined to be Belgian French.

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

PO files must be named in the form "la-CO.po" or "la.po", where "la" refers to the language and "CO" is the country. Some examples are: "en-US.po", "fr-BE.po" or "fr.po".

It is recommended to free resources after use:

      Set myPO = myPO.Dispose()
    

Properties

AddText

Adds a new entry in the list of localizable strings. It must not exist yet.

Syntax:

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

Parameters:

Context: The key to retrieve the translated string with the GetText method. This parameter has a default value of "".

MsgId: The untranslated string, which is the text appearing in the program code. It must not be empty. The MsgId becomes the key to retrieve the translated string via GetText method when Context is empty.

The MsgId string may contain any number of placeholders (%1 %2 %3 ...) for dynamically modifying the string at runtime.

Comment: Optional comment to be added alongside the string to help translators.

Example:

The example below creates a set of strings in English:

       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

Exports a set of untranslated strings as a POT file.

To build a set of strings you can use either a succession of AddText method calls, or by a successful invocation of the L10N service with the FolderName argument present. It is also possible to use a combination of both techniques.

Syntax:

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

Parameters:

FileName: The output file in FileSystem.FileNaming notation.

Header: Comments that will be added on top of the generated POT file.

Do not include any leading "#" characters. If you want the header to be broken into multiple lines, insert escape sequences (\n) where relevant. A standard header will be added alongside the text specified in the Header argument.

Encoding: The character set to be used (Default = "UTF-8").

Example:

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

The generated file should successfully pass the msgfmt --check GNU command.

GetText

Gets the translated string corresponding to the given MsgId argument.

A list of arguments may be specified to replace the placeholders (%1, %2, ...) in the string.

If no translated string is found, the method returns the untranslated string after replacing the placeholders with the specified arguments.

Syntax:

This method can be called either by the full name GetText or by the shortcut _ (a single underscore):

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

In the ScriptForge library, all methods starting with the "_" character are reserved for internal use only. However, the shortcut _ used for GetText is the only exception to this rule, hence it can be safely used in Basic scripts.

Parameters:

MsgId: The untranslated string, which is the text appearing in the program code. It must not be empty. It may contain any number of placeholders (%1 %2 %3 ...) that can be used to dynamically insert text at runtime.

Besides using a single MsgId string, this method also accepts the following formats:

• The Context string with which the method will retrieve the MsgId in the PO file, or;

• A combination Context|MsgId, instructing the method to retrieve the MsgId using specified Context value. The second part of the argument is used to improve code readability.

Arg1, ...: Values to be inserted into the placeholders. Any variable type is allowed, however only strings, numbers and dates will be considered.

Example:

Consider the following code is running on a LibreOffice installation with locale set to "es-ES". Additionally, there is a file "es-ES.po" inside the specified folder that translates the string passed to the GetText method:

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

All ScriptForge Basic routines or identifiers that are prefixed with an underscore character "_" are reserved for internal use. They are not meant be used in Basic macros.