| blob | fcb87ef1471b95d0c97957cae10e41210f37e0e7 |
3 <script:module xmlns:script="http://openoffice.org/2000/script" script:name="SF_L10N" script:language="StarBasic" script:moduleType="normal">REM =======================================================================================================================
4 REM === The ScriptForge library and its associated libraries are part of the LibreOffice project. ===
5 REM === Full documentation is available on https://help.libreoffice.org/ ===
6 REM =======================================================================================================================
8 Option Compatible
9 Option ClassModule
10 'Option Private Module
12 Option Explicit
14 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
15 ''' L10N (aka SF_L10N)
16 ''' ====
17 ''' Implementation of a Basic class for providing a number of services
18 ''' related to the translation of user interfaces into a huge number of languages
19 ''' with a minimal impact on the program code itself
20 '''
21 ''' The design choices of this module are based on so-called PO-files
22 ''' PO-files (portable object files) have long been promoted in the free software industry
23 ''' as a mean of providing multilingual UIs. This is accomplished through the use of human-readable
24 ''' text files with a well defined structure that specifies, for any given language,
25 ''' the source language string and the localized string
26 '''
27 ''' To read more about the PO format and its ecosystem of associated toolsets:
28 ''' https://www.gnu.org/software/gettext/manual/html_node/PO-Files.html#PO-Files
29 ''' and, IMHO, a very good tutorial:
30 ''' http://pology.nedohodnik.net/doc/user/en_US/ch-about.html
31 '''
32 ''' The main advantage of the PO format is the complete dissociation between the two
33 ''' very different profiles, i.e. the programmer and the translator(s).
34 ''' Being independent text files, one per language to support, the programmer may give away
35 ''' pristine PO template files (known as POT-files) for a translator to process.
36 '''
38 ''' - AddText: for the programmer to build a set of words or sentences
39 ''' meant for being translated later
40 ''' - ExportToPOTFile: All the above texts are exported into a pristine POT-file
41 ''' - GetText: At runtime get the text in the user language
42 ''' Note that the first two are optional: POT and PO-files may be built with a simple text editor
43 '''
44 ''' Several instances of the L10N class may coexist
45 ' The constraint however is that each instance should find its PO-files
46 ''' in a separate directory
47 ''' PO-files must be named with the targeted locale: f.i. "en-US.po" or "fr-BE.po"
48 '''
49 ''' Service invocation syntax
51 ''' FolderName: the folder containing the PO-files (in SF_FileSystem.FileNaming notation)
52 ''' Locale: in the form la-CO (language-COUNTRY)
53 ''' Service invocation examples:
54 ''' Dim myPO As Variant
55 ''' myPO = CreateScriptService("L10N") ' AddText and ExportToPOTFile are allowed
56 ''' myPO = CreateScriptService("L10N", "C:\myPOFiles\", "fr-BE")
57 ''' 'All functionalities are available
58 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
60 REM =============================================================== PRIVATE TYPES
62 ''' The recognized elements of an entry in a PO file are (other elements are ignored) :
63 ''' #. Extracted comments (given by the programmer to the translator)
64 ''' #, flag (the kde-format flag when the string contains tokens)
65 ''' msgctxt Context (to store an acronym associated with the message, this is a distortion of the norm)
66 ''' msgid untranslated-string
67 ''' msgstr translated-string
68 ''' NB: plural forms are not supported
70 Type POEntry
71 Comment As String
72 Flag As String
73 Context As String
74 MsgId As String
75 MsgStr As String
76 End Type
78 REM ================================================================== EXCEPTIONS
82 REM ============================================================= PRIVATE MEMBERS
84 Private [Me] As Object
85 Private [_Parent] As Object
87 Private ServiceName As String
88 Private _POFolder As String ' PO files container
89 Private _Locale As String ' la-CO
90 Private _POFile As String ' PO file in URL format
92 Private _Dictionary As Object ' SF_Dictionary
94 REM ===================================================== CONSTRUCTOR/DESTRUCTOR
96 REM -----------------------------------------------------------------------------
97 Private Sub Class_Initialize()
98 Set [Me] = Nothing
99 Set [_Parent] = Nothing
102 _POFolder = ""
103 _Locale = ""
104 _POFile = ""
105 Set _Dictionary = Nothing
106 End Sub ' ScriptForge.SF_L10N Constructor
108 REM -----------------------------------------------------------------------------
109 Private Sub Class_Terminate()
111 If Not IsNull(_Dictionary) Then Set _Dictionary = _Dictionary.Dispose()
112 Call Class_Initialize()
113 End Sub ' ScriptForge.SF_L10N Destructor
115 REM -----------------------------------------------------------------------------
116 Public Function Dispose() As Variant
117 Call Class_Terminate()
118 Set Dispose = Nothing
119 End Function ' ScriptForge.SF_L10N Explicit Destructor
121 REM ================================================================== PROPERTIES
123 REM -----------------------------------------------------------------------------
124 Property Get Folder() As String
125 ''' Returns the FolderName containing the PO-files expressed as given by the current FileNaming
126 ''' property of the SF_FileSystem service. Default = URL format
127 ''' May be empty
128 ''' Example:
129 ''' myPO.Folder
133 End Property ' ScriptForge.SF_L10N.Folder
135 REM -----------------------------------------------------------------------------
136 Property Get Languages() As Variant
137 ''' Returns a zero-based array listing all the BaseNames of the PO-files found in Folder,
138 ''' Example:
139 ''' myPO.Languages
143 End Property ' ScriptForge.SF_L10N.Languages
145 REM -----------------------------------------------------------------------------
146 Property Get Locale() As String
147 ''' Returns the currently active language-COUNTRY combination. May be empty
148 ''' Example:
149 ''' myPO.Locale
153 End Property ' ScriptForge.SF_L10N.Locale
155 REM ===================================================================== METHODS
157 REM -----------------------------------------------------------------------------
158 Public Function AddText(Optional ByVal Context As Variant _
159 , Optional ByVal MsgId As Variant _
160 , Optional ByVal Comment As Variant _
161 , Optional ByVal MsgStr As Variant _
162 ) As Boolean
163 ''' Add a new entry in the list of localizable text strings
164 ''' Args:
165 ''' Context: when not empty, the key to retrieve the translated string via GetText. Default = ""
166 ''' MsgId: the untranslated string, i.e. the text appearing in the program code. Must not be empty
167 ''' The key to retrieve the translated string via GetText when Context is empty
168 ''' May contain placeholders (%1 ... %9) for dynamic arguments to be inserted in the text at run-time
169 ''' If the string spans multiple lines, insert escape sequences (\n) where relevant
170 ''' Comment: the so-called "extracted-comments" intended to inform/help translators
171 ''' If the string spans multiple lines, insert escape sequences (\n) where relevant
172 ''' MsgStr: (internal use only) the translated string
173 ''' If the string spans multiple lines, insert escape sequences (\n) where relevant
174 ''' Returns:
175 ''' True if successful
176 ''' Exceptions:
177 ''' DUPLICATEKEYERROR: such a key exists already
178 ''' Examples:
181 Dim bAdd As Boolean ' Output buffer
182 Dim sKey As String ' The key part of the new entry in the dictionary
183 Dim vItem As POEntry ' The item part of the new entry in the dictionary
186 Const cstSubArgs = "[Context=""""], MsgId, [Comment=""""]"
188 If SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
189 bAdd = False
191 Check:
192 If IsMissing(Context) Or IsMissing(Context) Then Context = ""
193 If IsMissing(Comment) Or IsMissing(Comment) Then Comment = ""
194 If IsMissing(MsgStr) Or IsMissing(MsgStr) Then MsgStr = ""
195 If SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
200 End If
201 If Len(MsgId) = 0 Then GoTo Finally
203 Try:
205 If _Dictionary.Exists(sKey) Then GoTo CatchDuplicate
207 With vItem
208 .Comment = Comment
209 If InStr(MsgId, "%") > 0 Then .Flag = "kde-format" Else .Flag = ""
210 .Context = Replace(Context, cstPipe, " ")
211 .MsgId = Replace(MsgId, cstPipe, " ")
212 .MsgStr = MsgStr
213 End With
214 _Dictionary.Add(sKey, vItem)
216 Finally:
217 AddText = bAdd
218 SF_Utils._ExitFunction(cstThisSub)
219 Exit Function
220 Catch:
221 GoTo Finally
222 CatchDuplicate:
223 SF_Exception.RaiseFatal(DUPLICATEKEYERROR, Iif(Len(Context) > 0, "Context", "MsgId"), sKey)
224 GoTo Finally
225 End Function ' ScriptForge.SF_L10N.AddText
227 REM -----------------------------------------------------------------------------
228 Public Function ExportToPOTFile(Optional ByVal FileName As Variant _
229 , Optional ByVal Header As Variant _
230 , Optional ByVal Encoding As Variant _
231 ) As Boolean
232 ''' Export a set of untranslated strings as a POT file
233 ''' The set of strings has been built either by a succession of AddText() methods
234 ''' or by a successful invocation of the L10N service with the FolderName argument
235 ''' The generated file should pass successfully the "msgfmt --check 'the pofile'" GNU command
236 ''' Args:
237 ''' FileName: the complete file name to export to. If it exists, is overwritten without warning
238 ''' Header: Comments that will appear on top of the generated file. Do not include any leading "#"
239 ''' If the string spans multiple lines, insert escape sequences (\n) where relevant
240 ''' A standard header will be added anyway
241 ''' Encoding: The character set that should be used
242 ''' Use one of the Names listed in https://www.iana.org/assignments/character-sets/character-sets.xhtml
243 ''' Note that LibreOffice probably does not implement all existing sets
245 ''' Returns:
246 ''' True if successful
247 ''' Examples:
248 ''' myPO.ExportToPOTFile("myFile.pot", Header := "Top comment\nSecond line of top comment")
250 Dim bExport As Boolean ' Return value
251 Dim oFile As Object ' Generated file handler
252 Dim vLines As Variant ' Wrapped lines
253 Dim sLine As String ' A single line
254 Dim vItems As Variant ' Array of dictionary items
255 Dim vItem As Variant ' POEntry type
256 Const cstSharp = "# ", cstSharpDot = "#. ", cstFlag = "#, kde-format"
257 Const cstTabSize = 4
258 Const cstWrap = 70
260 Const cstSubArgs = "FileName, [Header=""""], [Encoding=""UTF-8"""
262 If SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
263 bExport = False
265 Check:
266 If IsMissing(Header) Or IsMissing(Header) Then Header = ""
268 If SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
272 End If
274 Try:
275 Set oFile = SF_FileSystem.CreateTextFile(FileName, Overwrite := True, Encoding := Encoding)
276 If Not IsNull(oFile) Then
277 With oFile
278 ' Standard header
279 .WriteLine(cstSharp)
280 .WriteLine(cstSharp & "This pristine POT file has been generated by LibreOffice/ScriptForge")
281 .WriteLine(cstSharp & "Full documentation is available on https://help.libreoffice.org/")
282 ' User header
284 .WriteLine(cstSharp)
285 vLines = SF_String.Wrap(Header, cstWrap, cstTabSize)
286 For Each sLine In vLines
288 Next sLine
289 End If
290 ' Standard header
291 .WriteLine(cstSharp)
296 & "https://bugs.libreoffice.org/enter_bug.cgi?product=LibreOffice&bug_status=UNCONFIRMED&component=UI\n"))
297 .WriteLine(SF_String.Quote("POT-Creation-Date: " & SF_STring.Represent(Now()) & "\n"))
303 .WriteLine(SF_String.Quote("Content-Type: text/plain; charset=" & Encoding & "\n"))
308 ' Individual translatable strings
309 vItems = _Dictionary.Items()
310 For Each vItem in vItems
311 .WriteBlankLines(1)
312 ' Comments
314 For Each sLine In vLines
315 .WriteLine(cstSharpDot & SF_String.ExpandTabs(SF_String.Unescape(sLine), cstTabSize))
316 Next sLine
317 ' Flag
319 ' Context
322 End If
323 ' MsgId
324 vLines = SF_String.Wrap(vItem.MsgId, cstWrap, cstTabSize)
325 If UBound(vLines) = 0 Then
327 Else
329 For Each sLine in vLines
330 .WriteLine(SF_String.Quote(SF_String.Escape(sLine)))
331 Next sLine
332 End If
333 ' MsgStr
335 Next vItem
336 .CloseFile()
337 End With
338 End If
339 bExport = True
341 Finally:
342 If Not IsNull(oFile) Then Set oFile = oFile.Dispose()
343 ExportToPOTFile = bExport
344 SF_Utils._ExitFunction(cstThisSub)
345 Exit Function
346 Catch:
347 GoTo Finally
348 End Function ' ScriptForge.SF_L10N.ExportToPOTFile
350 REM -----------------------------------------------------------------------------
351 Public Function GetProperty(Optional ByVal PropertyName As Variant) As Variant
352 ''' Return the actual value of the given property
353 ''' Args:
354 ''' PropertyName: the name of the property as a string
355 ''' Returns:
356 ''' The actual value of the property
357 ''' If the property does not exist, returns Null
358 ''' Exceptions:
359 ''' ARGUMENTERROR The property does not exist
360 ''' Examples:
364 Const cstSubArgs = ""
366 If SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
367 GetProperty = Null
369 Check:
370 If SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
371 If Not SF_Utils._Validate(PropertyName, "PropertyName", V_STRING, Properties()) Then GoTo Catch
372 End If
374 Try:
375 GetProperty = _PropertyGet(PropertyName)
377 Finally:
378 SF_Utils._ExitFunction(cstThisSub)
379 Exit Function
380 Catch:
381 GoTo Finally
382 End Function ' ScriptForge.SF_L10N.GetProperty
384 REM -----------------------------------------------------------------------------
385 Public Function GetText(Optional ByVal MsgId As Variant _
386 , ParamArray pvArgs As Variant _
387 ) As String
388 ''' Get the translated string corresponding with the given argument
389 ''' Args:
390 ''' MsgId: the identifier of the string or the untranslated string
391 ''' Either - the untranslated text (MsgId)
392 ''' - the reference to the untranslated text (Context)
393 ''' - both (Context|MsgId) : the pipe character is essential
394 ''' pvArgs(): a list of arguments present as %1, %2, ... in the (un)translated string)
395 ''' to be substituted in the returned string
396 ''' Any type is admitted but only strings, numbers or dates are relevant
397 ''' Returns:
398 ''' The translated string
399 ''' If not found the MsgId string or the Context string
400 ''' Anyway the substitution is done
401 ''' Examples:
403 ''' ' Ceci est un text à inclure dans un fichier POT
405 Dim sText As String ' Output buffer
406 Dim sContext As String ' Context part of argument
407 Dim sMsgId As String ' MsgId part of argument
408 Dim vItem As POEntry ' Entry in the dictionary
409 Dim vMsgId As Variant ' MsgId split on pipe
410 Dim sKey As String ' Key of dictionary
412 Dim i As Long
417 If SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
418 sText = ""
420 Check:
421 If SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
423 End If
424 If Len(Trim(MsgId)) = 0 Then GoTo Finally
425 sText = MsgId
427 Try:
428 ' Find and load entry from dictionary
430 vMsgId = Split(MsgId, cstPipe)
431 sKey = vMsgId(0)
432 If Not _Dictionary.Exists(sKey) Then ' Not found
434 Else
435 vItem = _Dictionary.Item(sKey)
437 End If
439 ' Substitute %i placeholders
442 sText = Replace(sText, sPercent, SF_String.Represent(pvArgs(i)))
443 Next i
445 Finally:
446 GetText = sText
447 SF_Utils._ExitFunction(cstThisSub)
448 Exit Function
449 Catch:
450 GoTo Finally
451 End Function ' ScriptForge.SF_L10N.GetText
453 REM - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
454 Public Function _(Optional ByVal MsgId As Variant _
455 , ParamArray pvArgs As Variant _
456 ) As String
457 ''' Get the translated string corresponding with the given argument
458 ''' Alias of GetText() - See above
459 ''' Examples:
461 ''' ' Ceci est un text à inclure dans un fichier POT
463 Dim sText As String ' Output buffer
465 Dim i As Long
470 If SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
471 sText = ""
473 Check:
474 If SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
476 End If
477 If Len(Trim(MsgId)) = 0 Then GoTo Finally
479 Try:
480 ' Find and load entry from dictionary
481 sText = GetText(MsgId)
483 ' Substitute %i placeholders - done here, not in GetText(), because # of arguments is undefined
484 For i = 0 To UBound(pvArgs)
486 sText = Replace(sText, sPercent, SF_String.Represent(pvArgs(i)))
487 Next i
489 Finally:
490 _ = sText
491 SF_Utils._ExitFunction(cstThisSub)
492 Exit Function
493 Catch:
494 GoTo Finally
495 End Function ' ScriptForge.SF_L10N._
497 REM -----------------------------------------------------------------------------
498 Public Function Methods() As Variant
499 ''' Return the list of public methods of the L10N service as an array
501 Methods = Array( _
506 )
508 End Function ' ScriptForge.SF_L10N.Methods
510 REM -----------------------------------------------------------------------------
511 Public Function Properties() As Variant
512 ''' Return the list or properties of the Timer class as an array
514 Properties = Array( _
518 )
520 End Function ' ScriptForge.SF_L10N.Properties
522 REM -----------------------------------------------------------------------------
523 Public Function SetProperty(Optional ByVal PropertyName As Variant _
524 , Optional ByRef Value As Variant _
525 ) As Boolean
526 ''' Set a new value to the given property
527 ''' Args:
528 ''' PropertyName: the name of the property as a string
529 ''' Value: its new value
530 ''' Exceptions
531 ''' ARGUMENTERROR The property does not exist
536 If SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
537 SetProperty = False
539 Check:
540 If SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
541 If Not SF_Utils._Validate(PropertyName, "PropertyName", V_STRING, Properties()) Then GoTo Catch
542 End If
544 Try:
545 Select Case UCase(PropertyName)
546 Case Else
547 End Select
549 Finally:
550 SF_Utils._ExitFunction(cstThisSub)
551 Exit Function
552 Catch:
553 GoTo Finally
554 End Function ' ScriptForge.SF_L10N.SetProperty
556 REM =========================================================== PRIVATE FUNCTIONS
558 REM -----------------------------------------------------------------------------
559 Public Sub _Initialize(ByVal psPOFile As String _
560 , ByVal Encoding As String _
561 )
562 ''' Completes initialization of the current instance requested from CreateScriptService()
563 ''' Load the POFile in the dictionary, otherwise leave the dictionary empty
564 ''' Args:
565 ''' psPOFile: the file to load the translated strings from
568 Dim oFile As Object ' PO file handler
569 Dim sContext As String ' Collected context string
570 Dim sMsgId As String ' Collected untranslated string
571 Dim sComment As String ' Collected comment string
572 Dim sMsgStr As String ' Collected translated string
573 Dim sLine As String ' Last line read
577 Try:
578 ' Initialize dictionary anyway
580 Set _Dictionary.[_Parent] = [Me]
582 ' Load PO file
584 With SF_FileSystem
585 _POFolder = ._ConvertToUrl(.GetParentFolderName(psPOFile))
586 _Locale = .GetBaseName(psPOFile)
587 _POFile = ._ConvertToUrl(psPOFile)
588 End With
589 ' Load PO file
590 Set oFile = SF_FileSystem.OpenTextFile(psPOFile, IOMode := SF_FileSystem.ForReading, Encoding := Encoding)
591 If Not IsNull(oFile) Then
592 With oFile
594 sContext = "" : sMsgId = "" : sComment = "" : sMsgStr = ""
595 Do While Not .AtEndOfStream
596 sLine = Trim(.ReadLine())
597 ' Trivial examination of line header
598 Select Case True
599 Case sLine = ""
601 sContext = "" : sMsgId = "" : sComment = "" : sMsgStr = ""
602 iContinue = 0
604 sComment = sComment & Iif(Len(sComment) > 0, "\n", "") & Trim(Mid(sLine, 4))
605 iContinue = 0
607 sContext = SF_String.Unquote(Trim(Mid(sLine, 9)))
608 iContinue = 0
610 sMsgId = SF_String.Unquote(Trim(Mid(sLine, 7)))
611 iContinue = cstMsgId
614 iContinue = cstMsgStr
616 If iContinue = cstMsgId Then
617 sMsgId = sMsgId & SF_String.Unquote(sLine)
618 ElseIf iContinue = cstMsgStr Then
619 sMsgStr = sMsgStr & SF_String.Unquote(sLine)
620 Else
621 iContinue = 0
622 End If
623 Case Else ' Skip line
624 iContinue = 0
625 End Select
626 Loop
627 ' Be sure to store the last entry
629 .CloseFile()
630 Set oFile = .Dispose()
631 End With
632 End If
633 Else
634 _POFolder = ""
635 _Locale = ""
636 _POFile = ""
637 End If
639 Finally:
640 Exit Sub
641 End Sub ' ScriptForge.SF_L10N._Initialize
643 REM -----------------------------------------------------------------------------
644 Private Function _PropertyGet(Optional ByVal psProperty As String)
645 ''' Return the value of the named property
646 ''' Args:
647 ''' psProperty: the name of the property
649 Dim vFiles As Variant ' Array of PO-files
650 Dim i As Long
651 Dim cstThisSub As String
652 Dim cstSubArgs As String
655 cstSubArgs = ""
656 SF_Utils._EnterFunction(cstThisSub, cstSubArgs)
658 With SF_FileSystem
659 Select Case psProperty
661 If Len(_POFolder) > 0 Then _PropertyGet = ._ConvertFromUrl(_POFolder) Else _PropertyGet = ""
665 For i = 0 To UBound(vFiles)
666 vFiles(i) = SF_FileSystem.GetBaseName(vFiles(i))
667 Next i
668 Else
669 vFiles = Array()
670 End If
671 _PropertyGet = vFiles
673 _PropertyGet = _Locale
674 Case Else
675 _PropertyGet = Null
676 End Select
677 End With
679 Finally:
680 SF_Utils._ExitFunction(cstThisSub)
681 Exit Function
682 End Function ' ScriptForge.SF_L10N._PropertyGet
684 REM -----------------------------------------------------------------------------
685 Private Function _Repr() As String
686 ''' Convert the L10N instance to a readable string, typically for debugging purposes (DebugPrint ...)
687 ''' Args:
688 ''' Return:
693 End Function ' ScriptForge.SF_L10N._Repr
695 REM ============================================ END OF SCRIPTFORGE.SF_L10N
696 </script:module>