====== Localization ======

Localization (a.k.a. l10n) is the process of improving the experience of non-English speaking users of a Synchronet BBS.

===== Important considerations =====
  * Although Synchronet does support UTF-8 terminals to a degree (primarily for output of non-ASCII characters), the native character set of files read/displayed by the Synchronet Terminal Server is CP437
  * The CP437 character has only limited support for non-English/Western locales, so if UNICODE characters are required to support a new language translation, that will provide additional challenges
  * Software localization usually considers other aspects of a locale beyond just language (e.g. currency indicators, number separators, etc.), but Synchronet is currently only focused on //language// localization
  * The Synchronet developers are primarily English-only speakers, so help from non-English speaking sysops and developers is very much needed for a fully-translated BBS experience
  * Although this article is in the "custom" namespace of the Synchronet Wiki, the hope is that Synchronet will eventually ship with full support for the most common non-English-speaking (but Western) users: French, Spanish, and German

===== Mechanisms =====
  * ''[[dir:ctrl]]/[[text.ini|text.lang.ini]]'' file can be used to replace ''text.dat'' strings/substrings with translated/localized strings/substrings
  * ''[[dir:text]]/[[menu_files|menu/lang/*]]'' files can be used to replace menu files with translated/localized equivalents
  * The ''[JS]'' section of ''[[dir:ctrl]]/[[text.ini|text.lang.ini]]'' files can be used to replace any JavaScript strings that are passed-to/returned-from ''gettext()'' (see ''[[dir:load]]/[[custom:javascript:lib:gettext.js]]'')

===== Command Keys =====
Many single-key commands take their key from the first letter of a ''text.dat'' string, so the key changes when that string is translated:
  * ''Yes'', ''No'', ''Quit'', ''All'', ''List'', ''Next'', and ''Previous'' (used by many prompts and menus)
  * ''Upload'', ''Download'', ''Configure'', ''Select'', and ''Pointers'' (used by the QWK menu, new in v3.22)

Menu files can display the Yes, No, and Quit keys and the five QWK menu keys with @-codes (''@YESCHAR@'', ''@QUITCHAR@'', ''@DOWNLOADCHAR@'', etc.), so a translation changes those menus without editing them. See [[atcodes|@-codes]].

==== The Quit key ====
A translated ''Quit'' word may start with the same letter as one of a prompt's other commands (e.g. Spanish "Salir" where ''S'' is already a command). As of v3.22 that no longer disables either one. Each prompt works out its Quit key from its own command keys:
  - the first letter of the ''Quit'' word, if no other command of that prompt uses it
  - otherwise ''Q''
  - otherwise no Quit letter at all: the prompt is left with Ctrl-C (or Enter, where the prompt accepts it)

The prompt displays the key it accepts. When that is not the word's first letter, the key is shown in front of the word, e.g. ''(Q)Salir''. The ''@QUITCHAR@'' code shows the same key. So the best translation of ''Quit'' can be used even when its first letter collides with a command.

A JavaScript module that combines its own command keys with the Quit key sets ''console.cmd_keys'' to those keys before displaying its prompt; ''console.quit_key'' then returns the key to accept.

==== Other key words ====
When translating the other key words, pick words whose first letters differ within the same prompt or menu. For the QWK menu those are Download, Upload, Configure, Select, and Pointers: if two of them start with the same letter, an error naming them is logged when a user enters the menu and the later command in that order cannot be used.

The ''AM'' and ''PM'' strings (new in v3.22) are shown after a 12-hour-clock time and are the suffixes accepted when a user enters an hour (e.g. ''3 pm''). A user may type either word in full or just enough of its beginning to tell the two apart (''3 p'', ''3 pm''), so the two words must differ, preferably from their first letter. Their leading space is the separator from the time: keep it by quoting the value, e.g. ''%%PM: " p.m."%%''.

===== Words in Menu Files =====
As of v3.22 the stock menu files display their most common words from ''text.dat'' strings instead of fixed English text, using the string's name as an @-code (e.g. ''@List@ files in dir''). Translating one of these words in a ''text.lang.ini'' file changes it in every stock menu, so a language needs far fewer translated menu files of its own, or none.

^ Words ^ String names ^
| Commands | ''Quit'', ''List'', ''Next'', ''Previous'', ''Select'', ''Upload'', ''Download'', ''Configure'', ''Search'', ''View'', ''Chat'', ''Reply'', ''Send'', ''Read'', ''Delete'', ''Edit'', ''Change'', ''Toggle'', ''Find'', ''Scan'', ''Forward'', ''PostVerb'' (Post), ''New'' |
| Other words | ''Main'', ''Text'', ''Sysop'', ''Transfer'', ''Area'', ''Logoff'', ''Section'', ''Node'', ''All'', ''Pointers'' |
| Nouns | ''FileNoun'', ''FilesNoun'', ''MessageNoun'', ''MessagesNoun'', ''MenuNoun'', ''MailNoun'', ''UserNoun'', ''UsersNoun'' |

Things to know when translating these words or writing menu files that use them:
  * Only the word is translated. The command key shown beside it in a menu is whatever the command shell accepts, which is usually fixed.
  * The rest of each menu line is still English, so a partly translated line is normal until a language has its own menu files.
  * A translated word is often longer than the English one. The stock menus place the text that follows each word with ''@POS:<column>@'', so columns and borders stay put while there is room, and most of them begin with ''@TRUNCATE@'', so a line that grows past the right margin is cut off there instead of wrapping. Shorter words give better-looking menus.
  * The stock ''text.es.ini'', ''text.fr.ini'' and ''text.de.ini'' files translate these words. Corrections from native speakers are welcome.

===== See Also =====
  * [[:custom:|custom index]]
  * [[text.ini]] file
  * [[custom:javascript:lib:gettext.js]]
  * [[Menu Files]]

{{tag>localization text.dat}}
