From 508d92c3e84078cca8918b812e671703e21ecbea Mon Sep 17 00:00:00 2001 From: Tommy Marplatt Date: Thu, 28 Oct 2021 18:38:59 -0300 Subject: [PATCH] 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> --- i18n/README.md | 142 +++++++++++++++++++++++++++---------------------- 1 file changed, 79 insertions(+), 63 deletions(-) diff --git a/i18n/README.md b/i18n/README.md index 3cfd56fc..f1412092 100644 --- a/i18n/README.md +++ b/i18n/README.md @@ -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.