====== text.ini file ======

New in Synchronet v3.20, the ''text.ini'' file is an optional configuration file that a sysop can create in their Synchronet ''[[dir:ctrl]]'' directory to over-ride one or more string values in the ''text.dat'' file or in some JavaScript files (e.g. ''default.js'').

The ''text.ini'' method of ''text.dat'' customization has the following advantages over modifying the ''text.dat'' file itself:
  * The file won't ever be over-written by any Synchronet upgrades or updates
  * The order of the strings configured in the file is not significant, you can order/group them however you like
  * Only your modified strings need to be included in the file, any that you don't want to customize need not be included

The ''text.ini'' method of ''text.dat'' customization has the following advantages over modification using Baja or JavaScript code:
  * Any strings that may be used in [[:server:|other servers]] (besides the Terminal Server) will have your customized values
  * There's no time at which the original (pre-modified) ''text.dat'' strings might be used (e.g. before your script could execute and replace them)
  * The string syntax a bit simpler than JavaScript or Baja

===== How-to for text.dat string =====
Follow the following steps to customize your ''text.dat'' strings using the ''text.ini'' file.

==== 1. Find Text ID ====

Find a string you want to over-ride in the ''[[dir:ctrl]]/[[text.dat]]'' file. Example:
  "\1_\1?\1b\1hE-mail (User name or number): \1w"           010 Email

The "text ID" of the string ("Email" in this example) follows the double-quoted string value and the text number (10, in this example).

==== 2. Edit text.ini ====

Edit the ''[[dir:ctrl]]/text.ini'' file (create, if it doesn't already exist) using a text editor.

Add the line:

  ID: string
 
where "ID" is the text id of the text string you are customizing and double-quotes around the string value are optional but recommended:
  Email: "\1_\1?\1c\1hE-mail (User name or number): \1w"

  * A string value cannot span multiple lines in the ''text.ini'' file.
  * A string value read from the ''text.ini'' file is limited to a maximum of 1023 characters.
  * Although the double-quotes around the string value are optional, if you wish to include any initial or trailing white-space, you'll need the quotes. See [[config::ini_files#string literals]] for details.
  * Although "ID = value" syntax is also valid, if you wish to include any control characters, you'll need to use the "ID: value" syntax. See [[config::ini_files#string literals]] for details.
  * If you're wondering what we changed in this example customization, we just changed the color of the prompt from bright blue to bright cyan by changing the value of one of the included [[Ctrl-a_codes]] (for changing text attributes and performing other console control operations).

==== 3. Recycle servers ====

At the minimum, users will have to logoff and back on to see any ''text.ini'' string changes. If a server doesn't automatically recycle or otherwise reload configuration files, you may need to force a recycle or restart of the server manually.

===== How-to for JavaScript strings =====

Follow the following steps to customize JavaScript strings using the ''text.ini'' file.

The text string you wish to customize must be wrapped in a call to ''gettext()'' in a JavaScript file (e.g. ''*.js'', ''*.ssjs'', or ''*.xjs'').

  - Edit the ''[[dir:ctrl]]/text.ini'' file (create, if it doesn't already exist) using a text editor.
  - Add the ''[JS]'' section to end of the ''text.ini'' file, if it doesn't already exist.
  - Add the original string followed by equals (''='') then the new custom string, or colon ('':'') and the new custom string as a string literal
  - The JavaScript file must ''require()'' or ''load()'' the ''[[custom:javascript:lib:gettext.js]]'' load library.

Example
<code ini>
[JS]
Find Text in Messages = find yo text bro
</code>
===== Alternate Languages ===== 

Variants of the ''text.ini'' file are supported for multiple-language support: ''[[dir:ctrl]]/text.//lang//.ini''. These files use the same format as ''text.ini'', but are required to include a ''LANG'' key/value pair (to specify the //name// of the language) and will be automatically loaded upon logon for terminal server user's that have chosen that alternate language for their user account.

The alternate language ''text.//lang//.ini'' files also support the ''[JS]'' section for translated JavaScript strings.

===== See Also =====
  * [[:custom:|custom index]]
  * [[text.dat]] File
  * [[custom:javascript:lib:gettext.js]] Library
  * [[:custom:localization]]

{{tag>text.dat}}