1Translation Strings Policy 2=========================== 3 4This document provides guidelines for internationalization of the Bitcoin Core software. 5 6How to translate? 7------------------ 8 9To mark a message as translatable 10 11- In GUI source code (under `src/qt`): use `tr("...")` 12 13- In non-GUI source code (under `src`): use `_("...")` 14 15No internationalization is used for e.g. developer scripts outside `src`. 16 17Strings to be translated 18------------------------- 19 20On 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 28Anything that appears to the user in the GUI is to be translated. This includes labels, menu items, button texts, tooltips and window titles. 29This includes messages passed to the GUI through the UI interface through `InitMessage`, `ThreadSafeMessageBox` or `ShowProgress`. 30 31### Command-line options 32 33Documentation for the command line options in the output of `--help` should be translated as well. 34 35Make 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 37Do not translate messages that are only shown to developers, such as those that only appear when `--help-debug` is used. 38 39General recommendations 40------------------------ 41 42### Avoid unnecessary translation strings 43 44Try not to burden translators with translating messages that are e.g. slight variations of other messages. 45In the GUI, avoid the use of text where an icon or symbol will do. 46Make 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 50Try 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 54Do 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, 55use a translatable generic message, then log the detailed message to the log. E.g. "A fatal internal error occurred, see debug.log for details". 56This 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 60Avoid 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 64There have been difficulties with use of HTML in translation strings; translators should not be able to accidentally affect the formatting of messages. 65This may sometimes be at conflict with the recommendation in the previous section. 66 67### Plurals 68 69Plurals can be complex in some languages. A quote from the gettext documentation: 70 71 In Polish we use e.g. plik (file) this way: 72 1 plik, 73 2,3,4 pliki, 74 5-21 pliko'w, 75 22-24 pliki, 76 25-31 pliko'w 77 and so on 78 79In Qt code use tr's third argument for optional plurality. For example: 80 81 tr("%n hour(s)","",secs/HOUR_IN_SECONDS); 82 tr("%n day(s)","",secs/DAY_IN_SECONDS); 83 tr("%n week(s)","",secs/WEEK_IN_SECONDS); 84 85This adds `<numerusform>`s to the respective `.ts` file, which can be translated separately depending on the language. In English, this is simply: 86 87 <message numerus="yes"> 88 <source>%n active connection(s) to Bitcoin network</source> 89 <translation> 90 <numerusform>%n active connection to Bitcoin network</numerusform> 91 <numerusform>%n active connections to Bitcoin network</numerusform> 92 </translation> 93 </message> 94 95Where it is possible try to avoid embedding numbers into the flow of the string at all. e.g. 96 97 WARNING: check your network connection, %d blocks received in the last %d hours (%d expected) 98 99versus 100 101 WARNING: check your network connection, less blocks (%d) were received in the last %n hours than expected (%d). 102 103The 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. 104 105### String freezes 106 107During a string freeze (often before a major release), no translation strings are to be added, modified or removed. 108 109This can be checked by executing `make translate` in the `src` directory, then verifying that `bitcoin_en.ts` remains unchanged. 110