WklTexts

Dim myWklTexts As New WklTexts

Returns the texts of an application by key, in the language the WKL components speak in this Access session.

None

WklTexts is an object, not a control; see Localize an application. The texts are records of the table USysWklTexts in the current database - one record per key and language, with the fields TextKey (Text, 255), Language (Text, 10) and TextValue (Long Text) - and files of the language folder i18n next to it (Folder). The table travels with the database, so an ACCDE and the Access Runtime need nothing else; a file of the folder overrides the record with the same key and language.

• Language. The language is the first of the application model, Office and Windows that the application has texts in, in any language (Choose the language of the components); the WKL components speak it when it is one of their five. Language sets another language for the session.
• Fallbacks. A key without a text in the language falls back to its neutral text (language neutral), then to English; a key without any text appears as [key] - visible on the screen instead of an empty caption. Missing lists every fallback, so a test can fail on them.
• Keys. Keys are compared without regard to case, as Access compares names. Dotted keys (orders.title) keep related texts together.
• Standard texts. Keys that start with wkl. are the standard texts of the components, reviewed in every language and the same in every WKL application: wkl.ok, wkl.cancel, wkl.yes, wkl.no, wkl.save, wkl.open, wkl.close, wkl.new, wkl.edit, wkl.delete, wkl.add, wkl.remove, wkl.rename, wkl.copy, wkl.cut, wkl.paste, wkl.undo, wkl.redo, wkl.refresh, wkl.search, wkl.filter, wkl.sort, wkl.print, wkl.export, wkl.import, wkl.help, wkl.settings, wkl.back, wkl.next, wkl.finish, wkl.apply, wkl.more, wkl.error, wkl.warning, wkl.information, wkl.question, wkl.confirm-delete (“Do you want to delete {0}?”) and wkl.save-changes. A record of the application with such a key is ignored.
• Captions with keys. A caption written as @ followed by a dotted key (@orders.title) names a text instead of holding one; @@ at the start writes a literal @. WKL controls and the ribbon model show the text of such captions themselves; Localize does it for the native controls of an open form or report, CaptionText for a caption value used as data.
• When the table is read. Once per database and Access session; Reload reads it again after the application changed it.
• Outside Access (a UserForm in Excel or Word) there is no database: the texts come from the folder set with Folder; without one the standard texts work in the language of Windows and every other key appears as [key].

Created with New WklTexts or CreateObject.

' A message in the language of the session; the table USysWklTexts holds
' orders.saved = "{0} orders saved." (en) and "{0} Aufträge gespeichert." (de).
Dim texts As New WklTexts
MsgBox texts.Text("orders.saved", 3), vbInformation, texts.Text("wkl.information")

None

Function Text(ByVal Key As String, ParamArray Args() As Variant) As String

Returns the text of a key in the language of the session, with its placeholders filled. This is the default member: texts("orders.title") is the same as texts.Text("orders.title").

Return value: String – The text; the English text when the language has none; [Key] when no language has one.

Placeholders take .NET format items: {0:N2} for a number with two decimals, {1:d} for a short date. Numbers and dates follow the regional settings of Windows, as everything Access formats, not the language of the text. A text whose placeholders do not read - a translation that lost a brace - is returned unfilled instead of raising an error. Without values the text is returned as it is, placeholders included.

Default member: it can be left out, as in myWklTexts(...) for myWklTexts.Text(...).

None

Declared by WklTexts.

Function Has(ByVal Key As String) As Boolean

Returns whether a key has a text.

Return value: Boolean – True when the application has a text for the key in any language, or the key is a standard text.

None

None

Declared by WklTexts.

Property Get Language() As String
Property Let Language(RHS As String)

Gets or sets the language of the session.

None

Property value: String – A language code such as de, fr or sl-SI (a regional code counts as its language), or neutral for the neutral texts. An empty text returns to the measured language.

Setting a language puts it ahead of the application model, Office and Windows until Access ends, for the application texts, and for the WKL components when it is one of their five: a test can run in Slovenian on a German Office. Windows that are already open (a designer, a form with a WKL control) keep their texts until they are opened again. A value that is no language code raises wkeInvalidValue and leaves the language unchanged.

Read/write.

None

Declared by WklTexts.

Property Get Languages() As String

Returns the languages the application has texts for.

None

Property value: String – The codes separated by commas: neutral first, then en, de, sl, hr, it, then further languages in alphabetical order, for example neutral,en,de,fr; empty when there are no application texts.

Read-only.

None

Declared by WklTexts.

Property Get Missing() As String

Returns the keys that were asked for and had no text in the language asked for.

None

Property value: String – One line per key and language, key language, in the order they occurred, lines separated by CR LF; empty when every text was found.

A key that fell back to English is listed as well, so an incomplete translation shows up in a test run. The list starts empty when the texts are read, also after Reload.

Read-only.

None

Declared by WklTexts.

Sub Reload()

Reads the table USysWklTexts of the current database again, after the application changed it while running.

None

None

None

Declared by WklTexts.

Function Localize(ByVal Target As Object) As Long

Replaces the captions of an open form or report that name a text by the text in the language of the session.

Return value: Long – The number of property values replaced.

Changed are Caption of the form or report and Caption, ControlTipText and StatusBarText of every control in its Controls collection whose value is @ followed by a dotted key; @@x becomes @x, any other value stays. A subform is a form of its own and localizes itself in its own Open event. Call it once per opening: afterwards the properties hold the texts. In Design view the method raises error &H80040306 and changes nothing, because the texts would be saved with the object in place of the keys.

Private Sub Form_Open(Cancel As Integer)
    Dim texts As New WklTexts
    texts.Localize Me
End Sub

Declared by WklTexts.

Function CaptionText(ByVal Caption As String) As String

Returns a caption value resolved by the rule of the WKL controls.

Return value: String – The text of the key for @key, @x for @@x, the value unchanged otherwise.

For captions an application uses as data - copied into a table, a report or a message - so they read as the controls show them.

None

Declared by WklTexts.

Property Get Folder() As String
Property Let Folder(RHS As String)

Gets or sets the language folder.

None

Property value: String – The full path of the folder with the files <language>.json and neutral.json. In Access the default is i18n next to the current database; outside Access there is none until code sets one. An empty text returns to the default.

Each file is a JSON object of keys and texts in UTF-8, the format of the text files of the WKL Office SDK. A text of the folder overrides the record of USysWklTexts with the same key and language, so a translation can be corrected or a language added after delivery without a new build. A file that cannot be read, or whose name is no language code, is skipped; the other texts still apply. Setting the folder reads the texts again. Whoever can write to the folder changes the texts of the application.

Read/write.

' In an Excel workbook (Workbook_Open): the texts lie in the folder i18n next to the workbook.
Dim texts As New WklTexts
texts.Folder = ThisWorkbook.Path & "\i18n"

Declared by WklTexts.