Text¶

The Text table offers utility methods for working with text and formatting tags.

It also power's Epip custom TSK system, intended to make exporting strings for translation more easily, through the TextLib_TranslatedString class. This class contains not only the handle and default text of a string, but also contextual data that is later used to populate the public translation sheets.

Internally, Epip TSKs still use the game's handle system. However, translations are created and loaded differently, through .json files.

When lua loads, Epip looks for these translation files in the \Data\Mods\{Mod}_{GUID}\Localization\Epip\{Game language}\{Mod table}.json folder for each mod, following the load order. {Mod table}.json files are checked for every other mod present. This allows mods to provide translations or string overrides for any other mod using Epip's TSK system. Epip itself also uses this system to load the publicly contributed translations. A single mod can provide translation files for multiple mods, by creating multiple {Mod table}.json files within a language folder.

The game language IDs correspond to the ones used by the game:

English
Amlatspanish
Chinese
Chinesetraditional
Czech
French
German
Italian
Japanese
Korean
Polish
Portuguesebrazil
Russian
Spanish

It's worth noting that the game supports adding custom languages by editing the Language field in config.lsx (thereby changing the ChatLanguage global switch). Epip's system will consider such cases for loading translations.

For information on how the public translation sheets are handled, see this page.

CommonStrings¶

CommonStrings.lua contains TSKs for generic strings that are reused across many different contexts. Strings should be added here if they are of general usage and their translation won't differ across different contexts. These are accessed via the Text.CommonStrings, a raw table with no particularities.

The following VSC snippet is used to add entries to CommonStrings:

"commonstring": {
   "scope": "lua",
   "prefix": "commonstring",
   "body": [
      "Text.CommonStrings.$1 = Text.RegisterTranslatedString({",
      "   Handle = \"h${UUID/[\\-]/g/g}\",",
      "   Text = \"$1\",",
      "})",
   ],
},

TextLib Class¶

Inherits from Library.

Events and Hooks¶

GetTranslationTemplateEntry (hook)¶

@field Entry TextLib_LocalizationTemplate_Entry Hookable. Set to nil to prevent an entry from getting exported.

@field TranslatedString TextLib_TranslatedString

Methods¶

AddPadding¶

function TextLib.AddPadding(str, minLength, paddingCharacter, direction)
   -> string

Adds padding characters to a string to meet a minimum length.

@param str string

@param minLength integer

@param paddingCharacter string? Defaults to `" "`

@param direction ("front"|"back")? Defaults to `"front"`.

AppendLine¶

function TextLib.AppendLine(str1, str2)
   -> string

Joins two strings inserting a line break between them.

@param str1 string The line break is not added if this string is empty.

@param str2 string

Capitalize¶

function TextLib.Capitalize(str)
   -> string

Capitalizes the first letter of the string.

https://stackoverflow.com/a/2421746

@param str string

Contains¶

function TextLib.Contains(str, pattern)

Returns whether str contains the pattern.

@param str string

@param pattern pattern

Dump¶

function TextLib.Dump(obj, opts)
   -> string

Shorthand for Ext.DumpExport() which does not require you to explicitly define the default options (Beautify, StringifyInternalTypes, etc.)

@param obj any

@param opts unknown? TODO specify type

EqualizeSpace¶

function TextLib.EqualizeSpace(str1, str2, space)
   -> string

Concatenates 2 strings and adds enough whitespace padding inbetween them to ensure a specific length.

@param str1 string

@param str2 string

@param space integer

EscapePatternCharacters¶

function TextLib.EscapePatternCharacters(str)
   -> string

Escapes characters that have a special meaning in lua patterns.

Source: https://github.com/lua-nucleo/lua-nucleo/blob/v0.1.0/lua-nucleo/string.lua#L245-L267

@param str string

Format¶

function TextLib.Format(str, formatData)
   -> string

Format a string.

@param str string

@param formatData TextFormatData

FormatLarianTranslatedString¶

function TextLib.FormatLarianTranslatedString(handle, ...)

Resolves and formats a TSK that uses Larian's placeholder format ("[1]", "[2]" etc.).

@param handle TranslatedStringHandle

@param ... any

GenerateGUID¶

function TextLib.GenerateGUID(pattern)
   -> GUID

Generate a random GUID.

Source: https://gist.github.com/jrus/3197011

@param pattern pattern? Defaults to GUID4 pattern.

GenerateLocalizationTemplate¶

function TextLib.GenerateLocalizationTemplate(modTable, existingTemplate)
   -> TextLib_LocalizationTemplate, integer[]?, integer[]? -- Second param is new strings, third is outdated strings. Second param onwards is only returned while patching.

Generates a template file for localizing strings registered through this library.

@param modTable string? Defaults to "EpipEncounters"

