Usługa ScriptForge.L10N

Usługa ta udostępnia szereg metod związanych z tłumaczeniem ciągów znaków przy minimalnym wpływie na kod źródłowy programu. Metody udostępniane przez usługę L10N można wykorzystać głównie do:

Tworzenia plików POT, które można wykorzystać jako szablony do tłumaczenia wszystkich ciągów znaków w programie.
Uzyskania przetłumaczonych ciągów znaków w czasie wykonywania dla języka zdefiniowanego we właściwości Locale.

Akronim L10N oznacza lokalizację i odnosi się do zestawu procedur tłumaczenia oprogramowania na konkretny kraj lub region.

W świecie wolnego oprogramowania pliki PO od dawna są wykorzystywane do tworzenia wielojęzycznych interfejsów użytkownika. Są to czytelne dla człowieka pliki tekstowe o dobrze zdefiniowanej strukturze, które określają ciąg języka źródłowego i odpowiadający mu zlokalizowany ciąg znaków dla dowolnego języka.

Główną zaletą formatu PO jest oddzielenie programisty od tłumacza. Pliki PO są niezależnymi plikami tekstowymi, więc programista może wysyłać pliki szablonów POT do tłumaczy, którzy następnie przetłumaczą ich zawartość i zwrócą przetłumaczone pliki PO dla każdego obsługiwanego języka.

Usługa L10N opiera się na implementacji GNU plików PO (Portable Object). Aby dowiedzieć się więcej o tym formacie pliku, odwiedź GNU gettext Utilities: PO Files.

Usługa ta implementuje metody wymienione poniżej:

AddText: używana przez programistę do budowania zestawu ciągów znaków, które zostaną później przetłumaczone.
AddTextsFromDialog: wyodrębnia wszystkie ciągi z instancji usługi Dialog.
ExportToPOTFile: eksportuje ciągi dodane metodą AddText do pliku POT.
GetText: pobiera przetłumaczone ciągi w czasie wykonywania.

Należy zauważyć, że dwie pierwsze metody służą do zbudowania zestawu ciągów znaków do przetłumaczenia i wyeksportowania ich do pliku POT. Tworzenie plików POT przy użyciu tych metod nie jest jednak obowiązkowe. Ponieważ są to pliki tekstowe, programista mógł je utworzyć za pomocą dowolnego edytora tekstu.

Wywoływanie usługi

Przed użyciem usługi L10N należy załadować lub zaimportować bibliotekę ScriptForge:

• Podstawowe makra wymagają załadowania biblioteki ScriptForge przy użyciu następującej instrukcji:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Skrypty Pythona wymagają importu z modułu scriptforge:
from scriptforge import CreateScriptService

Istnieje kilka sposobów wywołania usługi L10N przy użyciu maksymalnie pięciu opcjonalnych argumentów, które określają folder, w którym przechowywane są pliki PO, ustawienia regionalne i używane kodowanie, a także zastępczy plik PO i jego kodowanie.

Składnia:

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

foldername: folder zawierający pliki PO. Musi być wyrażony w notacji FileSystem.FileNaming.

locale: ciąg znaków w postaci "la-CO" (język-KRAJ) lub tylko w postaci "la" (język).

encoding: zestaw znaków, który ma być używany. Domyślne kodowanie to „UTF-8”.

locale2: ciąg znaków określający zastępcze ustawienia regionalne, które mają być użyte w przypadku, gdy plik PO odpowiadający danym regionalnym definiuje parametr locale nie istnieje. Parametr ten jest wyrażony wyłącznie w formie "la-CO" (język-KRAJ) lub "la" (język).

encoding2: zestaw znaków zastępczego pliku PO odpowiadający argumentowi locale2. Domyślne kodowanie to "UTF-8".

Aby dowiedzieć się więcej o nazwach zestawów znaków, odwiedź stronę Zestaw znaków IANA. Należy pamiętać, że LibreOffice nie implementuje wszystkich istniejących zestawów znaków.

Przykład:

W języku Basic

Poniższy przykład tworzy instancję usługi L10N bez żadnych opcjonalnych argumentów. Spowoduje to włączenie tylko metod AddText i ExportToPOTFile, które są przydatne przy tworzeniu plików POT.


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

