1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
|
<?xml version="1.0" encoding="UTF-8"?>
<helpdocument version="1.0">
<!--
* This file is part of the LibreOffice project.
*
* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at http://mozilla.org/MPL/2.0/.
*
-->
<meta>
<topic id="SF_L10N" indexer="include" status="PUBLISH">
<title id="tit" xml-lang="en-US">ScriptForge.L10N service</title>
<filename>/text/sbasic/shared/03/sf_l10n.xhp</filename>
</topic>
</meta>
<body>
<section id="ScriptForge-sf_l10n">
<bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id571585843652319">
<bookmark_value>L10N service</bookmark_value>
</bookmark>
</section>
<section id="abstract">
<h1 id="hd_id521585843652750" xml-lang="en-US"><variable id="L10NService"><link href="text/sbasic/shared/03/sf_l10n.xhp" name="L10N service"><literal>ScriptForge</literal>.<literal>L10N</literal> service</link></variable></h1>
<paragraph role="paragraph" xml-lang="en-US" id="par_id411585843652556">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 <literal>L10N</literal> service can be used mainly to:</paragraph>
<list type="unordered">
<listitem>
<paragraph id="par_id601614351922212" role="listitem">Create POT files that can be used as templates for translation of all strings in the program.</paragraph>
</listitem>
<listitem>
<paragraph id="par_id131614352196513" role="listitem">Get translated strings at runtime for the language defined in the <literal>Locale</literal> property.</paragraph>
</listitem>
</list>
</section>
<note id="par_id971614966420419">The acronym <literal>L10N</literal> stands for Localization and refers to a set of procedures for translating software to a specific country or region.</note>
<paragraph role="paragraph" id="par_id291585843652438" xml-lang="en-US">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.</paragraph>
<paragraph role="paragraph" id="par_id181585843652814" xml-lang="en-US">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.</paragraph>
<tip id="par_id811614352321187">The <literal>L10N</literal> service is based on the GNU implementation of PO (portable object) files. To learn more about this file format, visit <link href="https://www.gnu.org/software/gettext/manual/html_node/PO-Files.html" name="GetText">GNU gettext Utilities: PO Files</link>.</tip>
<paragraph role="paragraph" id="par_id91585843652832" xml-lang="en-US">This service implements the methods listed below:</paragraph>
<list type="unordered">
<listitem>
<paragraph id="par_id1158584365237" role="listitem" xml-lang="en-US"><emph>AddText</emph>: Used by the programmer to build a set of strings that will be translated later.</paragraph>
</listitem>
<listitem>
<paragraph id="par_id81637866601151" role="listitem"><emph>AddTextsFromDialog</emph>: Extracts all strings from a <literal>Dialog</literal> service instance.</paragraph>
</listitem>
<listitem>
<paragraph id="par_id681585843652331" role="listitem" xml-lang="en-US"><emph>ExportToPOTFile</emph>: Exports the strings added by the <literal>AddText</literal> method to a POT file.</paragraph>
</listitem>
<listitem>
<paragraph id="par_id531585843652697" role="listitem" xml-lang="en-US"><emph>GetText</emph>: Gets the translated strings at runtime.</paragraph>
</listitem>
</list>
<note id="par_id361614361362393">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.</note>
<h2 id="hd_id351585843652312" xml-lang="en-US">Service invocation</h2>
<paragraph role="paragraph" id="par_id421614353247163">There are several ways to invoke the <literal>L10N</literal> 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.</paragraph>
<embed href="text/sbasic/shared/00000003.xhp#functsyntax"/>
<paragraph role="paragraph" localize="false" id="par_id481625854402332">
<input>CreateScriptService("L10N", opt foldername: str, opt locale: str, encoding: str = "UTF-8", opt locale2: str, encoding2: str = "UTF-8"): svc</input>
</paragraph>
<paragraph role="paragraph" id="par_id331585843652877"><emph>foldername</emph>: The folder containing the PO files. It must be expressed in the <literal>FileSystem.FileNaming</literal> notation.</paragraph>
<paragraph role="paragraph" id="par_id581585843652789"><emph>locale</emph>: A string in the form "la-CO" (language-COUNTRY) or in the form "la" (language) only.</paragraph>
<paragraph role="paragraph" id="par_id591646219881864"><emph>encoding</emph>: The character set to be used. The default encoding is "UTF-8".</paragraph>
<paragraph role="paragraph" id="par_id281646219882464"><emph>locale2</emph>: A string specifying the fallback locale to be used in case the PO file corresponding to the locale defined the <literal>locale</literal> parameter does not exist. This parameter is expressed in the form "la-CO" (language-COUNTRY) or "la" (language) only.</paragraph>
<paragraph role="paragraph" id="par_id881646219882951"><emph>encoding2</emph>: The character set of the fallback PO file corresponding to the <literal>locale2</literal> argument. The default encoding is "UTF-8".</paragraph>
<note id="par_id141613001281573">To learn more about the names of character sets, visit <link href="https://www.iana.org/assignments/character-sets/character-sets.xhtml" name="Character Sets">IANA's Character Set</link> page. Beware that %PRODUCTNAME does not implement all existing character sets.</note>
<embed href="text/sbasic/shared/00000003.xhp#functexample"/>
<embed href="text/sbasic/shared/00000003.xhp#In_Basic"/>
<paragraph role="paragraph" id="par_id891614358528334">The following example instantiates the <literal>L10N</literal> service without any optional arguments. This will only enable the <literal>AddText</literal> and <literal>ExportToPOTFile</literal> methods, which is useful for creating POT files.</paragraph>
<bascode>
<paragraph role="bascode" localize="false" id="bas_id891585843652669">GlobalScope.BasicLibraries.loadLibrary("ScriptForge")</paragraph>
<paragraph role="bascode" localize="false" id="bas_id821585843652135">Dim myPO As Variant</paragraph>
<paragraph role="bascode" localize="false" id="bas_id151585843652269">Set myPO = CreateScriptService("L10N")</paragraph>
</bascode>
<paragraph role="paragraph" id="par_id611614358672609">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 %PRODUCTNAME user interface, which is the same locale defined in the <literal>OfficeLocale</literal> property of the <link href="text/sbasic/shared/03/sf_platform.xhp" name="OfficeLocale_link">Platform</link> service.</paragraph>
<bascode>
<paragraph role="bascode" localize="false" id="bas_id451614358683971">Set myPO = CreateScriptService("L10N", "C:\myPOFiles")</paragraph>
</bascode>
<warning id="par_id391625855630975">The example above will result in an runtime error if the PO file corresponding to the <literal>OfficeLocale</literal> locale does not exist in the specified folder.</warning>
<paragraph role="paragraph" id="par_id321614358809763">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.</paragraph>
<bascode>
<paragraph role="bascode" localize="false" id="bas_id661614358846464">Set myPO = CreateScriptService("L10N", "C:\myPOFiles", "fr-BE", "UTF-8")</paragraph>
</bascode>
<paragraph role="paragraph" id="par_id271646220649616">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.</paragraph>
<bascode>
<paragraph role="bascode" localize="false" id="bas_id551646220782634">Set myPO = CreateScriptService("L10N", "C:\myPOFiles", "fr-BE", "UTF-8", "en-US", "UTF-8")</paragraph>
</bascode>
<paragraph role="tip" id="par_id411585843652496" xml-lang="en-US">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".</paragraph>
<paragraph role="paragraph" id="par_id171585843652545" xml-lang="en-US">It is recommended to free resources after use:</paragraph>
<bascode>
<paragraph role="bascode" localize="false" id="bas_id891585843652617">Set myPO = myPO.Dispose()</paragraph>
</bascode>
<embed href="text/sbasic/shared/00000003.xhp#In_Python"/>
<paragraph role="paragraph" id="par_id281625854773330">The examples above can be translated to Python as follows:</paragraph>
<pycode>
<paragraph role="pycode" localize="false" id="pyc_id941625854656863">from scriptforge import CreateScriptService</paragraph>
<paragraph role="pycode" localize="false" id="pyc_id51625854657247">myPO = CreateScriptService('L10N')</paragraph>
</pycode>
<pycode>
<paragraph role="pycode" localize="false" id="pyc_id761625854846211">myPO = CreateScriptService('L10N', r'C:\myPOFiles')</paragraph>
</pycode>
<pycode>
<paragraph role="pycode" localize="false" id="pyc_id311625854879209">myPO = CreateScriptService('L10N', r'C:\myPOFiles', 'fr-BE')</paragraph>
</pycode>
<pycode>
<paragraph role="pycode" localize="false" id="pyc_id981646221720301">myPO = CreateScriptService('L10N', r'C:\myPOFiles', 'fr-BE', 'UTF-8', 'en-US', 'UTF-8')</paragraph>
<paragraph role="pycode" localize="false" id="pyc_id11625855490095">myPO = myPO.Dispose()</paragraph>
</pycode>
<note id="par_id301614358956087">Several instances of the <literal>L10N</literal> service may coexist. However, each instance must use a separate directory for its PO files.</note>
<bookmark localize="false" branch="index" id="bm_id871614359551930">
<bookmark_value>L10N service;Folder</bookmark_value>
<bookmark_value>L10N service;Languages</bookmark_value>
<bookmark_value>L10N service;Locale</bookmark_value>
</bookmark>
<h2 id="hd_id561585843652465" xml-lang="en-US">Properties</h2>
<table id="tab_id711585843652120">
<tablerow>
<tablecell>
<paragraph id="par_id181585843652958" role="tablehead" xml-lang="en-US">Name</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id741585843652162" role="tablehead" xml-lang="en-US">Readonly</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id291585843652823" role="tablehead" xml-lang="en-US">Type</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id351585843652638" role="tablehead" xml-lang="en-US">Description</paragraph>
</tablecell>
</tablerow>
<tablerow>
<tablecell>
<paragraph id="par_id781585843652397" role="tablecontent" xml-lang="en-US" localize="false">Folder</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id451585843652928" role="tablecontents" xml-lang="en-US">Yes</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id351585843652874" role="tablecontents" xml-lang="en-US" localize="false">String</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id751585843652642" role="tablecontent" xml-lang="en-US">The folder containing the PO files (see the <link href="text/sbasic/shared/03/sf_filesystem.xhp#bm_id901612991354326" name="FileNaming property"><literal>FileSystem.FileNaming</literal></link> property to learn about the notation used).</paragraph>
</tablecell>
</tablerow>
<tablerow>
<tablecell>
<paragraph id="par_id161585843652104" role="tablecontent" xml-lang="en-US" localize="false">Languages</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id96158584365279" role="tablecontents" xml-lang="en-US">Yes</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id611585843652345" role="tablecontents" xml-lang="en-US" localize="false">Array</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id331585843652912" role="tablecontent" xml-lang="en-US">A zero-based array listing all the base names (without the ".po" extension) of the PO-files found in the specified <literal>Folder</literal>.</paragraph>
</tablecell>
</tablerow>
<tablerow>
<tablecell>
<paragraph id="par_id721585843652496" role="tablecontent" xml-lang="en-US" localize="false">Locale</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id961585843652589" role="tablecontents" xml-lang="en-US">Yes</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id611585843652290" role="tablecontents" xml-lang="en-US" localize="false">String</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id561585843652947" role="tablecontent" xml-lang="en-US">The currently active language-COUNTRY combination. This property will be initially empty if the service was instantiated without any of the optional arguments.</paragraph>
</tablecell>
</tablerow>
</table>
<table id="tab_id551614360519973">
<tablerow>
<tablecell colspan="3">
<paragraph id="par_id231614360519973" role="tablehead">List of Methods in the L10N Service</paragraph>
</tablecell>
</tablerow>
<tablerow>
<tablecell>
<paragraph id="par_id611614360519255" role="tablecontent" localize="false">
<link href="text/sbasic/shared/03/sf_l10n.xhp#AddText" name="AddText">AddText</link><br/>
<link href="text/sbasic/shared/03/sf_l10n.xhp#AddTextsFromDialog" name="AddTextsFromDialog">AddTextsFromDialog</link>
</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id611614360519104" role="tablecontent" localize="false">
<link href="text/sbasic/shared/03/sf_l10n.xhp#ExportToPOTFile" name="ExportToPOTFile">ExportToPOTFile</link><br/><br/>
</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id611614360518452" role="tablecontent" localize="false">
<link href="text/sbasic/shared/03/sf_l10n.xhp#GetText" name="GetText">GetText</link><br/><br/>
</paragraph>
</tablecell>
</tablerow>
</table>
<section id="AddText">
<comment> AddText ----------------------------------------------------------------------------------------------- </comment>
<bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id951585843652555">
<bookmark_value>L10N service;AddText</bookmark_value>
</bookmark>
<h2 id="hd_id191585843652902" localize="false">AddText</h2>
<paragraph role="paragraph" id="par_id1001585843652271">Adds a new entry in the list of localizable strings. It must not exist yet.</paragraph>
<paragraph role="paragraph" id="par_id641625855725050">The method returns <literal>True</literal> if successful.</paragraph>
<embed href="text/sbasic/shared/00000003.xhp#functsyntax"/>
<paragraph role="paragraph" localize="false" id="par_id241625855910866">
<input>svc.AddText(context: str = '', msgid: str = '', comment: str = ''): bool</input>
</paragraph>
<embed href="text/sbasic/shared/00000003.xhp#functparameters"/>
<paragraph role="paragraph" id="par_id391585843652753"><emph>context</emph>: The key to retrieve the translated string with the <literal>GetText</literal> method. This parameter has a default value of "".</paragraph>
<paragraph role="paragraph" id="par_id581585844419114" xml-lang="en-US"><emph>msgid</emph>: The untranslated string, which is the text appearing in the program code. It must not be empty. The <literal>msgid</literal> becomes the key to retrieve the translated string via <literal>GetText</literal> method when <literal>context</literal> is empty.</paragraph>
<paragraph role="paragraph" id="par_id311614361926844">The <literal>msgid</literal> string may contain any number of placeholders (%1 %2 %3 ...) for dynamically modifying the string at runtime.</paragraph>
<paragraph role="paragraph" id="par_id541585844475331" xml-lang="en-US"><emph>comment</emph>: Optional comment to be added alongside the string to help translators.</paragraph>
<embed href="text/sbasic/shared/00000003.xhp#functexample"/>
<paragraph role="paragraph" id="par_id461614364298440">The example below creates a set of strings in English:</paragraph>
<embed href="text/sbasic/shared/00000003.xhp#In_Basic"/>
<bascode>
<paragraph role="bascode" localize="false" id="bas_id61585843652630">myPO.AddText(, "This is a string to be included in a POT file")</paragraph>
<paragraph role="bascode" localize="false" id="bas_id61585843652141">myPO.AddText("CTX1", "A string with a context")</paragraph>
<paragraph role="bascode" localize="false" id="bas_id61585843653298">myPO.AddText(, "Provide a String value", Comment := "Do not translate the word String")</paragraph>
</bascode>
<embed href="text/sbasic/shared/00000003.xhp#In_Python"/>
<pycode>
<paragraph role="pycode" localize="false" id="pyc_id821625856085258">myPO.AddText(msgid = 'This is a string to be included in a POT file')</paragraph>
<paragraph role="pycode" localize="false" id="pyc_id821625856440025">myPO.AddText('CTX1', 'A string with a context')</paragraph>
<paragraph role="pycode" localize="false" id="pyc_id521625856443322">myPO.AddText(msgid = 'Provide a String value', comment = 'Do not translate the word String')</paragraph>
</pycode>
</section>
<section id="AddTextsFromDialog">
<comment> AddTextsFromDialog ------------------------------------------------------------------------------------- </comment>
<bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id951585843650024">
<bookmark_value>L10N service;AddTextsFromDialog</bookmark_value>
</bookmark>
<h2 id="hd_id191585843652058" localize="false">AddTextsFromDialog</h2>
<paragraph role="paragraph" id="par_id1001585843659821">Automatically extracts strings from a dialog and adds them to the list of localizable text strings. The following strings are extracted:</paragraph>
<section id="L10NDlgControls">
<list type="unordered">
<listitem>
<paragraph id="par_id621637863440015" role="listitem">The title of the dialog.</paragraph>
</listitem>
<listitem>
<paragraph id="par_id61637863440399" role="listitem">The caption of the following control types: Button, CheckBox, FixedLine, FixedText, GroupBox and RadioButton.</paragraph>
</listitem>
<listitem>
<paragraph id="par_id251637863440626" role="listitem">Static strings in ListBoxes and ComboBoxes.</paragraph>
</listitem>
<listitem>
<paragraph id="par_id811637863596791" role="listitem">The tooltip or help text displayed when the mouse hovers over the control.</paragraph>
</listitem>
</list>
</section>
<paragraph role="paragraph" id="par_id641625855723650">The method returns <literal>True</literal> if successful.</paragraph>
<note id="par_id731637863894577">The dialog from which strings will be extracted must not be open when the method is called.</note>
<paragraph role="paragraph" id="par_id911637864050221">When a <literal>L10N</literal> service instance is created from an existing PO file, use the <link href="text/sbasic/shared/03/sf_dialog.xhp#GetTextsFromL10N" name="GetTextsFromL10N">GetTextsFromL10N</link> method from the <literal>Dialog</literal> service to automatically load all translated strings into the dialog.</paragraph>
<embed href="text/sbasic/shared/00000003.xhp#functsyntax"/>
<paragraph role="paragraph" localize="false" id="par_id241625855910158">
<input>svc.AddTextsFromDialog(dialog: svc): bool</input>
</paragraph>
<embed href="text/sbasic/shared/00000003.xhp#functparameters"/>
<paragraph role="paragraph" id="par_id391585843652113"><emph>dialog</emph>: a Dialog service instance corresponding to the dialog from which strings will be extracted.</paragraph>
<embed href="text/sbasic/shared/00000003.xhp#functexample"/>
<paragraph role="paragraph" id="par_id461614364298983">The following example extracts all strings from the dialog "MyDialog" stored in the "Standard" library and exports them to a POT file:</paragraph>
<embed href="text/sbasic/shared/00000003.xhp#In_Basic"/>
<bascode>
<paragraph role="bascode" localize="false" id="bas_id61585843652225">oDlg = CreateScriptService("Dialog", "GlobalScope", "Standard", "MyDialog")</paragraph>
<paragraph role="bascode" localize="false" id="bas_id61585843652012">myPO = CreateScriptService("L10N")</paragraph>
<paragraph role="bascode" localize="false" id="bas_id61585843653117">myPO.AddTextsFromDialog(oDlg)</paragraph>
<paragraph role="bascode" localize="false" id="bas_id68163786595435">myPO.ExportToPOTFile("en-US.pot")</paragraph>
</bascode>
<embed href="text/sbasic/shared/00000003.xhp#In_Python"/>
<pycode>
<paragraph role="pycode" localize="false" id="pyc_id821625856085583">dlg = CreateScriptService("Dialog", "GlobalScope", "Standard", "Dialog1")</paragraph>
<paragraph role="pycode" localize="false" id="pyc_id821625856440596">myPO = CreateScriptService("L10N")</paragraph>
<paragraph role="pycode" localize="false" id="pyc_id521625856443065">myPO.AddTextsFromDialog(dlg)</paragraph>
<paragraph role="pycode" localize="false" id="pyc_id401637866328706">myPO.ExportToPOTFile("en-US.pot")</paragraph>
</pycode>
</section>
<section id="ExportToPOTFile">
<comment> ExportToPOTFile --------------------------------------------------------------------------------------- </comment>
<bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id471586102707389">
<bookmark_value>L10N service;ExportToPOTFile</bookmark_value>
</bookmark>
<h2 id="hd_id231586102707125" localize="false">ExportToPOTFile</h2>
<paragraph role="paragraph" id="par_id281586102707242">Exports a set of untranslated strings as a POT file.</paragraph>
<paragraph role="paragraph" id="par_id711586102939257" xml-lang="en-US">To build a set of strings you can use either a succession of <literal>AddText</literal> method calls, or by a successful invocation of the <literal>L10N</literal> service with the <literal>foldername</literal> argument present. It is also possible to use a combination of both techniques.</paragraph>
<paragraph role="paragraph" id="par_id641625855725141">The method returns <literal>True</literal> if successful.</paragraph>
<embed href="text/sbasic/shared/00000003.xhp#functsyntax"/>
<paragraph role="paragraph" localize="false" id="par_id161625856621303">
<input>svc.ExportToPOTFile(filename: str, header: str = '', encoding:str = 'UTF-8'): bool</input>
</paragraph>
<embed href="text/sbasic/shared/00000003.xhp#functparameters"/>
<paragraph role="paragraph" id="par_id31586102707537"><emph>filename</emph>: The output file in <literal>FileSystem.FileNaming</literal> notation.</paragraph>
<paragraph role="paragraph" id="par_id851586102707579" xml-lang="en-US"><emph>header</emph>: Comments that will be added on top of the generated POT file.</paragraph>
<paragraph role="paragraph" id="par_id111614364686973">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 <literal>header</literal> argument.</paragraph>
<paragraph role="paragraph" id="par_id5158610270728" xml-lang="en-US"><emph>encoding</emph>: The character set to be used (Default = "UTF-8").</paragraph>
<embed href="text/sbasic/shared/00000003.xhp#functexample"/>
<bascode>
<paragraph role="bascode" localize="false" id="bas_id761625856867301">' Basic</paragraph>
<paragraph role="bascode" localize="false" id="bas_id891586102707992">myPO.ExportToPOTFile("myFile.pot", Header := "First line of the header\nSecond line of the header")</paragraph>
</bascode>
<pycode>
<paragraph role="pycode" localize="false" id="pyc_id141625856892715"># Python</paragraph>
<paragraph role="pycode" localize="false" id="pyc_id131625856893020">myPO.ExportToPOTFile('myFile.pot', header = 'First line of the header\nSecond line of the header')</paragraph>
</pycode>
<note id="par_id581614364494235">The generated file should successfully pass the <literal>msgfmt --check</literal> GNU command.</note>
</section>
<section id="GetText">
<comment> GetText ----------------------------------------------------------------------------------------------- </comment>
<bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id131586165768747">
<bookmark_value>L10N service;GetText</bookmark_value>
</bookmark>
<h2 id="hd_id56158616576884" localize="false">GetText</h2>
<paragraph role="paragraph" id="par_id891586165768715">Gets the translated string corresponding to the given <literal>msgid</literal> argument.</paragraph>
<paragraph role="paragraph" id="par_id291614365296959">A list of arguments may be specified to replace the placeholders (%1, %2, ...) in the string.</paragraph>
<paragraph role="paragraph" id="par_id231586166181909">If no translated string is found, the method returns the untranslated string after replacing the placeholders with the specified arguments.</paragraph>
<embed href="text/sbasic/shared/00000003.xhp#functsyntax"/>
<paragraph role="paragraph" id="par_id871586352505927" xml-lang="en-US">This method can be called either by the full name <literal>GetText</literal> or by the shortcut <literal>_</literal> (a single underscore):</paragraph>
<paragraph role="paragraph" localize="false" id="par_id661625857165908">
<input>svc.GetText(msgid: str, args: any[0..*]): str</input>
</paragraph>
<paragraph role="paragraph" localize="false" id="par_id661625857165119">
<input>svc._(msgid: str, args: any[0..*]): str</input>
</paragraph>
<note id="par_id421614967136502">In the ScriptForge library, all methods starting with the "_" character are reserved for internal use only. However, the shortcut <literal>_</literal> used for <literal>GetText</literal> is the only exception to this rule, hence it can be safely used in Basic and Python scripts.</note>
<embed href="text/sbasic/shared/00000003.xhp#functparameters"/>
<paragraph role="paragraph" id="par_id51586165768525" xml-lang="en-US"><emph>msgid</emph>: 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.</paragraph>
<paragraph role="paragraph" id="par_id11614365537450">Besides using a single <literal>msgid</literal> string, this method also accepts the following formats:</paragraph>
<list type="unordered">
<listitem>
<paragraph id="par_id961614365557277" role="listitem">The <literal>context</literal> string with which the method will retrieve the <literal>msgid</literal> in the PO file, or;</paragraph>
</listitem>
<listitem>
<paragraph id="par_id981614365589866" role="listitem">A combination <literal>context|msgid</literal>, instructing the method to retrieve the <literal>msgid</literal> using specified <literal>context</literal> value. The second part of the argument is used to improve code readability.</paragraph>
</listitem>
</list>
<paragraph role="paragraph" id="par_id571586165768106" xml-lang="en-US"><emph>args</emph>: Values to be inserted into the placeholders. Any variable type is allowed, however only strings, numbers and dates will be considered.</paragraph>
<embed href="text/sbasic/shared/00000003.xhp#functexample"/>
<embed href="text/sbasic/shared/00000003.xhp#In_Basic"/>
<paragraph role="paragraph" id="par_id701614365961454">Consider the following code is running on a %PRODUCTNAME 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 <literal>GetText</literal> method:</paragraph>
<bascode>
<paragraph role="bascode" localize="false" id="bas_id171614366110835">myPO = CreateScriptService("L10N", "C:\myPOFiles\")</paragraph>
<paragraph role="bascode" localize="false" id="bas_id861586165768104">myPO.GetText("Welcome %1! Hope you enjoy this program", "John")</paragraph>
<paragraph role="bascode" localize="false" id="bas_id1001586166834936">' "¡Bienvenido John! Espero que disfrutes de este programa"</paragraph>
</bascode>
<embed href="text/sbasic/shared/00000003.xhp#In_Python"/>
<pycode>
<paragraph role="pycode" localize="false" id="pyc_id821625858120620">myPO = CreateScriptService('L10N', r"C:\myPOFiles")</paragraph>
<paragraph role="pycode" localize="false" id="pyc_id231625858122952">myPO.GetText('Welcome %1! Hope you enjoy this program', 'John')</paragraph>
<paragraph role="pycode" localize="false" id="pyc_id831625858123194"># "¡Bienvenido John! Espero que disfrutes de este programa"</paragraph>
</pycode>
</section>
<embed href="text/sbasic/shared/03/lib_ScriptForge.xhp#SF_InternalUse"/>
<section id="relatedtopics">
<embed href="text/sbasic/shared/03/sf_filesystem.xhp#FileSystemService"/>
<embed href="text/sbasic/guide/translation.xhp#translation"/>
</section>
</body>
</helpdocument>
|
