[VerusCoin.git] / doc / translation_strings_policy.md

*** Warning: This document has not been updated for Zcash and may be inaccurate. ***

Translation Strings Policy
===========================

This document provides guidelines for internationalization of the Bitcoin Core software.

How to translate?
------------------

To mark a message as translatable

- In non-GUI source code (under `src`): use `_("...")`

No internationalization is used for e.g. developer scripts outside `src`.

Strings to be translated
-------------------------

On a high level, these strings are to be translated:

- GUI strings, anything that appears in a dialog or window

- Command-line option documentation

### GUI strings

Anything that appears to the user in the GUI is to be translated. This includes labels, menu items, button texts, tooltips and window titles.
This includes messages passed to the GUI through the UI interface through `InitMessage`, `ThreadSafeMessageBox` or `ShowProgress`.

### Command-line options

Documentation for the command line options in the output of `--help` should be translated as well.

Make sure that default values do not end up in the string, but use string formatting like `strprintf(_("Threshold for disconnecting misbehaving peers (default: %u)"), 100)`. Putting default values in strings has led to accidental translations in the past, and forces the string to be retranslated every time the value changes.

Do not translate messages that are only shown to developers, such as those that only appear when `--help-debug` is used.

General recommendations
------------------------

### Avoid unnecessary translation strings

Try not to burden translators with translating messages that are e.g. slight variations of other messages.
In the GUI, avoid the use of text where an icon or symbol will do.
Make sure that placeholder texts in forms don't end up in the list of strings to be translated (use `<string notr="true">`).

### Make translated strings understandable

Try to write translation strings in an understandable way, for both the user and the translator. Avoid overly technical or detailed messages

### Do not translate internal errors

Do not translate internal errors, or log messages, or messages that appear on the RPC interface. If an error is to be shown to the user,
use a generic message, then log the detailed message to the log. E.g. "Error: A fatal internal error occurred, see debug.log for details".
This helps troubleshooting; if the error is the same for everyone, the likelihood is increased that it can be found using a search engine.

### Avoid fragments

Avoid dividing up a message into fragments. Translators see every string separately, so may misunderstand the context if the messages are not self-contained.

### Avoid HTML in translation strings

There have been difficulties with use of HTML in translation strings; translators should not be able to accidentally affect the formatting of messages.
This may sometimes be at conflict with the recommendation in the previous section.

### String freezes

During a string freeze (often before a major release), no translation strings are to be added, modified or removed.

This can be checked by executing `make translate` in the `src` directory, then verifying that `bitcoin_en.ts` remains unchanged.
Commit	Line	Data
82dd46a6 JG	1	* Warning: This document has not been updated for Zcash and may be inaccurate. *
82dd46a6 JG	2
213f257a WL	3	Translation Strings Policy
	4	===========================
	5
4fbfebea	6	This document provides guidelines for internationalization of the Bitcoin Core software.
213f257a WL	7
	8	How to translate?
	9	------------------
	10
	11	To mark a message as translatable
	12
213f257a WL	13	- In non-GUI source code (under `src`): use `_("...")`
	14
	15	No internationalization is used for e.g. developer scripts outside `src`.
	16
	17	Strings to be translated
	18	-------------------------
	19
	20	On a high level, these strings are to be translated:
	21
	22	- GUI strings, anything that appears in a dialog or window
	23
	24	- Command-line option documentation
	25
	26	### GUI strings
	27
	28	Anything that appears to the user in the GUI is to be translated. This includes labels, menu items, button texts, tooltips and window titles.
	29	This includes messages passed to the GUI through the UI interface through `InitMessage`, `ThreadSafeMessageBox` or `ShowProgress`.
	30
	31	### Command-line options
	32
	33	Documentation for the command line options in the output of `--help` should be translated as well.
	34
	35	Make sure that default values do not end up in the string, but use string formatting like `strprintf(_("Threshold for disconnecting misbehaving peers (default: %u)"), 100)`. Putting default values in strings has led to accidental translations in the past, and forces the string to be retranslated every time the value changes.
	36
	37	Do not translate messages that are only shown to developers, such as those that only appear when `--help-debug` is used.
	38
	39	General recommendations
	40	------------------------
	41
	42	### Avoid unnecessary translation strings
	43
	44	Try not to burden translators with translating messages that are e.g. slight variations of other messages.
	45	In the GUI, avoid the use of text where an icon or symbol will do.
	46	Make sure that placeholder texts in forms don't end up in the list of strings to be translated (use `<string notr="true">`).
	47
	48	### Make translated strings understandable
	49
	50	Try to write translation strings in an understandable way, for both the user and the translator. Avoid overly technical or detailed messages
	51
	52	### Do not translate internal errors
	53
	54	Do not translate internal errors, or log messages, or messages that appear on the RPC interface. If an error is to be shown to the user,
	55	use a generic message, then log the detailed message to the log. E.g. "Error: A fatal internal error occurred, see debug.log for details".
	56	This helps troubleshooting; if the error is the same for everyone, the likelihood is increased that it can be found using a search engine.
	57
	58	### Avoid fragments
	59
	60	Avoid dividing up a message into fragments. Translators see every string separately, so may misunderstand the context if the messages are not self-contained.
	61
	62	### Avoid HTML in translation strings
	63
	64	There have been difficulties with use of HTML in translation strings; translators should not be able to accidentally affect the formatting of messages.
	65	This may sometimes be at conflict with the recommendation in the previous section.
	66
	67	### String freezes
	68
	69	During a string freeze (often before a major release), no translation strings are to be added, modified or removed.
	70
	71	This can be checked by executing `make translate` in the `src` directory, then verifying that `bitcoin_en.ts` remains unchanged.