Poniższy przykład określa folder zawierający pliki PO. Ponieważ ustawienia regionalne nie są zdefiniowane, instancja usługi użyje ustawień regionalnych zdefiniowanych dla interfejsu użytkownika LibreOffice, czyli tych samych ustawień regionalnych, które zdefiniowano we właściwości OfficeLocale elementu usługi Platform


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

Powyższy przykład spowoduje błąd wykonania, jeśli plik PO odpowiadający ustawieniom OfficeLocale nie istnieje w określonym folderze.

W poniższym przykładzie ustawienia regionalne są wyraźnie zdefiniowane jako belgijski francuski ("fr-BE"), dlatego usługa załaduje plik "fr-BE.po" z folderu "C:\myPOFiles". Jeśli plik nie istnieje, wystąpi błąd.


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

Aby uniknąć błędów, można określić preferowane i zastępcze ustawienia regionalne oraz kodowanie. Poniższy przykład najpierw spróbuje załadować plik "fr-BE.po" z określonego folderu, a jeśli nie istnieje, zostanie załadowany plik "en-US.po".


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

Pliki PO muszą mieć nazwę w postaci "la-CO.po" lub "la.po", gdzie "la" odnosi się do języka, a "CO" to kraj. Oto kilka przykładów: "en-US.po", "fr-BE.po" lub "fr.po".

Zaleca się zwolnienie zasobów po użyciu:


      Set myPO = myPO.Dispose()

W języku Python

Powyższe przykłady można przetłumaczyć na język Python w następujący sposób:


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

Może współistnieć kilka instancji usługi L10N. Jednakże każda instancja musi używać osobnego katalogu dla swoich plików PO.

Właściwości

Nazwa	Tylko do odczytu	Typ	Opis
Folder	Tak	String	Folder zawierający pliki PO (zobacz właściwość FileSystem.FileNaming, aby poznać stosowaną notację ).
Languages	Tak	Array	Tablica liczona od zera zawierająca wszystkie nazwy podstawowe (bez rozszerzenia ".po") plików PO znalezionych w określonym Folderze.
Locale	Tak	String	Aktualnie aktywna kombinacja języka i KRAJU. Ta właściwość będzie początkowo pusta, jeśli instancja usługi została utworzona bez żadnych opcjonalnych argumentów.

Lista metod w usłudze L10N
AddText AddTextsFromDialog	ExportToPOTFile	GetText

AddText

Dodaje nowy wpis na liście ciągów możliwych do zlokalizowania. Nie może jeszcze istnieć.

Metoda zwraca wartość True, jeśli operacja się powiedzie.

Składnia:

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

Parametry:

context: klucz do pobrania przetłumaczonego ciągu za pomocą metody GetText. Ten parametr ma wartość domyślną "".

msgid: nieprzetłumaczony ciąg znaków, czyli tekst pojawiający się w kodzie programu. Nie musi być puste. msgid staje się kluczem do pobrania przetłumaczonego ciągu za pomocą metody GetText, gdy context jest pusty.

Ciąg msgid może zawierać dowolną liczbę symboli zastępczych (%1 %2 %3 ...) umożliwiających dynamiczną modyfikację ciągu w czasie wykonywania.

comment: opcjonalny komentarz do dodania obok ciągu znaków, aby pomóc tłumaczom.

Przykład:

Poniższy przykład tworzy zestaw ciągów w języku angielskim:

W języku 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")

W języku 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

Automatycznie wyodrębnia ciągi tekstowe z okna dialogowego i dodaje je do listy możliwych do zlokalizowania ciągów tekstowych. Wyodrębniane są następujące ciągi:

Tytuł okna dialogowego.
Opis następujących typów formantów: Button, CheckBox, FixLine, FixText, GroupBox i RadioButton.
Ciągi statyczne w elementach ListBox i ComboBox.
Podpowiedź lub tekst pomocy wyświetlany po najechaniu myszką na formant.

Metoda zwraca wartość True, jeśli operacja się powiedzie.

Okno dialogowe, z którego zostaną wyodrębnione ciągi znaków, nie może być otwarte w momencie wywołania metody.

