1Translations
2============
3
4The Bitcoin-Core project has been designed to support multiple localisations. This makes adding new phrases, and completely new languages easily achievable. For managing all application translations, Bitcoin-Core makes use of the Transifex online translation management tool.
5
6### Helping to translate (using Transifex)
7Transifex is setup to monitor the GitHub repo for updates, and when code containing new translations is found, Transifex will process any changes. It may take several hours after a pull-request has been merged, to appear in the Transifex web interface.
8
9Multiple language support is critical in assisting Bitcoin’s global adoption, and growth. One of Bitcoin’s greatest strengths is cross-border money transfers, any help making that easier is greatly appreciated.
10
11See the [Transifex Bitcoin project](https://www.transifex.com/bitcoin/bitcoin/) to assist in translations. You should also join the translation mailing list for announcements - see details below.
12
13### Writing code with translations
14We use automated scripts to help extract translations in both Qt, and non-Qt source files. It is rarely necessary to manually edit the files in `src/qt/locale/`. The translation source files must adhere to the following format:
15`bitcoin_xx_YY.ts or bitcoin_xx.ts`
16
17`src/qt/locale/bitcoin_en.ts` is treated in a special way. It is used as the source for all other translations. Whenever a string in the source code is changed, this file must be updated to reflect those changes. A custom script is used to extract strings from the non-Qt parts. This script makes use of `gettext`, so make sure that utility is installed (ie, `apt-get install gettext` on Ubuntu/Debian). Once this has been updated, `lupdate` (included in the Qt SDK) is used to update `bitcoin_en.ts`.
18
19To automatically regenerate the `bitcoin_en.ts` file, run the following commands:
20```sh
21cd src/
22make translate
23```
24
25**Example Qt translation**
26```cpp
27QToolBar *toolbar = addToolBar(tr("Tabs toolbar"));
28```
29
30### Creating a pull-request
31For general PRs, you shouldn’t include any updates to the translation source files. They will be updated periodically, primarily around pre-releases, allowing time for any new phrases to be translated before public releases. This is also important in avoiding translation related merge conflicts.
32
33When an updated source file is merged into the GitHub repo, Transifex will automatically detect it (although it can take several hours). Once processed, the new strings will show up as "Remaining" in the Transifex web interface and are ready for translators.
34
35To create the pull-request, use the following commands:
36```
37git add src/qt/bitcoinstrings.cpp src/qt/locale/bitcoin_en.ts
38git commit
39```
40
41### Creating a Transifex account
42Visit the [Transifex Signup](https://www.transifex.com/signup/) page to create an account. Take note of your username and password, as they will be required to configure the command-line tool.
43
44You can find the Bitcoin translation project at [https://www.transifex.com/bitcoin/bitcoin/](https://www.transifex.com/bitcoin/bitcoin/).
45
46### Installing the Transifex client command-line tool
47The client is used to fetch updated translations. If you are having problems, or need more details, see [https://docs.transifex.com/client/installing-the-client](https://docs.transifex.com/client/installing-the-client)
48
49`pip install transifex-client`
50
51Setup your Transifex client config as follows. Please *ignore the token field*.
52
53```ini
54nano ~/.transifexrc
55
56[https://www.transifex.com]
57hostname = https://www.transifex.com
58password = PASSWORD
59token =
60username = USERNAME
61```
62
63The Transifex Bitcoin project config file is included as part of the repo. It can be found at `.tx/config`, however you shouldn’t need to change anything.
64
65### Synchronising translations
66
67To assist in updating translations, a helper script is available in the [maintainer-tools repo](https://github.com/bitcoin-core/bitcoin-maintainer-tools). To use it and commit the result, simply do:
68
69```
70python3 ../bitcoin-maintainer-tools/update-translations.py
71git commit -a
72```
73
74**Do not directly download translations** one by one from the Transifex website, as we do a few post-processing steps before committing the translations.
75
76### Handling Plurals (in source files)
77When new plurals are added to the source file, it's important to do the following steps:
78
791. Open `bitcoin_en.ts` in Qt Linguist (included in the Qt SDK)
802. Search for `%n`, which will take you to the parts in the translation that use plurals
813. Look for empty `English Translation (Singular)` and `English Translation (Plural)` fields
824. Add the appropriate strings for the singular and plural form of the base string
835. Mark the item as done (via the green arrow symbol in the toolbar)
846. Repeat from step 2, until all singular and plural forms are in the source file
857. Save the source file
86
87### Translating a new language
88To create a new language template, you will need to edit the languages manifest file `src/qt/bitcoin_locale.qrc` and add a new entry. Below is an example of the English language entry.
89
90```xml
91<qresource prefix="/translations">
92    <file alias="en">locale/bitcoin_en.qm</file>
93    ...
94</qresource>
95```
96
97**Note:** that the language translation file **must end in `.qm`** (the compiled extension), and not `.ts`.
98
99### Questions and general assistance
100
101If you are a translator, you should also subscribe to the mailing list, https://groups.google.com/forum/#!forum/bitcoin-translators. Announcements will be posted during application pre-releases to notify translators to check for updates.
102