Improve the i18n readme (#917)
* Improve i18n readme. * Make some minor clarifications and reformatting of the i18n readme file Co-authored-by: Veronica Berglyd Olsen <1619840+vkbo@users.noreply.github.com>
This commit is contained in:
Tommy Marplatt
+79
-63
@@ -1,76 +1,91 @@
|
||||
# novelWriter Internationalisation
|
||||
# novelWriter Internationalisation (i18n)
|
||||
|
||||
The `i18n` folder contains the translation files for the Qt5 GUI. There are two types of files
|
||||
involved: the `nw_XX.ts` and the `nw_XX.qm` files. The `nw_XX.ts` files are located in the `i18n`
|
||||
folder at the root of the repository, and the `nw_XX.qm` together with the `project_XX.json` files
|
||||
are located in `novelwriter/assets/i18n`. The latter are JSON translation maps for the novelWriter
|
||||
projects, used by the Build Novel Project tool.
|
||||
Here you will find instructions for translating novelWriter to a new language or updating the
|
||||
translations for an already existing supported language.
|
||||
|
||||
**Note**
|
||||
There are two areas relevant to localisation:
|
||||
|
||||
When making a new translation, or updating an existing one, only commit the `nw_XX.ts` you have
|
||||
made changes to. The `qtlupdate` command mentioned below may modify all `nw_XX.ts` slightly, but
|
||||
please _don't_ commit those changes to the pull request.
|
||||
* The Qt5 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.
|
||||
|
||||
## Qt GUI Localisation
|
||||
|
||||
The `.qm` files are the actual files used by the application to translate the GUI into another
|
||||
language other than the default British English. The files are not generated by default. They can
|
||||
be built with:
|
||||
```bash
|
||||
python3 setup.py qtlrelease
|
||||
```
|
||||
**Important:**
|
||||
|
||||
Before adding translations to an existing translation file, you may need to update the file against
|
||||
the current source code. This is done by running the command:
|
||||
```bash
|
||||
python3 setup.py qtlupdate
|
||||
```
|
||||
When making a new translation, or updating an existing one, only commit the `nw_XX.ts` (and
|
||||
`project_XX.json`) files you have made changes to. The `qtlupdate` command mentioned below may
|
||||
modify all `nw_XX.ts` slightly, but please _don't_ commit those changes to the pull request.
|
||||
|
||||
If you want to update specific language files, you can add them as one or more arguments, like so:
|
||||
```bash
|
||||
python3 setup.py qtlupdate i18n/nw_fr.ts
|
||||
```
|
||||
## Qt5 GUI Localisation
|
||||
|
||||
To add a new language to the translation framework, run the command above with the file name of the
|
||||
new, and not yet existing, language file. Make sure the file name is 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 code. It must be a valid ISO language code, otherwise novelWriter will
|
||||
not accept the file.
|
||||
|
||||
For instance, to add a file for a language with language code "XX", run:
|
||||
```bash
|
||||
python3 setup.py qtlupdate i18n/nw_xx.ts
|
||||
```
|
||||
|
||||
This will build a new `i18n/nw_XX.ts` file for the language you just added. The file can then be
|
||||
edited with the Qt 5 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 langauge if
|
||||
prompted by Qt 5 Linguist.
|
||||
|
||||
When you're done editing, you can build the `novelwriter/assets/i18n/nw_XX.qm` file and test it in
|
||||
novelWriter. The Preferences dialog should list the newly added language, and you can select it and
|
||||
test it.
|
||||
|
||||
Please do not submit the `.qm` files to the repository. Only the `.ts` file you just added in the
|
||||
`i18n` folder is needed.
|
||||
|
||||
**Note**
|
||||
|
||||
These commands require that you have the tools Qt 5 Linguist and the PyQt5 tool `pylupdate5`
|
||||
installed on your system.
|
||||
You will need the tools Qt 5 Linguist and the PyQt5 tool `pylupdate5` installed on your system.
|
||||
|
||||
For Ubuntu/Debian, run:
|
||||
```bash
|
||||
sudo apt install qttools5-dev-tools pyqt5-dev-tools
|
||||
```
|
||||
|
||||
### 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 setup.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 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`, so its translation file will be
|
||||
`nw_fr.ts`
|
||||
|
||||
**Note:** If you run the `qtlupdate` command without a file name, it will update translation files
|
||||
for all languages.
|
||||
|
||||
### Edit the Translation File in Qt Linguist
|
||||
|
||||
The `i18n/nw_XX.ts` file can be edited with the Qt Linguist application provided by Qt 5. 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 setup.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.
|
||||
|
||||
**Note:** Please do not submit the `.qm` files to the repository. Only the `.ts` file you just
|
||||
added in the `i18n` folder is needed.
|
||||
|
||||
### Missing QtBase Translations
|
||||
|
||||
The default Qt dialogs also have translations, for instance for standard buttons like "Yes", "No",
|
||||
"Ok", "Cancel", etc. Generally, these translations files are installed with the Qt libraries on
|
||||
your system, and novelWriter will collect those translations from there. However, these
|
||||
translations are missing for many languages.
|
||||
"Ok", "Cancel", etc. Generally, these translation files are installed with the Qt libraries on your
|
||||
system, and novelWriter will collect those translations from there. However, these translations are
|
||||
missing for many languages.
|
||||
|
||||
As a starting point, there is no need to translate any entries in the `.ts` files that are under
|
||||
elements starting with the letter "Q", like "QPlatformTheme", "QWizard", etc. If these turn up in
|
||||
@@ -87,12 +102,13 @@ Projects can have a different language setting than the GUI itself. The files wi
|
||||
`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 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.
|
||||
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.json` file, rename it to
|
||||
the appropriate language coded filename, and edit it. Please use the underscore as separator if a
|
||||
language needs to be localised to a specific country under a language. The importer will for
|
||||
instance look for `en_US` first, then use `en` if it is not found. If there are no matching files,
|
||||
the project falls back to using English.
|
||||
the appropriate language coded filename, and open it in a text editor. Please use the underscore as
|
||||
separator if a language needs to be localised to a specific country under a language. The importer
|
||||
will for instance look for `en_US` first, then use `en` if it is not found. If there are no
|
||||
matching files, the project falls back to using English.
|
||||
|
||||
Reference in New Issue
Block a user