Jeśli instancja usługi L10N zostanie utworzona z istniejącego pliku PO, wszystkie przetłumaczone ciągi znaków zostaną załadowane do okna dialogowego za pomocą GetTextsFromL10N z usługi Dialog.

Składnia:

svc.AddTextsFromDialog(dialog: svc): bool

Parametry:

dialog: instancja usługi Dialog odpowiadająca oknu dialogowemu, z którego zostaną wyodrębnione ciągi znaków.

Przykład:

Poniższy przykład wyodrębnia wszystkie ciągi znaków z okna dialogowego "MyDialog" zapisane w bibliotece "Standard" i eksportuje je do pliku POT:

W języku Basic


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

W języku Python


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

ExportToPOTFile

Eksportuje zestaw nieprzetłumaczonych ciągów znaków jako plik POT.

Aby zbudować zestaw ciągów znaków, możesz użyć serii wywołań metody AddText lub pomyślnego wywołania usługi L10N z argumentem foldername. Możliwe jest także zastosowanie kombinacji obu technik.

Metoda zwraca wartość True, jeśli operacja się powiedzie.

Składnia:

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

Parametry:

filename: pełna nazwa pliku wyjściowego w notacji FileSystem.FileNaming.

header: komentarze, które zostaną dodane na górze wygenerowanego pliku POT.

Nie dołączaj żadnych wiodących znaków "#". Jeśli chcesz, aby nagłówek został podzielony na wiele wierszy, wstaw tam, gdzie to konieczne, sekwencje specjalne (\n). Standardowy nagłówek zostanie dodany obok tekstu określonego w argumencie header.

encoding: zestaw znaków, który ma być używany (domyślnie = "UTF-8").

Przykład:


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

Wygenerowany plik powinien pomyślnie przejść polecenie GNU msgfmt --check.

GetText

Pobiera przetłumaczony ciąg odpowiadający podanemu argumentowi msgid.

Można określić listę argumentów zastępujących symbole zastępcze (%1, %2, ...) w ciągu.

Jeśli nie zostanie znaleziony żaden przetłumaczony ciąg, metoda zwraca nieprzetłumaczony ciąg po zastąpieniu symboli zastępczych określonymi argumentami.

Składnia:

Metodę tę można wywołać albo pełną nazwą GetText, albo skrótem _ (pojedynczy znak podkreślenia):

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

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

W bibliotece ScriptForge wszystkie metody zaczynające się od znaku „_” są zarezerwowane wyłącznie do użytku wewnętrznego. Jednak skrót _ używany do GetText jest jedynym wyjątkiem od tej reguły, dlatego można go bezpiecznie używać w skryptach Basic i Python.

Parametry:

msgid: nieprzetłumaczony ciąg znaków, czyli tekst pojawiający się w kodzie programu. Nie może być puste. Może zawierać dowolną liczbę symboli zastępczych (%1 %2 %3 ...), których można użyć do dynamicznego wstawiania tekstu w czasie wykonywania.

Oprócz użycia pojedynczego ciągu msgid ta metoda akceptuje także następujące formaty:

Ciąg context, za pomocą którego metoda pobierze msgid z pliku PO.
Kombinacja context|msgid instruująca metodę pobierania msgid przy użyciu określonej wartości context. Druga część argumentu służy poprawie czytelności kodu.

args: wartości, które mają zostać wstawione do symboli zastępczych. Dozwolony jest dowolny typ zmiennej, jednak pod uwagę będą brane tylko ciągi znaków, liczby i daty.

Przykład:

W języku Basic

Rozważmy, że następujący kod działa w instalacji LibreOffice z ustawieniami regionalnymi ustawionymi na "es-ES". Dodatkowo w podanym folderze znajduje się plik "es-ES.po", który tłumaczy ciąg znaków przekazany do metody GetText:


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

W języku 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"

Wszystkie podstawowe procedury lub identyfikatory ScriptForge poprzedzone znakiem podkreślenia „_” są zarezerwowane do użytku wewnętrznego. Nie należy ich używać w makrach Basic ani skryptach Pythona.

Usługa ScriptForge.FileSystem

Tłumaczenie formantów w edytorze okien dialogowych