@param existingTemplate TextLib_LocalizationTemplate? If present, translated strings from this template will be patched into the new one, if the reference text is still up-to-date.

GenerateTranslatedStringHandle¶

function TextLib.GenerateTranslatedStringHandle()
   -> TranslatedStringHandle

Generates a random handle in the format that Larian uses for TranslatedStringHandle.

GetCurrentLanguage¶

function TextLib.GetCurrentLanguage()
   -> string

Returns the language the game is set to.

GetStringKeyHandle¶

function TextLib.GetStringKeyHandle(stringKey)
   -> TranslatedStringHandle?

Returns the handle for a string key.

@param stringKey string

GetTranslatedString¶

function TextLib.GetTranslatedString(handle, fallBack)
   -> string -- Defaults to the handle, or fallBack if specified.

Returns the string bound to a TranslatedStringHandle, or a key.

@param handle TranslatedStringHandle|string|TextLib_TranslatedString Accepts handles or keys.

@param fallBack string?

GetTranslatedStringTranslation¶

function TextLib.GetTranslatedStringTranslation(handle, language)
   -> string? -- `nil` if the handle is not translated

Returns the translation for a handle.

@param handle TranslatedStringHandle

@param language string? Defaults to current language.

IsTranslatedStringRegistered¶

function TextLib.IsTranslatedStringRegistered(handle)
   -> boolean

Returns whether a TSK handle was registered through the Text library.

@param handle TranslatedStringHandle

Join¶

function TextLib.Join(str1, str2, separator)

Joins two strings together.

@param str1 string

@param str2 string

@param separator string? Defaults to ` `

LoadLocalization¶

function TextLib.LoadLocalization(language, filePath)

Loads a localization file. Must be in the format generated by GenerateLocalizationTemplate()

@param language string

@param filePath string

RegisterTranslatedString¶

function TextLib.RegisterTranslatedString(handle, text)
   -> TextLib_TranslatedString

Registers a translated string.

@param handle TranslatedStringHandle

@param text string

RemoveGUIDPrefix¶

function TextLib.RemoveGUIDPrefix(guid)
   -> GUID

Returns the GUID passed by parameter with any prefixes removed.

@param guid PrefixedGUID

RemoveTrailingZeros¶

function TextLib.RemoveTrailingZeros(num)
   -> string

Removes trailing zeros from a number and returns it as string.

@param num number

Replace¶

function TextLib.Replace(text, str, replacement, count)
   -> string

Replaces a plain string within text.

@param text string

@param str string

@param replacement string

@param count integer? Amount of ocurrences to replace. Defaults to `math.maxinteger`.

ReplaceLarianPlaceholders¶

function TextLib.ReplaceLarianPlaceholders(str, replacement)
   -> string

Replaces Larian placeholders (ex. "[1]", "[2]") within str.

@param str string

@param replacement (string|string[])? Defaults to empty string. If a list is passed and it's length is shorter than the amount of placeholders, the last placeholder will be used for the remaining replacements.

Resolve¶

function TextLib.Resolve(str)

Resolves a translated string, or returns the string itself if the passed parameter is already of string type.

Useful to reduce verbosity in situations where a text variable might be a TSK or a raw lua string.

@param str TextLib_TranslatedString|string

Round¶

function TextLib.Round(value, decimals)
   -> string

Returns a string representation of a number, rounded.

@param value number

@param decimals integer Defaults to 0.

SeparatePascalCase¶

function TextLib.SeparatePascalCase(str)
   -> string

Returns a string with spaces inserted inbetween PascalCase words.

@param str string

SetStringKey¶

function TextLib.SetStringKey(key, handle)

Binds a TSK to a string key.

@param key string

@param handle TranslatedStringHandle

SetTranslatedString¶

function TextLib.SetTranslatedString(handle, text)

Sets the text of a translated string.

@param handle TranslatedStringHandle

@param text string

SetTranslatedStringTranslation¶

function TextLib.SetTranslatedStringTranslation(handle, language, text)

Sets the translation of a TSK.

The handle's bound text will be updated if the game's language matches.

@param handle TranslatedStringHandle

@param language string

@param text string

Split¶

function TextLib.Split(inputstr, sep)
   -> string[]

Split a string by delimiter. Source: https://stackoverflow.com/questions/1426954/split-string-in-lua

@param inputstr string

@param sep string

SplitPascalCase¶

function TextLib.SplitPascalCase(str)
   -> string[]

Splits up a pascal-case (ex. "PascalCase") string into words.

Will split up consecutive uppercase characters.

@param str string First letter will be automatically capitalized.

Split_2¶

function TextLib.Split_2()

StripFontTags¶

function TextLib.StripFontTags(str)
   -> string

Removes all tags from a string. WIP!

@param str string

Uncapitalize¶

function TextLib.Uncapitalize(str)
   -> string

Turns the first letter of a string into lowercase.

@param str string