dash/doc/translation_strings_policy.md
MarcoFalke af00598c9a Merge #16224: gui: Bilingual GUI error messages
18bd83b1fee2eb47ed4ad05c91f2d6cc311fc9ad util: Cleanup translation.h (Hennadii Stepanov)
e95e658b8ec6e02229691a1941d688e96d4df6af doc: Do not translate technical or extremely rare errors (Hennadii Stepanov)
7e923d47ba9891856b86bc9f718cf2f1f773bdf6 Make InitError bilingual (Hennadii Stepanov)
917ca93553917251e0fd59717a347c63cdfd8a14 Make ThreadSafe{MessageBox|Question} bilingual (Hennadii Stepanov)
23b9fa2e5ec0425980301d2eebad81e660a5ea39 gui: Add detailed text to BitcoinGUI::message (Hennadii Stepanov)

Pull request description:

  This is an alternative to #15340 (it works with the `Chain` interface; see: https://github.com/bitcoin/bitcoin/pull/15340#issuecomment-502674004).
  Refs:
  - #16218 (partial fix)
  - https://github.com/bitcoin/bitcoin/pull/15894#issuecomment-487947077

  This PR:
  - makes GUI error messages bilingual: user's native language + untranslated (i.e. English)
  - insures that only untranslated messages are written to the debug log file and to `stderr` (that is not the case on master).

  If a translated string is unavailable only an English string appears to a user.

  Here are some **examples** (updated):

  ![Screenshot from 2020-04-24 17-08-37](https://user-images.githubusercontent.com/32963518/80222043-e2458780-864e-11ea-83fc-197b7121dba5.png)

  ![Screenshot from 2020-04-24 17-12-17](https://user-images.githubusercontent.com/32963518/80222051-e5407800-864e-11ea-92f7-dfef1144becd.png)

  * `qt5ct: using qt5ct plugin` message is my local environment specific; please ignore it.

  ---

  Note for reviewers: `InitWarning()` is out of this PR scope.

ACKs for top commit:
  Sjors:
    re-tACK 18bd83b1fee2eb47ed4ad05c91f2d6cc311fc9ad
  MarcoFalke:
    ACK 18bd83b1fee2eb47ed4ad05c91f2d6cc311fc9ad 🐦

Tree-SHA512: 3cc8ec44f84403e54b57d11714c86b0855ed90eb794b5472e432005073354b9e3f7b4e8e7bf347a4c21be47299dbc7170f2d0c4b80e308205ff09596e55a4f96

# Conflicts:
#	src/dashd.cpp
#	src/httpserver.cpp
#	src/index/base.cpp
#	src/init.cpp
#	src/interfaces/chain.cpp
#	src/interfaces/chain.h
#	src/interfaces/node.cpp
#	src/net.h
#	src/qt/bitcoingui.cpp
#	src/ui_interface.h
#	src/wallet/init.cpp
#	src/wallet/load.cpp
2022-04-07 10:41:24 -05:00

101 lines
4.0 KiB
Markdown

Translation Strings Policy
===========================
This document provides guidelines for internationalization of the Dash Core software.
How to translate?
------------------
To mark a message as translatable
- In GUI source code (under `src/qt`): use `tr("...")`
- 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
### GUI strings
Do not translate technical or extremely rare errors.
Anything else 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`.
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 do not 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, log messages, or messages that appear on the RPC interface. If an error is to be shown to the user,
use a translatable generic message, then log the detailed message to the log. E.g., "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 they may misunderstand the context if the messages are not self-contained.
### Avoid HTML in translation strings
There have been difficulties with the 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.
### Plurals
Plurals can be complex in some languages. A quote from the gettext documentation:
In Polish we use e.g. plik (file) this way:
1 plik,
2,3,4 pliki,
5-21 pliko'w,
22-24 pliki,
25-31 pliko'w
and so on
In Qt code, use tr's third argument for optional plurality. For example:
tr("%n hour(s)","",secs/HOUR_IN_SECONDS);
tr("%n day(s)","",secs/DAY_IN_SECONDS);
tr("%n week(s)","",secs/WEEK_IN_SECONDS);
This adds `<numerusform>`s to the respective `.ts` file, which can be translated separately depending on the language. In English, this is simply:
<message numerus="yes">
<source>%n active connection(s) to Dash network</source>
<translation>
<numerusform>%n active connection to Dash network</numerusform>
<numerusform>%n active connections to Dash network</numerusform>
</translation>
</message>
Where possible, try to avoid embedding numbers into the flow of the string at all. E.g.,
WARNING: check your network connection, %d blocks received in the last %d hours (%d expected)
versus
WARNING: check your network connection, less blocks (%d) were received in the last %n hours than expected (%d).
The second example reduces the number of pluralized words that translators have to handle from three to one, at no cost to comprehensibility of the sentence.
### 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 `dash_en.ts` remains unchanged.