Servei ScriptForge.L10N

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 methods listed below:

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

• AddTextsFromDialog: Extracts all strings from a Dialog service instance.

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

Invocació del servei

Abans d'utilitzar el servei L10N, cal carregar o importar la biblioteca ScriptForge:

• Per a carregar macros BASIC cal fer servir la biblioteca ScriptForge mitjançant aquesta expressió:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Els scripts Python requereixen una importació del mòdul scriptforge:
from scriptforge import CreateScriptService

There are several ways to invoke the L10N service using up to five optional arguments that specify the folder where PO files are stored, the locale and encoding to be used, as well as a fallback PO file and its encoding.

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

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.

encoding: The character set to be used. The default encoding is "UTF-8".

locale2: A string specifying the fallback locale to be used in case the PO file corresponding to the locale defined the locale parameter does not exist. This parameter is expressed in the form "la-CO" (language-COUNTRY) or "la" (language) only.

encoding2: The character set of the fallback PO file corresponding to the locale2 argument. The default encoding is "UTF-8".

To learn more about the names of character sets, visit IANA's Character Set page. Be aware that LibreOffice does not implement all existing character sets.

The following example instantiates the L10N service without any optional arguments. This will only enable the AddText and ExportToPOTFile methods, which is useful for creating POT files.

      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 locale defined for the LibreOffice user interface, which is the same locale defined in the OfficeLocale property of the Platform service.

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

The example above will result in an runtime error if the PO file corresponding to the OfficeLocale locale does not exist in the specified folder.

In the example below, the locale is explicitly defined to be Belgian French ("fr-BE"), hence the service will load the file "fr-BE.po" from the folder "C:\myPOFiles". If the file does not exist, an error will occur.

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

To avoid errors, it is possible to specify a preferred and a fallback locale and encoding. The following example will first try to load the file "fr-BE.po" from the specified folder and if it does not exist, the file "en-US.po" will be loaded.

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

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

Es recomana alliberar els recursos després de l'ús:

      Set myPO = myPO.Dispose()
    

Els exemples anteriors es poden traduir a Python d'aquesta manera:

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

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

Propietats

AddText

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

The method returns True if successful.

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

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.

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

      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

Automatically extracts strings from a dialog and adds them to the list of localizable text strings. The following strings are extracted:

• El títol del diàleg.

• The caption of the following control types: Button, CheckBox, FixedLine, FixedText, GroupBox and RadioButton.