Languages

The interface speaks English. I can put it in another language with one line in config.toml, and anyone can add a language by translating one file.

Choose a language

Write language before any table of config.toml:

language = "it"

The value is a language code: two or three letters, optionally a dash and two to eight letters or digits (en, it, pt-br). Capital letters are read as small ones. A code with a dash names its own file (pt-br.toml); there is no fallback to pt, and en-us is not en. Without the key the language is en; tmail does not look at the language of the machine. A value that is not a code is an error, and tmail check says so.

Restart tmail after a change: the language is read once, when the configuration is loaded.

Where the texts come from

• en is part of the program: src/TildeMail.App/Assets/Langs/en.toml is embedded in the executable, so it is always there.
• Any other language is a file langs/<code>.toml in the configuration folder, ~/.config/tildemail/langs/ (see Files and folders). tmail creates the folder empty.
• The repository carries four files in langs/: Italian (it), French (fr), German (de) and Spanish (es). From a clone, copy the ones you want to the configuration folder: cp langs/*.toml ~/.config/tildemail/langs/.
• The release archives carry the same files in a langs/ folder: copy them to the configuration folder yourself, tmail does not read the archive. The .deb installs them in /usr/share/tildemail/langs/, and tmail reads that folder when ~/.config/tildemail/langs/ has no file for the language: language = "fr" works right after the install, and a file of your own with the same code wins, so you can copy one and change it.

The French, German and Spanish files were written by an AI assistant and no native speaker has read them yet: a correction is welcome.

A translation can be partial. A text that the file leaves out is taken from the English file, so a new version of tmail never shows an empty place.

What is translated

Everything the terminal interface and the tmail commands that read config.toml print for a person: the status line and the hints, the messages about what an action did, the reader (labels, signature line, problems), the confirmation before a message is sent, the help, the descriptions of keys and of commands, the windows (:about, :jobs, :message.log, :cache.stats) and the output of tmail check, tmail cache, tmail rules run, tmail send, tmail themes list and tmail watch. The month in the message list follows the language too (29 ott in Italian).

What stays in English:

• the log, the errors of config.toml and the errors of Lua scripts, because they quote keys and code;
• the commands that do not read config.toml: tmail gpg fetch, tmail themes show, tmail bar dump, tmail completion and tmail man, which cannot know the language;
• the steps that a rule reports (tmail rules run and tmail watch print what each rule did), because they come from the rules engine;
• the documentation, the --help of the commands and the scripts of tmail completion;
• the names of commands, keys, actions and contexts, and the names of the Lua API;
• the answer to the question before a message is sent: y or yes, in every language;
• the text of a message: the quote mark > of a reply and the line of a forwarded message belong to the mail that is sent.

Write a translation

1. Copy src/TildeMail.App/Assets/Langs/en.toml (or a file of langs/ if the language is close) to ~/.config/tildemail/langs/<code>.toml.
2. Translate the values. Do not change the keys, the tables or the placeholders.
3. Set language = "<code>" and start tmail.

The format is TOML, with one table for each area ([status], [reader], …). The key of a text is the table and the name, status.read_only.

• Placeholders. {name} marks a value that tmail fills in, such as {count} or {folder}. A translation may leave one out, but it must not add one that the English text does not have: such a text is ignored and the English one is used. A brace that does not hold a name (lower case letters, digits and underscores, starting with a letter or an underscore) is plain text.
• Plurals. A key that ends in _one is the text for exactly one thing, and _other is the text for any other number, zero included. All the languages that I ship follow that rule. {count} holds the number.
• Spaces. Some texts begin or end with a space or are aligned by spaces on purpose ("Send to ", "Author: {author}"). Keep them.
• Line breaks. \n in a text is a line break.
• Length. The status line and the hints are cut to the width of the terminal, so a short text is better than a long one.
• Connection. The three texts status.account_online, status.account_offline and status.account_error carry no mark: the status line draws the symbol of the theme before them. A file copied from an older version may still start them with ● , ○ or ! ; tmail ignores that mark, so it is not drawn twice.

What happens with a file that is wrong

A language file comes from you, so tmail reads it with care and never stops because of it. It must be a regular file of at most 256 KB. In the texts, control characters become a space and invisible characters (a bidirectional mark, a zero-width space) are removed.

Each problem is a warning. tmail check prints it with the other warnings of the configuration, and the log records it (the terminal interface leaves it there, so look in logs/ when a language does not show). The warning names the key and never quotes the text:

Problem	What tmail does
The file does not exist, is too big, is not a regular file or is not valid TOML	English for the whole interface
A key that English does not have	the text is ignored
A text with a placeholder that English does not have	the text is ignored, English is used
A value that is not a text	the value is ignored

To check a translation, set the language and run tmail check. The tests of the repository fail when one of the files of langs/ lacks a text of en.toml, or has a key or a placeholder that en.toml does not.