Veronica Berglyd Olsen
130 lines
5.6 KiB
Markdown
130 lines
5.6 KiB
Markdown
# novelWriter Internationalisation (i18n)
|
|
|
|
The maintenance of translations has been moved to the Crowdin service. The translation strings can
|
|
be edited there at the [novelWriter project page](https://crowdin.com/project/novelwriter).
|
|
However, please read the Translation Guidelines section below.
|
|
|
|
You can still use the manual approach listed below, and then upload the file through the website's
|
|
interface. The translation strings for that language will then be updated and queued for approval.
|
|
|
|
To verify a language file translated through the Crowdin tool, download and extract it into the
|
|
`i18n` folder in the novelWriter source and follow the instructions in
|
|
[Generate an Updated Translation File](#generate-an-updated-translation-file) below.
|
|
|
|
|
|
# Translation Guidelines
|
|
|
|
When contributing translations, keep the following things in mind.
|
|
|
|
* For descriptive labels and dialog boxes, make sure you do _not_ change the meaning of the text
|
|
when you translate it from English. The user must receive the same instructions or information
|
|
regardless of language. This is important, otherwise the documentation will be inconsistent with
|
|
the user interface and it will become a lot more difficult to handle user issues and questions.
|
|
* If you think a label or description is misleading or incomplete, please file an issue report. The
|
|
correct way to handle such changes is to change the text in the code first, which will then be
|
|
forwarded to _all_ translators such that the GUI is consistent across all languages.
|
|
* For very short labels, like button labels. it may be fine to replace the word with a similar
|
|
word, but only as long as the user understands what it is supposed to do. Some buttons and tabs
|
|
have limited space. If necessary, it is OK to use abbreviations.
|
|
|
|
|
|
# Direct Approach Using Qt Linguist
|
|
|
|
Here you will find instructions for translating novelWriter to a new language directly using Qt
|
|
Linguist, or updating the translations for an already existing supported language.
|
|
|
|
There are two areas relevant to localisation:
|
|
|
|
* The Qt GUI translation files, which consists of `nw_XX.ts` files. This is the bulk of the
|
|
translation work.
|
|
* The `project_XX.json` files. See [Project Localisation](#project-localisation) below.
|
|
|
|
The `XX` in the file name corresponds to the language and country code for the translation. For
|
|
instance `en_GB` for British English.
|
|
|
|
|
|
## Qt GUI Localisation
|
|
|
|
You will need the translation tool Qt Linguist on your system.
|
|
|
|
For Ubuntu/Debian, run:
|
|
|
|
```bash
|
|
sudo apt install qttools5-dev-tools
|
|
```
|
|
|
|
See also [Qt Linguist Manual: Translators](https://doc.qt.io/qt-6/linguist-translators.html).
|
|
|
|
|
|
### Workflow
|
|
|
|
Here's an overview of the localisation workflow:
|
|
|
|
1. First, create a new branch off of `main`, and there, generate a new `nw_XX.ts` translation file.
|
|
1. Load the translation file in Qt Linguist. Translate and save your changes.
|
|
1. Generate the `nw_XX.qm` file.
|
|
1. Run the application and verify your changes. Iterate from step 2.
|
|
1. Once finished, commit your changes and submit your pull request.
|
|
|
|
When you want to translate new changes, again create a new branch off of `main` and re-generate the
|
|
translation file. Continue from step 2.
|
|
|
|
|
|
### Generate an Updated Translation File
|
|
|
|
The `i18n` folder at the root of the repository contains the `nw_XX.ts` translation files.
|
|
|
|
Whether to add a new language to the translation framework, or to update the file against the
|
|
current source code, you must first run the `qtlupdate` command:
|
|
|
|
```bash
|
|
python3 pkgutils.py qtlupdate i18n/nw_XX.ts
|
|
```
|
|
|
|
The file name must be in the correct format. All translation files must be located in the `i18n`
|
|
folder, start with `nw_` and end with `.ts`. In between goes the language and country code. It must
|
|
be a valid ISO language code, otherwise novelWriter will not accept the file.
|
|
|
|
For instance, the French translation uses the language code `fr_FR`, so its translation file will
|
|
be `nw_fr_FR.ts`
|
|
|
|
Note: The `qtlupdate` command needs the `lupdate` tool provided by PyQt6, which uses the latest
|
|
TS file format. On Debian/Ubuntu it is provided by the package `pyqt6-dev-tools`.
|
|
|
|
|
|
### Edit the Translation File in Qt Linguist
|
|
|
|
The `i18n/nw_XX.ts` file can be edited with the Qt Linguist application provided by Qt. This is
|
|
by far easier than manually editing the `.ts` file.
|
|
|
|
Please select "English" and "United Kingdom" as the _source_ language if prompted by Qt Linguist.
|
|
|
|
|
|
### Verify Your Translation
|
|
|
|
The application does not use `.ts` files directly. The `novelwriter/assets/i18n/nw_XX.qm` files are
|
|
the actual files used to translate the GUI into another language other than the default British
|
|
English. These files are not generated by default, but they can be built with:
|
|
|
|
```bash
|
|
python3 pkgutils.py qtlrelease
|
|
```
|
|
|
|
You can now test the translation in novelWriter. The Preferences dialog should list the newly added
|
|
language, so go ahead and select it.
|
|
|
|
|
|
## Project Localisation
|
|
|
|
Projects can have a different language setting than the GUI itself. The files with format
|
|
`project_XX.json` in `novelwriter/assets/i18n` are simple translation maps for text that goes into
|
|
the exported documents generated by the Build Novel Project tool.
|
|
|
|
The files are loaded based on the language setting in the Build Novel Project tool. At the present
|
|
time, no other parts of the application use these files. Since these are used as replacement
|
|
lookups, they are maintained as plain JSON files. The main usage is to generate chapter headers as
|
|
number words.
|
|
|
|
Adding new translations for these files is easy. Just copy the `project_en_GB.json` file, rename it
|
|
to the appropriate language coded filename, and open it in a text editor and edit the content.
|