| name | localization |
| description | Use when updating KMReader translations in Localizable.xcstrings after code changes. Covers build/localize refresh, missing key discovery, context lookup, and deterministic updates through misc/translate.py. |
KMReader Localization
Maintain and complete KMReader translations in KMReader/Localizable.xcstrings.
When To Use
- The user asks to fill missing translations.
- New localized strings were introduced and need all supported languages.
- The user mentions
misc/translate.py, make localize, or missing localization entries.
Standard Workflow
Hard requirement:
make localize must be preceded by a full make build for the current code state.- Without that build, extracted localized strings data may be stale, and
Localizable.xcstrings will not be updated correctly.
Default order:
- Run a full
make build once to refresh extracted strings data.
- Sync extracted strings data into
Localizable.xcstrings.
- Fill missing translations.
Only skip the build step when it is already confirmed that the current code changes have been through a full make build. If that is not explicitly confirmed, run make build before make localize.
make build
make localize
Missing Translation Check
./misc/translate.py list
- This lists keys with missing languages.
- If output is
No missing translations found., no translation update is needed.
Per-Key Process
- Understand key meaning and UI context.
- Locate usage in code when needed to avoid semantic drift.
- Prepare all target languages first, then write once.
rg -n "String\\(localized: \"<KEY>\"\\)|\"<KEY>\"" KMReader Shared KMReaderWidgets
Optional terminology alignment source (if present):
../komga/komga-webui/src/locales/
Current supported target languages:
de, en, es, fr, it, ja, ko, ru, zh-Hans, zh-Hant
Deterministic Update Command
Always write all target languages in one command to avoid partial updates.
Run ./misc/translate.py update commands sequentially.
Do not run multiple update commands in parallel against the same KMReader/Localizable.xcstrings file, because each invocation rewrites the file and concurrent writes can corrupt the JSON.
Parallelism is only safe for read-only steps such as rg or ./misc/translate.py list.
./misc/translate.py update "<KEY>" \
--de "<German>" \
--en "<English>" \
--es "<Spanish>" \
--fr "<French>" \
--it "<Italian>" \
--ja "<Japanese>" \
--ko "<Korean>" \
--ru "<Russian>" \
--zh-hans "<Simplified Chinese>" \
--zh-hant "<Traditional Chinese>"
If Localizable.xcstrings becomes invalid JSON at any point, restore it to a known-good state first, rerun make localize, and then repeat the missing-key updates sequentially.
Quality Rules
- Preserve placeholders and format markers exactly:
%@, %d, %lld, %f, %1$@, \\n.
- Keep tone consistent with product domains (Reader, Series, Read List, Offline Sync).
- Do not modify entries where
shouldTranslate == false.
- Do not rewrite unrelated keys; only update requested or missing ones.
Final Verification
./misc/translate.py list
If missing items remain, continue until the list is empty.
