kcc/TRANSLATION.md

Translating KCC

KCC ships its UI and CLI strings in English by default, with optional translations loaded at runtime. This file documents how to keep those translations up to date when strings are added or changed.

Why translation files need maintenance

Translatable strings are wrapped in self.tr(...) or QT_TRANSLATE_NOOP('KCCGUI', ...) in the source. The English text lives in the code, but the actual translations live in translations/*.ts. If a new string is added to the code and the .ts files are not regenerated, the new string has no translation and silently falls back to English.

The .ts files are the human-editable source of truth. The .qm files are the compiled, runtime-format translations. Both are committed to the repository.

Prerequisites

• Python 3 with PySide6 installed in the active environment, which provides the pyside6-lupdate, pyside6-lrelease, and pyside6-rcc tools.
• Run all commands from the repository root.

Updating translations after adding a string

The whole flow is wrapped in one script:

./gen_translation_files.sh     # macOS / Linux
gen_translation_files.bat      # Windows

It runs three steps in order:

1. pyside6-lupdate scans the source files and updates every translations/*.ts in place.
2. pyside6-lrelease compiles each .ts into its .qm runtime file.
3. pyside6-rcc re-bundles the .qm files into KCC_rc.py, because the .qm files are loaded from the Qt resource system, not from disk.

After running the script, open the .ts files and fill in the newly added <translation> entries. lupdate extracts strings but does not translate them.

Manual equivalent

If you prefer to run the steps yourself, the script is equivalent to:

for ts in translations/*.ts; do
    pyside6-lupdate \
        kindlecomicconverter/KCC_gui.py \
        kindlecomicconverter/comic2ebook.py \
        gui/KCC.ui \
        gui/MetaEditor.ui \
        -ts "$ts"
done

for ts in translations/*.ts; do
    pyside6-lrelease "$ts" -qm "${ts%.ts}.qm"
done

pyside6-rcc gui/KCC.qrc > kindlecomicconverter/KCC_rc.py

The source file list is significant. comic2ebook.py contains the CLI-side messages; omitting it drops 20 strings (250 -> 230 extracted). The .ui files contribute the mainWindow and editorDialog contexts.

pyside6-project is intentionally not used. Its lupdate scans the whole project, which would pick up both gui/KCC.ui and the generated kindlecomicconverter/KCC_ui.py and extract the mainWindow context twice.

Generated files and what to commit

File	Generated by	Commit?
translations/*.ts	edited by hand (updated by lupdate)	yes
translations/*.qm	pyside6-lrelease	yes
kindlecomicconverter/KCC_rc.py	pyside6-rcc	yes

The .qm files are also embedded into KCC_rc.py via gui/KCC.qrc; both the standalone .qm and the resource module are kept in sync by the script.

Adding a new language

1. Generate the new source file:

   pyside6-lupdate \
       kindlecomicconverter/KCC_gui.py \
       kindlecomicconverter/comic2ebook.py \
       gui/KCC.ui \
       gui/MetaEditor.ui \
       -ts translations/kcc_xx_XX.ts
   

2. Fill in the <translation> entries.
3. Register the language in kindlecomicconverter/i18n.py in the LANGUAGES dict.
4. Add the .qm to gui/KCC.qrc under the /i18n prefix:

   <file alias="kcc_xx_XX.qm">../translations/kcc_xx_XX.qm</file>
   

5. Run gen_translation_files to compile and re-bundle the new language.

Verifying the result

• Run the script twice: the second run should produce no further changes (git diff stays empty), confirming the flow is idempotent.
• Launch KCC and switch languages via the language button; verify the UI, the metadata editor, and the conversion progress messages all switch.

Common problems

• pyside6-lupdate: command not found — PySide6 is not installed or the virtual environment is not active. Install with pip install pyside6.
• Hundreds of <location> lines changed after running lupdate — the -ts target was written outside translations/. Location paths are relative to the .ts file, so always update the files in place.
• dropping duplicate messages warnings from lrelease — a .ts file has the same (context, source) entry twice. Regenerate it with lupdate.
• Some strings stay English after switching languages — the .qm was not re-bundled into KCC_rc.py. Run gen_translation_files (step 3).
• type="vanished" entries accumulate — this is normal: lupdate marks entries whose source string is no longer found instead of deleting them. lrelease skips them, so they do not affect the runtime translations.