Reproog/novelWriter
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Improve the i18n readme (#917)

Browse Source 
* 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
2021-10-28 18:38:59 -03:00
committed by GitHub
parent 299cde9cdf
commit 508d92c3e8
1 changed files with 79 additions and 63 deletions
Download Patch File Download Diff File Expand all files Collapse all files
i18n/README.md
+79 -63
View File
@@ -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 Here you will find instructions for translating novelWriter to a new language or updating the
involved: the `nw_XX.ts` and the `nw_XX.qm` files. The `nw_XX.ts` files are located in the `i18n` translations for an already existing supported language.
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.
**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 * The Qt5 GUI translation files, which consists of `nw_XX.ts` files. This is the bulk of the
made changes to. The `qtlupdate` command mentioned below may modify all `nw_XX.ts` slightly, but translation work.
please _don't_ commit those changes to the pull request. * 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 **Important:**
language other than the default British English. The files are not generated by default. They can
be built with:
```bash
python3 setup.py qtlrelease
```
Before adding translations to an existing translation file, you may need to update the file against When making a new translation, or updating an existing one, only commit the `nw_XX.ts` (and
the current source code. This is done by running the command: `project_XX.json`) files you have made changes to. The `qtlupdate` command mentioned below may
```bash modify all `nw_XX.ts` slightly, but please _don't_ commit those changes to the pull request.
python3 setup.py qtlupdate
```
If you want to update specific language files, you can add them as one or more arguments, like so: ## Qt5 GUI Localisation
```bash
python3 setup.py qtlupdate i18n/nw_fr.ts
```
To add a new language to the translation framework, run the command above with the file name of the You will need the tools Qt 5 Linguist and the PyQt5 tool `pylupdate5` installed on your system.
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.
For Ubuntu/Debian, run: For Ubuntu/Debian, run:
```bash ```bash
sudo apt install qttools5-dev-tools pyqt5-dev-tools 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 ### Missing QtBase Translations
The default Qt dialogs also have translations, for instance for standard buttons like "Yes", "No", 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 "Ok", "Cancel", etc. Generally, these translation files are installed with the Qt libraries on your
your system, and novelWriter will collect those translations from there. However, these system, and novelWriter will collect those translations from there. However, these translations are
translations are missing for many languages. missing for many languages.
As a starting point, there is no need to translate any entries in the `.ts` files that are under 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 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 `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 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 The files are loaded based on the language setting in the Build Novel Project tool. At the present
parts of the application use these files. Since these are used as replacement lookups, they are time, no other parts of the application use these files. Since these are used as replacement
maintained as plain JSON files. The main usage is to generate chapter headers as number words. 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 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 the appropriate language coded filename, and open it in a text editor. Please use the underscore as
language needs to be localised to a specific country under a language. The importer will for separator if a language needs to be localised to a specific country under a language. The importer
instance look for `en_US` first, then use `en` if it is not found. If there are no matching files, will for instance look for `en_US` first, then use `en` if it is not found. If there are no
the project falls back to using English. matching files, the project falls back to using English.